Commit | Line | Data |
---|---|---|
d37eb365 AJ |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename wine.info | |
4 | @settitle Wine Reference Manual | |
5 | @iftex | |
6 | @afourpaper | |
7 | @end iftex | |
8 | @c %**end of header | |
9 | ||
10 | @ifinfo | |
11 | @format | |
12 | START-INFO-DIR-ENTRY | |
692389d0 | 13 | * wine: (wine.info). Windows on Unix. |
d37eb365 AJ |
14 | END-INFO-DIR-ENTRY |
15 | @end format | |
16 | @end ifinfo | |
17 | ||
18 | @iftex | |
19 | @c @finalout | |
20 | @end iftex | |
21 | ||
22 | @ifinfo | |
692389d0 DR |
23 | This file documents Wine, a system providing Microsoft Windows compatibility |
24 | to Unix. | |
d37eb365 AJ |
25 | |
26 | @c | |
a11d7b1a | 27 | Copyright @copyright{} 1997,1998 The Wine authors. @* |
641ee76a AJ |
28 | @xref{Authors, The Wine Authors, The Wine Authors}, |
29 | for a list of the copyright holders. | |
d37eb365 AJ |
30 | |
31 | Permission is granted to make and distribute verbatim | |
32 | copies of this manual provided the copyright notice and | |
33 | this permission notice are preserved on all copies. | |
34 | ||
35 | @ignore | |
36 | Permission is granted to process this file through TeX | |
37 | and print the results, provided the printed document | |
38 | carries a copying permission notice identical to this | |
39 | one except for the removal of this paragraph (this | |
40 | paragraph not being relevant to the printed manual). | |
41 | ||
42 | @end ignore | |
43 | Permission is granted to copy and distribute modified | |
44 | versions of this manual under the conditions stated in | |
45 | the section entitled ``License, Warranty, and Authors of Wine''. | |
46 | ||
47 | @sp 4 | |
a11d7b1a AJ |
48 | FIXME: X11 and POSIX trademarks. @* |
49 | UNIX is a registered trademark of the Open Group. | |
670cdc45 AJ |
50 | Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are |
51 | registered trademarks of Microsoft Corporation. | |
52 | NT is a trademark of Northern Telecom Limited. | |
53 | C++Builder is a trademark of Borland International, Inc. | |
54 | Postscript is a registered trademark of Adobe Systems Inc. | |
55 | Other trademarks are the property of their respective owners, which may | |
56 | be registered in certain jurisdictions. | |
d37eb365 AJ |
57 | @end ifinfo |
58 | ||
59 | @c begin chapters on right pages | |
60 | @setchapternewpage odd | |
61 | ||
62 | @titlepage | |
d37eb365 | 63 | |
a11d7b1a AJ |
64 | @title{The Wine Reference Manual} |
65 | @subtitle{Edition 0.0.5, February 1998} | |
d37eb365 | 66 | |
a11d7b1a | 67 | @author{The Wine Team} |
d37eb365 AJ |
68 | @c The following two commands start the copyright page. |
69 | @page | |
70 | @vskip 0pt plus 1filll | |
71 | ||
a11d7b1a | 72 | Copyright @copyright{} 1997, 1998 The Wine authors. @* |
641ee76a AJ |
73 | @xref{Authors, The Wine Authors, The Wine Authors}, |
74 | for a list of the copyright holders. | |
d37eb365 AJ |
75 | |
76 | Permission is granted to make and distribute verbatim | |
77 | copies of this manual provided the copyright notice and | |
78 | this permission notice are preserved on all copies. | |
79 | ||
80 | Permission is granted to copy and distribute modified | |
81 | versions of this manual under the conditions stated in | |
82 | the section entitled ``License, Warranty, and Authors of Wine''. | |
83 | ||
84 | @sp 4 | |
85 | FIXME: UNIX and POSIX trademarks. @* | |
670cdc45 AJ |
86 | X11 @* |
87 | Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are | |
88 | registered trademarks of Microsoft Corporation. | |
89 | NT is a trademark of Northern Telecom Limited. | |
90 | C++Builder is a trademark of Borland International, Inc. | |
91 | Postscript is a registered trademark of Adobe Systems Inc. | |
92 | Other trademarks are the property of their respective owners, which may | |
93 | be registered in certain jurisdictions. | |
d37eb365 AJ |
94 | @end titlepage |
95 | ||
96 | ||
97 | ||
98 | @c | |
99 | @c SETTINGS, DEFINES, MACROS | |
100 | @c | |
101 | ||
102 | @c Edit this macro manually in the above parts of the document | |
103 | @macro winemanualversion | |
a11d7b1a | 104 | 0.0.4 |
d37eb365 AJ |
105 | @end macro |
106 | ||
107 | @c Edit this macro manually in the above parts of the document | |
108 | @macro winemanualdate | |
a11d7b1a | 109 | February 1998 |
d37eb365 AJ |
110 | @end macro |
111 | ||
112 | @c Edit this macro manually into the TeX titlepage | |
641ee76a | 113 | @macro winemanualtitle |
d37eb365 AJ |
114 | The Wine Reference Manual |
115 | @end macro | |
116 | ||
641ee76a AJ |
117 | @c |
118 | @macro winelib | |
119 | Winelib | |
120 | @end macro | |
d37eb365 AJ |
121 | @c |
122 | @c MICROSOFT | |
123 | @c | |
124 | ||
a11d7b1a | 125 | @c FIXME: automatic trademark reference |
d37eb365 AJ |
126 | @macro mswindows |
127 | MS-Windows | |
128 | @end macro | |
129 | ||
a11d7b1a | 130 | @c FIXME: automatic trademark reference |
d37eb365 AJ |
131 | @c spell it always the same |
132 | @macro WIN32 | |
133 | WIN32 | |
134 | @end macro | |
641ee76a AJ |
135 | @macro WIN16 |
136 | WIN16 | |
137 | @end macro | |
d37eb365 | 138 | |
a11d7b1a | 139 | @c FIXME: automatic trademark reference |
d37eb365 AJ |
140 | @macro WINNT |
141 | Windows NT | |
142 | @end macro | |
143 | ||
a11d7b1a | 144 | @c FIXME: automatic trademark reference |
670cdc45 AJ |
145 | @macro WINNT40 |
146 | Windows NT 4.0 | |
147 | @end macro | |
148 | ||
a11d7b1a | 149 | @c FIXME: automatic trademark reference |
d37eb365 AJ |
150 | @macro WIN95 |
151 | Windows 95 | |
152 | @end macro | |
153 | ||
154 | ||
155 | @c | |
156 | @c THE OTHERS | |
157 | @c | |
a11d7b1a | 158 | @c FIXME: automatic trademark reference |
d37eb365 AJ |
159 | @macro unix |
160 | UNIX | |
161 | @end macro | |
162 | ||
a11d7b1a | 163 | @c FIXME: automatic trademark reference |
d37eb365 AJ |
164 | @macro posix |
165 | POSIX | |
166 | @end macro | |
641ee76a AJ |
167 | |
168 | @macro unicode | |
169 | Unicode | |
170 | @end macro | |
171 | ||
172 | @macro ascii | |
173 | ASCII | |
174 | @end macro | |
175 | ||
d37eb365 AJ |
176 | @c |
177 | @c THIS MANUAL | |
178 | @c | |
179 | ||
180 | @c flag out differences to MS-Windows | |
181 | @macro windiff | |
182 | @emph{Differences to @mswindows{}:} @* | |
183 | @end macro | |
184 | ||
185 | @macro windiffnone | |
186 | @windiff{} | |
187 | No differences known. | |
188 | @end macro | |
189 | ||
190 | @c tell whether function is present in Windows 95 and/or NT | |
191 | @macro winconf | |
192 | @emph{Conformance to @mswindows{}:} @* | |
193 | @end macro | |
194 | ||
195 | @macro winconfall | |
196 | @winconf{} | |
197 | Present in @WIN95{} and @WINNT{}. | |
198 | @end macro | |
199 | ||
200 | @c give information about completion | |
201 | @macro completion | |
202 | @emph{Completion status:} @* | |
203 | @end macro | |
204 | ||
205 | @macro completionnone | |
206 | @completion{} | |
207 | Not yet implemented. | |
208 | @end macro | |
209 | ||
641ee76a AJ |
210 | @c |
211 | @c MACROS FOR FUNCTIONS, TYPES, CONSTANTS, VARIABLES | |
212 | @c | |
d37eb365 | 213 | |
641ee76a AJ |
214 | @c Constants in the WIN32 API |
215 | @macro defvr_cw32 {restofline} | |
216 | @defvr Constant \restofline\ | |
217 | @end macro | |
218 | @macro defvrx_cw32 {restofline} | |
219 | @defvrx Constant \restofline\ | |
220 | @end macro | |
d37eb365 | 221 | |
641ee76a AJ |
222 | @c Functions in the WIN32 API |
223 | @macro deftypefn_w32 {restofline} | |
224 | @deftypefn {WIN32 function} \restofline\ | |
225 | @end macro | |
226 | @macro deftypefnx_w32 {restofline} | |
227 | @deftypefnx {WIN32 function} \restofline\ | |
228 | @end macro | |
d37eb365 | 229 | |
641ee76a AJ |
230 | @c Types in the WIN32 API |
231 | @macro deftp_w32 {restofline} | |
232 | @deftp {Data type} \restofline\ | |
233 | @end macro | |
234 | @macro deftpx_w32 {restofline} | |
235 | @deftpx {Data type} \restofline\ | |
236 | @end macro | |
d37eb365 | 237 | |
641ee76a AJ |
238 | @c Macros internal to Wine |
239 | @macro deffn_winemacro {restofline} | |
240 | @deffn {Wine internal macro} \restofline\ | |
241 | @end macro | |
242 | @macro deffnx_winemacro {restofline} | |
243 | @deffn {Wine internal macro} \restofline\ | |
244 | @end macro | |
245 | ||
246 | @c Constants internal to Wine | |
247 | @macro defvr_cwine {restofline} | |
248 | @defvr {Wine internal constant} \restofline\ | |
249 | @end macro | |
250 | @macro defvrx_cwine {restofline} | |
251 | @defvrx {Wine internal constant} \restofline\ | |
252 | @end macro | |
d37eb365 AJ |
253 | |
254 | ||
255 | @c | |
256 | @c TOP NODE | |
257 | @c | |
258 | @ifinfo | |
259 | @node Top, Copying, (dir), (dir) | |
260 | @top Wine | |
261 | ||
262 | This is edition @winemanualversion{}, last updated @winemanualdate{}, | |
263 | of @winemanualtitle{}. | |
264 | ||
692389d0 DR |
265 | Wine provides both source and binary compatibility with Microsoft Windows. |
266 | The Wine API is designed to be as compatible as possible with various | |
267 | implementations of the Windows APIs. The Wine library allows porting | |
268 | Windows source to Unix, and a program loader allows unaltered Windows binaries | |
269 | to be run on Unix. | |
d37eb365 | 270 | |
692389d0 | 271 | Wine is free software. Wine is still under development. |
d37eb365 AJ |
272 | @end ifinfo |
273 | ||
274 | @menu | |
275 | * Copying:: License, Warranty, and Authors of Wine. | |
276 | * Introduction:: A short overview. | |
f90efa9c | 277 | * Wine Design:: The design of Wine. |
d37eb365 | 278 | * Reference Manual:: The Wine reference manual. |
641ee76a | 279 | * Installation:: Installing and configuring Wine. |
d37eb365 AJ |
280 | * The Wine Project:: How to contribute to Wine. |
281 | * Concept Index:: Index of concepts and names. | |
282 | * Type Index:: Index of types and type qualifiers. | |
283 | * Function Index:: Index of functions and function-like | |
284 | macros. | |
641ee76a AJ |
285 | * Variable Index:: Index of variables, constants, and |
286 | variable-like macros. | |
d37eb365 AJ |
287 | * File Index:: Index of programs and files. |
288 | @end menu | |
289 | ||
290 | @node Copying, Introduction, Top, Top | |
291 | ||
641ee76a | 292 | @unnumbered License, Warranty, and Authors of Wine |
d37eb365 AJ |
293 | @cindex copying conditions for Wine |
294 | @cindex conditions for copying Wine | |
295 | @cindex Wine copying conditions | |
296 | ||
297 | The Wine license, warranty, and list of authors together form the | |
298 | copyright for Wine. Read these sections carefully. | |
299 | ||
300 | @menu | |
301 | * License:: The Wine license. | |
302 | * Warranty:: Wine comes with no warranty. | |
303 | * Authors:: The persons that contributed to Wine. | |
304 | @end menu | |
305 | ||
306 | @node License, Warranty, , Copying | |
307 | @cindex Wine license | |
308 | @cindex license of Wine | |
309 | ||
310 | @unnumberedsec The Wine License | |
311 | Wine is distributed under the following copyright. | |
312 | ||
313 | @quotation | |
314 | @include LICENSE | |
315 | @end quotation | |
316 | ||
317 | @node Warranty, Authors, License, Copying | |
318 | @cindex Wine warranty | |
319 | @cindex warranty of Wine | |
320 | ||
321 | @unnumberedsec The Wine Warranty | |
322 | ||
323 | @quotation | |
324 | @include WARRANTY | |
325 | @end quotation | |
326 | ||
327 | @node Authors, , Warranty, Copying | |
328 | @cindex Wine authors | |
329 | @cindex authors of Wine | |
330 | @cindex copyright holders of Wine | |
331 | @cindex Wine copyright holders | |
332 | ||
333 | @unnumberedsec The Wine Authors | |
334 | ||
335 | @quotation | |
336 | @include AUTHORS | |
337 | @end quotation | |
338 | ||
339 | These persons also hold the copyright on Wine. | |
340 | ||
341 | The overall coordination is done by @* | |
342 | Alexandre Julliard @* | |
343 | @email{julliard@@lrc.epfl.ch} | |
344 | ||
345 | ||
346 | ||
f90efa9c | 347 | @node Introduction, Wine Design, Copying, Top |
d37eb365 AJ |
348 | @chapter Introduction |
349 | ||
641ee76a AJ |
350 | @strong{What is Wine?} |
351 | ||
f90efa9c AJ |
352 | Wine is a Windows-compatibility layer for Unix and X11. |
353 | The Wine system consists of several thing: | |
641ee76a AJ |
354 | @enumerate |
355 | @item | |
f90efa9c AJ |
356 | An API, sometimes referred to as the Wine API, |
357 | designed to be as compatible as possible with the | |
358 | @mswindows{} API | |
359 | @item | |
360 | A library, called @winelib{}, which implements this API | |
641ee76a | 361 | @item |
692389d0 DR |
362 | A binary compatibility layer |
363 | acts as a program loader for native Windows binaries. | |
364 | It works for both 16 and 32 bit Intel binaries, and | |
f90efa9c AJ |
365 | provides all the appropriate translation between 16 and 32 bit code |
366 | (thunking). Real mode interrupts are also supported, and their | |
367 | functionality is implemented in @winelib{}. | |
641ee76a | 368 | |
641ee76a AJ |
369 | @end enumerate |
370 | ||
f90efa9c | 371 | @strong{System Requirements} |
641ee76a | 372 | |
641ee76a | 373 | |
f90efa9c AJ |
374 | Wine provides binary support for Intel code on Intel hardware only. |
375 | Neither hardware emulation | |
376 | nor non-Intel binaries are supported. | |
377 | @winelib{} should be possible to port to just about any Unix system. | |
641ee76a AJ |
378 | |
379 | Currently, you must have one of: | |
380 | @itemize @bullet | |
381 | @item | |
382 | Linux version 0.99.13 or above | |
383 | @item | |
384 | NetBSD-current | |
385 | @item | |
386 | FreeBSD-current or FreeBSD 1.1 | |
f90efa9c AJ |
387 | @item |
388 | OpenBSD/i386 2.1 or later | |
389 | @item | |
390 | Solaris x86 2.5 or later | |
641ee76a AJ |
391 | @end itemize |
392 | You need X11, and you must have @file{libXpm} installed on your system. | |
393 | ||
394 | @strong{Availability} | |
395 | ||
f90efa9c AJ |
396 | Wine is free software; the license is BSD-style. Basically, you can do |
397 | anything with it, except claim that you wrote it. | |
641ee76a AJ |
398 | @xref{Copying}, for more information. |
399 | ||
641ee76a AJ |
400 | @strong{Further information} |
401 | ||
402 | You should consult the files @file{README}, @file{ANNOUNCE}, | |
403 | @file{RELEASE-NOTES}, @file{BUGS}, @file{LICENSE}, and @file{WARRANTY}, | |
404 | in the root directory of the Wine distribution. | |
405 | ||
f90efa9c AJ |
406 | The Wine USENET newsgroup @url{news:comp.emulators.ms-windows.wine} |
407 | is useful for both Wine developers and Wine users. The Wine home page | |
408 | is @url{http://www.winehq.com/}. | |
409 | ||
410 | @node Wine Design, Reference Manual, Introduction, Top | |
411 | @chapter Wine Design | |
412 | ||
413 | @subsection The Wine Graphics Driver Model | |
414 | ||
415 | Wine, like Windows, abstracts drawing code so that applications may access | |
416 | a wide variety of devices, from different kinds of graphics cards, | |
417 | X displays and printers, using a single unified graphics model. | |
418 | This model is referred to as GDI: _G_raphics _D_river _I_nterface. | |
419 | This section discusses the Wine implementation of GDI. | |
420 | There are 61 functions in the Wine graphics model, including Arc, BitBlt, | |
421 | Chord, etc. For a complete list and prototypes, see the definition | |
422 | of DC_FUNCTIONS in [include/gdi.h]. | |
423 | ||
424 | Wine, as of 2Q1998, has three native drivers: these provide support | |
425 | for rendering to X displays, metafiles, and Win16 native printer drivers. | |
426 | As far as Wine is concerned, a driver | |
427 | simply consists of a name and a table of function pointers | |
428 | (see [graphics/driver.c]). These functions | |
429 | are the driver's implementation of the various Wine graphics | |
430 | operations (the GDI). Wine maintains a linked list of all drivers which | |
431 | register themselves with Wine, as well as a ``generic'' | |
432 | driver. Currently, the X11 driver registers itself as DISPLAY, the | |
433 | win16 driver registers itself as the generic driver, and the metafile | |
434 | driver doesn't register itself at all. | |
435 | ||
436 | @subsubsection How a driver function gets invoked | |
437 | ||
438 | All drawing by Wine applications | |
439 | is done in terms of a Device Context (DC). | |
440 | Before an application can draw, it must create a DC, and all drawing calls | |
441 | must pass a handle to the DC they wish to draw to. | |
442 | [include/gdi.h] defines several structures relating to DCs, including | |
443 | DC, WIN_DC_INFO, and DeviceCaps. The DeviceCaps structure is at the lowest | |
444 | level: it holds | |
445 | information relating to specifics of the graphics display | |
446 | hardware and associated | |
447 | driver. | |
448 | WIN_DC_INFO holds information about several device independent | |
449 | modes the DC can be in, plus a pointer to DeviceCaps. | |
450 | Finally, | |
451 | the DC structure is the toplevel structure usually passed around. | |
452 | It holds viewport information, a pointer to WIN_DC_INFO, and a | |
453 | pointer to the function table to be used while rendering that DC. | |
454 | This function table is filled at the time of creating the DC. | |
455 | ||
456 | @c Modes | |
457 | ||
458 | @c Some discussion of the various modalities available to a DC would be nice. | |
459 | ||
460 | @c Coordinate Systems | |
461 | ||
462 | @c Some discussion of the maze of coordinate systems would also be nice. | |
463 | ||
464 | @c Device Coordinates | |
465 | ||
466 | @c Logical Coordinates | |
467 | ||
468 | @c World transforms | |
469 | ||
470 | ||
471 | @subsubsection The X11 driver | |
472 | ||
473 | As a part of the Wine loading process, | |
474 | X11DRV_Init in [graphics/x11drv/init.c] is called. | |
475 | This initializes various aspects of the X11 driver and | |
476 | registers it as DISPLAY. This function first | |
477 | calls initialization procedures for various parts of the X11 driver. | |
478 | It then | |
479 | creates and | |
480 | fills a static DeviceCaps | |
481 | structure to be used for every X11 DC. | |
482 | Finally, it fills the table of GDI functions to be used for X11 | |
483 | rendering and registers itself as ``DISPLAY''. | |
484 | ||
485 | @subsubsection The Metafile Driver | |
486 | ||
487 | The metafile driver is unusual, in that it is not a driver for any | |
488 | kind of display device, but rather a mechanism which allows using | |
489 | the Wine graphics model as a file format for saving graphics. | |
490 | The advantage of this is that it allows using identical formats for | |
491 | saving pictures as is actually used to display them; it is analogous | |
492 | to Display PostScript. | |
493 | ||
494 | The metafile driver is invoked explicitly by the application. The | |
495 | application calls CreateMetaFile() to create a special DC for recording | |
496 | graphics drawing operations in a metafile. Any drawing operations | |
497 | performed in this DC are not drawn physically anywhere, they are | |
498 | instead stored in the metafile. The DC is explicitly destroyed by a | |
499 | call to CloseMetaFile(), which also finishes writing the metafile. | |
500 | Metafiles may be written either to a file or to memory. Later, the | |
501 | metafile can be rendered (in a physical DC) by PlayMetaFile(). | |
502 | ||
503 | The way that this works is that device contexts contain a pointer | |
504 | to the function lookup table for drawing operations appropriate for | |
505 | that device. | |
506 | ||
507 | Not all functions in the Wine graphics model are relevant to metafiles, but | |
508 | some relevant but rarely used functions are unimplemented. | |
509 | ||
510 | @subsubsection The WIN16 Driver | |
511 | ||
512 | WIN16DRV_Init is called by MAIN_EmulatorInit, and registers the | |
513 | WIN16DRV function table WIN16DRV_Funcs [graphics/win16drv/init.c] | |
514 | for the generic driver. The WIN16 driver is designed to load | |
515 | specified native Windows printer drivers. I don't understand | |
516 | how the whole scheme works, | |
517 | start studying what happens when a printer DC is | |
518 | created via WIN16DRV_CreateDC. | |
519 | ||
520 | If a DC is created explicitly, via the | |
521 | CreateDC() call, the driver name is specified explicitly and Wine | |
522 | finds the appropriate driver by leafing through its table of registered | |
523 | drivers. Metafile DCs can only be created by the CreateMetaFile function. | |
524 | ||
525 | Alternatively, most of the time, the DISPLAY driver is invoked | |
526 | implicitly. | |
527 | The application creates a window with | |
528 | CreateWindow(). If the CS_CLASSDC or CS_OWNDC flag is passed, a new DC | |
529 | is created and saved for the window in a structure called DCE, which holds | |
530 | a DC, a clipping region, and flags. Whenever the application wants to | |
531 | paint in that window, it calls GetDC(hwnd), which returns the DC in the | |
532 | DCE saved in the window. | |
533 | ||
534 | If neither of those flags are used, the window gets a DCE assigned to it | |
535 | from a pool of DCEs created during Wine initialization and temporarily | |
536 | assigned during the GetDC() call. | |
537 | All DCEs, whether part of the Wine DC pool or created by request of a window, | |
538 | use the ``DISPLAY'' driver. | |
539 | ||
540 | ||
541 | @node Reference Manual, Installation, Wine Design, Top | |
d37eb365 AJ |
542 | |
543 | @menu | |
7692b583 | 544 | * @WIN32{} Reference Manual:: The @WIN32{} function calls and data types. |
d37eb365 AJ |
545 | * Resources and INI files:: How to determine the appearance and |
546 | behaviour of Wine programs. | |
7692b583 | 547 | * Metafiles--Icons--Bitmaps:: FIXME missing. |
d37eb365 AJ |
548 | * Debugging:: Debugging Wine. |
549 | * Programs:: Programs written to run in/with Wine. | |
550 | * Tools:: Programs to support Wine. | |
551 | @end menu | |
552 | ||
553 | @node @WIN32{} Reference Manual, Resources and INI files, , Reference Manual | |
554 | @chapter The @WIN32{} Reference Manual | |
555 | ||
556 | @menu | |
557 | * Kernel Objects:: How the Wine kernel keeps information. | |
558 | * Processes and Threads:: Job control and management in Wine. | |
559 | * Users and Groups:: Security in Wine. | |
560 | * Date and Time:: Functions for getting the date and time | |
561 | and for conversion between formats. | |
562 | * System Information:: Getting information about the hardware | |
563 | and software the system runs on. | |
564 | * Memory Management:: How your programs get memory from | |
565 | Wine. | |
566 | * I/O Facilities:: Input/Output in Wine. | |
d37eb365 AJ |
567 | * Communication:: How processes can communicate. |
568 | * Windows and Graphics:: GUI functions of @WIN32{}. | |
569 | * Errors and Exceptions:: How your program can report errors. | |
641ee76a | 570 | (messaging) |
d37eb365 AJ |
571 | * Resources:: Functions for dealing with resources. |
572 | * The Registry:: FIXME missing. | |
573 | * Dynamic Link Libraries:: Functions for dealing with DLL's. | |
574 | @end menu | |
575 | ||
576 | @node Kernel Objects, Processes and Threads, , @WIN32{} Reference Manual | |
577 | @section Kernel Objects | |
578 | ||
579 | ||
580 | @node Processes and Threads, Users and Groups, Kernel Objects, @WIN32{} Reference Manual | |
581 | @section Processes and Threads | |
582 | ||
583 | @node Users and Groups, Date and Time, Processes and Threads, @WIN32{} Reference Manual | |
584 | @section Users and Groups | |
585 | ||
586 | @node Date and Time, System Information, Users and Groups, @WIN32{} Reference Manual | |
587 | @section Date and Time | |
588 | ||
589 | This section describes functions for manipulating dates and times. This | |
590 | includes the current time, the creation or manipulation times of files | |
591 | and other objects, and conversion between different time | |
592 | representations. | |
593 | ||
594 | @menu | |
595 | * File Times:: Creation and manipulation times of files. | |
596 | @end menu | |
597 | ||
598 | @node File Times, , , Date and Time | |
599 | @subsection File Times | |
600 | ||
601 | @menu | |
602 | * Type FILETIME:: The data structure used for specifying | |
603 | file times. | |
604 | * Compare File Times:: Compare two file times. | |
d37eb365 AJ |
605 | @end menu |
606 | ||
607 | @c | |
608 | @c *** struct FILETIME *** | |
609 | @c | |
610 | @node Type FILETIME, Compare File Times, , File Times | |
641ee76a | 611 | @subsubsection Type FILETIME |
d37eb365 AJ |
612 | |
613 | @noindent | |
614 | File times in Wine are specified by the data type @code{FILETIME}, | |
615 | defined in @file{windows.h}. | |
641ee76a AJ |
616 | @deftp_w32 FILETIME |
617 | @deftpx_w32 LPFILETIME | |
d37eb365 AJ |
618 | This is the data type for specifying file times. The file times are |
619 | stored with 64 bit precision. The actual data type is a structure with | |
641ee76a | 620 | two 32-bit values which are interpreted as the low and high parts of a |
d37eb365 AJ |
621 | 64-bit value. This value gives a time measured in a granularity of 100 |
622 | nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In | |
623 | Wine, this 64-bit value is signed, with the sign taken from the high | |
624 | part. The lower part is used as unsigned. | |
625 | ||
626 | The definition of @code{FILETIME} reads: | |
627 | @example | |
641ee76a | 628 | typedef struct |
d37eb365 AJ |
629 | @{ |
630 | INT32 dwLowDateTime; | |
631 | INT32 dwHighDateTime; | |
641ee76a | 632 | @} FILETIME, *LPFILETIME; |
d37eb365 AJ |
633 | @end example |
634 | ||
635 | @cindex epoch in file time | |
636 | The @code{FILETIME} structure may be used to hold absolute or relative | |
637 | times. Absolute times are given as the number of 100 nanoseconds | |
638 | intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated | |
639 | Universal Time, which is GMT, Greenwich Mean Time). This might be | |
640 | called the @dfn{epoch} for file times. With a signed 64-bit value, this | |
641 | representation covers absolute times of 29247 years around the epoch. | |
641ee76a AJ |
642 | To convert this type to local time, use the function |
643 | @code{FileTimeToLocalFileTime}. | |
d37eb365 AJ |
644 | |
645 | @windiff{} | |
646 | In @mswindows{}, the elements of the structure are apparently of type | |
647 | @code{DWORD}. Whether the full 64 bit value is interpreted as signed or | |
648 | unsigned I do not know. | |
649 | @end deftp | |
650 | ||
651 | @c | |
652 | @c *** CompareFileTime *** | |
653 | @c | |
641ee76a | 654 | @node Compare File Times, , Type FILETIME, File Times |
d37eb365 AJ |
655 | |
656 | @noindent | |
657 | The Wine function @code{CompareFileTime} compares two file times, and | |
658 | returns whether the first time is less than, equal to, or greater than | |
659 | the second file time. It is defined in @file{windows.h}. | |
641ee76a | 660 | @deftypefn_w32 LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})} |
d37eb365 AJ |
661 | This function returns @code{1}, if @var{time_1} is greater than |
662 | @var{time_2}, @code{-1} if it is less, and @code{0} if both times are | |
663 | equal. | |
664 | ||
665 | @winconfall{} | |
666 | ||
667 | @windiffnone{} | |
668 | ||
669 | @completionnone{} | |
670 | @end deftypefn | |
671 | ||
641ee76a AJ |
672 | @node System Information, Memory Management, Date and Time, @WIN32{} Reference Manual |
673 | @section System Information | |
674 | ||
675 | @node Memory Management, I/O Facilities, System Information, @WIN32{} Reference Manual | |
676 | @section Memory Management | |
677 | ||
678 | @node I/O Facilities, Communication, Memory Management, @WIN32{} Reference Manual | |
679 | @section I/O Facilities | |
680 | ||
681 | This section describes all input/output of a process, except for two | |
682 | topics: communication with other processes, and communication with the | |
683 | windowing system. | |
684 | ||
685 | @menu | |
686 | * I/O on Files:: Accessing the contents of files. | |
687 | * File System Interface:: Functions for manipulating files as a whole. | |
688 | @end menu | |
689 | ||
690 | @node I/O on Files, File System Interface, , I/O Facilities | |
691 | @subsection I/O on Files | |
692 | ||
693 | @node File System Interface, , I/O on Files, I/O Facilities | |
694 | @subsection File System Interface | |
695 | ||
696 | These functions are concerned with operating on files themselves, rather | |
697 | than on their contents. | |
698 | ||
699 | @menu | |
700 | * Type BY_HANDLE_FILE_INFORMATION:: The data structure used to | |
701 | specify file information. | |
702 | * File attributes:: The file attributes flags in | |
703 | a file information structure. | |
704 | * Getting file information:: These functions let you obtain | |
705 | information about a file. | |
706 | @end menu | |
707 | ||
708 | @node Type BY_HANDLE_FILE_INFORMATION, File attributes, , File System Interface | |
709 | @subsubsection The file information structure | |
710 | ||
711 | The file information structure of Wine is used to obtain information | |
712 | about files. It is declared in the header @file{winedows.h}. | |
713 | @deftp_w32 BY_HANDLE_FILE_INFORMATION | |
714 | This is the data type for specifying information about files as objects | |
715 | of the file system. It contains the following members: | |
716 | @table @code | |
717 | @item int dwFileAttributes | |
718 | @cindex file attributes in file information | |
719 | @cindex attributes of file in file information | |
720 | @xref{File attributes}, for details. | |
721 | @item FILETIME ftCreationTime | |
722 | @cindex creation time in file information | |
723 | @cindex time of file creation in file information | |
724 | The time when the file was created. | |
725 | @xref{Type FILETIME}, for details. | |
726 | @item FILETIME ftLastAccessTime | |
727 | @cindex access time in file information | |
728 | @cindex time of file access in file information | |
729 | The time when the file was last accessed. | |
730 | @xref{Type FILETIME}, for details. | |
731 | @item FILETIME ftLastWriteTime | |
732 | @cindex write time in file information | |
733 | @cindex time of last file write in file information | |
734 | The time when the file was last written to. | |
735 | @xref{Type FILETIME}, for details. | |
736 | @item int dwVolumeSerialNumber | |
737 | @cindex serial number of volume in file information | |
738 | @cindex volume number (serial) in file information | |
739 | The serial number of the volume containing the file. In Wine, | |
740 | currently 0. | |
741 | @item int nFileSizeHigh | |
742 | @cindex file size in file information | |
743 | @cindex size of file in file information | |
744 | A 32 bit value which contains the high part of the 64 bit file size. | |
745 | @item int nFileSizeLow | |
746 | A 32 bit value which contains the low part of the 64 bit file size. | |
747 | @item int nNumberOfLinks | |
748 | @cindex hard links number in file information | |
749 | @cindex links (number of hard) in file information | |
750 | This is the number of hard links to the file. In a file system which | |
751 | does not support hard links, this is 1. | |
752 | @item int nFileIndexHigh | |
753 | @cindex inode number in file information | |
754 | @cindex file index in file information | |
755 | @cindex index of file in file information | |
756 | A 32 bit value which contains the high part of the 64 bit file | |
757 | index. The file index is a unique number for a file on a volume. | |
758 | This identifier cannot change while the file is opened by a process. | |
759 | Together with the volume number, the file index is a unique | |
760 | identifier for the file. This can be used by an application to check | |
761 | whether two handles refer to the same file. Wine currently uses the | |
762 | inode number for the file index. | |
763 | @item int nFileIndexLow | |
764 | A 32 bit value which contains the low part of the 64 bit file index. | |
765 | @end table | |
766 | ||
767 | The definition of @code{BY_HANDLE_FILE_INFORMATION} reads: | |
768 | @example | |
769 | typedef struct | |
770 | @{ | |
771 | int dwFileAttributes; | |
772 | FILETIME ftCreationTime; | |
773 | FILETIME ftLastAccessTime; | |
774 | FILETIME ftLastWriteTime; | |
775 | int dwVolumeSerialNumber; | |
776 | int nFileSizeHigh; | |
777 | int nFileSizeLow; | |
778 | int nNumberOfLinks; | |
779 | int nFileIndexHigh; | |
780 | int nFileIndexLow; | |
781 | @} BY_HANDLE_FILE_INFORMATION ; | |
782 | @end example | |
783 | ||
784 | The @code{BY_HANDLE_FILE_INFORMATION} structure can be obtained by the | |
785 | @code{GetFileInformationByHandle} function (@pxref{Getting file information}, for | |
786 | details). | |
787 | ||
788 | @windiff{} | |
789 | In @mswindows{}, the @code{int} elements of the structure are apparently | |
790 | of type @code{DWORD}. | |
791 | @end deftp | |
792 | ||
793 | @node File attributes, Getting file information, Type BY_HANDLE_FILE_INFORMATION, File System Interface | |
794 | @subsubsection The file attributes in a file information structure | |
795 | ||
796 | The file attributes in a file information structure and in other structures | |
797 | are a logical @emph{or} of one or more of the following constants: | |
798 | ||
799 | @defvr_cw32 FILE_ATTRIBUTE_READONLY | |
800 | The file is a read-only file. (Wine value: 0x0001). | |
801 | @end defvr | |
802 | @defvr_cw32 FILE_ATTRIBUTE_HIDDEN | |
803 | The file is a hidden file. Files in Wine do not have this attribute. (Wine value: | |
804 | 0x0002). | |
805 | @end defvr | |
806 | @defvr_cw32 FILE_ATTRIBUTE_SYSTEM | |
807 | The file belongs to the operating system. Files in Wine do not have this | |
808 | attribute. (Wine value: 0x0004). | |
809 | @end defvr | |
810 | @defvr_cw32 FILE_ATTRIBUTE_LABEL | |
811 | This is not present in the @mswindows{} API. (Wine value: 0x0008). | |
812 | @end defvr | |
813 | @defvr_cw32 FILE_ATTRIBUTE_DIRECTORY | |
814 | The file is a directory. (Wine value: 0x0010). | |
815 | @end defvr | |
816 | @defvr_cw32 FILE_ATTRIBUTE_ARCHIVE | |
670cdc45 AJ |
817 | The file is an archive file. Currently, all non-directory files are |
818 | reported by Wine to have this attribute. This attribute is normally set | |
819 | by @mswindows{} to indicate that a file is to be archived; when the file | |
820 | is archived, the flag is cleared. (Wine value: 0x0020). | |
641ee76a AJ |
821 | @end defvr |
822 | @defvr_cw32 FILE_ATTRIBUTE_NORMAL | |
823 | The file does not have any other attributes set. This value must be used | |
824 | alone. In Wine, normal files are reported as archive files. (Wine value: | |
825 | 0x0080). | |
826 | @end defvr | |
827 | @defvr_cw32 FILE_ATTRIBUTE_TEMPORARY | |
828 | The file is used as a temporary storage. Files in Wine do not have this | |
829 | attribute. (Wine value: 0x0100). | |
830 | @end defvr | |
831 | @defvr_cw32 FILE_ATTRIBUTE_ATOMIC_WRITE | |
832 | This is reserved for future use. Files in Wine do not have this | |
833 | attribute. (Wine value: 0x0200). | |
834 | @end defvr | |
835 | @defvr_cw32 FILE_ATTRIBUTE_XACTION_WRITE | |
836 | This is reserved for future use. Files in Wine do not have this | |
837 | attribute. (Wine value: 0x0400). | |
838 | @end defvr | |
839 | @defvr_cw32 FILE_ATTRIBUTE_COMPRESSED | |
840 | The file is compressed. Files in Wine do not have this attribute. (Wine | |
841 | value: 0x0800). | |
842 | @end defvr | |
843 | ||
844 | @node Getting file information, , File attributes, File System Interface | |
845 | @subsubsection Getting file information | |
846 | ||
847 | The functions in this section describe how to get information about | |
848 | files. | |
849 | ||
850 | @c | |
851 | @c *** GetFileInformationByHandle | |
852 | @c | |
853 | @noindent | |
854 | The Wine function @code{GetFileInformationByHandle} returns a file | |
855 | information structure. It is defined in @file{windows.h}. | |
856 | ||
857 | @deftypefn_w32 BOOL GetFileInformationByHandle (@w{HFILE32 @var{file},} @w{BY_HANDLE_FILE_INFORMATION *@var{info})} | |
858 | This function obtains for the specified @var{file} the file information, | |
859 | and stores it in @var{info}. The file information contains the file | |
860 | attributes, the file times, the volume serial number, the file size, the | |
861 | number of links, and a unique file identifier. The function returns | |
862 | @code{TRUE} on success, @code{FALSE} on failure. | |
863 | ||
864 | @winconfall{} | |
865 | ||
866 | @windiff{} | |
867 | The Wine function can of course only give back information that is | |
868 | accessible in the @unix{} file system. File times are produced in a | |
869 | granularity of full seconds. Most file attributes are not present in the | |
870 | @unix{} file system. @xref{File attributes}, for details. The volume | |
871 | serial number is set to 0. | |
872 | @end deftypefn | |
873 | ||
874 | ||
d37eb365 | 875 | @c |
641ee76a | 876 | @c *** GetFileTime *** |
d37eb365 | 877 | @c |
d37eb365 | 878 | @noindent |
d37eb365 AJ |
879 | The Wine function @code{GetFileTime} returns the creation time and |
880 | the times of last the read and modification access to a file. It is | |
881 | defined in @file{windows.h}. | |
882 | ||
641ee76a | 883 | @deftypefn_w32 BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})} |
d37eb365 AJ |
884 | This function obtains for the specified @var{file} the creation time |
885 | @var{ctime}, the time of the last access to the file @var{atime}, and | |
886 | the time of the last modification (write) to the file, @var{mtime}. | |
641ee76a AJ |
887 | The file time arguments of this function are pointers to @code{FILETIME} |
888 | variables, which are filled with a value that indicates an absolute time | |
889 | in UTC. @xref{Type FILETIME}, for details. If you do not need some of | |
890 | the times, you can pass a @code{NULL} pointer. | |
891 | The function returns @code{TRUE} on | |
892 | success, @code{FALSE} on failure. | |
d37eb365 AJ |
893 | |
894 | @winconfall{} | |
895 | ||
641ee76a AJ |
896 | @windiff{} |
897 | The file times are produced in a granularity of full seconds, due to the | |
898 | underlying @unix{} file system. | |
d37eb365 AJ |
899 | @end deftypefn |
900 | ||
641ee76a AJ |
901 | @c |
902 | @c *** GetFileAttributes *** | |
903 | @c | |
904 | @noindent | |
905 | The Wine function @code{GetFileAttributes} returns the file attributes | |
906 | for a file. It is defined in @file{windows.h}. | |
907 | ||
908 | @deftypefn_w32 DWORD GetFileAttributes (@w{LPCTSTR @var{name})} | |
909 | This function looks up the file with name @var{name}, and returns the | |
910 | attributes of the file. @xref{File attributes}, for details on the file | |
911 | attributes. If the function is not successful, it returns a word with | |
912 | all bits set (@samp{0xffffffff}). | |
913 | ||
914 | @winconfall{} | |
915 | ||
916 | @windiff{} | |
917 | Most file attributes are not present in the | |
918 | @unix{} file system. @xref{File attributes}, for details. | |
919 | @end deftypefn | |
d37eb365 | 920 | |
d37eb365 | 921 | |
d37eb365 | 922 | |
d37eb365 AJ |
923 | |
924 | @node Communication, Windows and Graphics, I/O Facilities, @WIN32{} Reference Manual | |
925 | @section Communication | |
926 | ||
927 | @node Windows and Graphics, Errors and Exceptions, Communication, @WIN32{} Reference Manual | |
928 | @section Windows and Graphics | |
929 | ||
930 | @node Errors and Exceptions, Resources, Windows and Graphics, @WIN32{} Reference Manual | |
931 | @section Errors and Exceptions | |
932 | ||
933 | @node Resources, The Registry, Errors and Exceptions, @WIN32{} Reference Manual | |
934 | @section Resources | |
935 | ||
936 | @node The Registry, Dynamic Link Libraries, Resources, @WIN32{} Reference Manual | |
937 | @section The Registry | |
938 | ||
939 | @node Dynamic Link Libraries, , The Registry, @WIN32{} Reference Manual | |
940 | @section Dynamic Link Libraries (DLL's) | |
941 | ||
641ee76a AJ |
942 | This section deals with API functions for handling DLL's (dynamic link |
943 | libraries). It does not describe DLL's themselves; nor does it give | |
944 | information on how Wine handles DLL's. @xref{The build program}, for | |
945 | information on how DLL's are integrated into Wine. | |
946 | ||
d37eb365 AJ |
947 | |
948 | ||
949 | ||
950 | @node Resources and INI files, Metafiles--Icons--Bitmaps, @WIN32{} Reference Manual, Reference Manual | |
951 | @chapter Resources and @file{INI} Files | |
952 | ||
953 | @node Metafiles--Icons--Bitmaps, Debugging, Resources and INI files, Reference Manual | |
954 | @chapter Metafiles --- Icons --- Bitmaps | |
955 | ||
956 | @node Debugging, Programs, Metafiles--Icons--Bitmaps, Reference Manual | |
957 | @chapter Debugging | |
958 | ||
959 | @node Programs, Tools, Debugging, Reference Manual | |
960 | @chapter Programs | |
961 | ||
962 | @node Tools, , Programs, Reference Manual | |
963 | @chapter Tools | |
964 | ||
641ee76a AJ |
965 | This chapter describes some of the tools that are used by Wine. These |
966 | are not user-level programs which the user of Wine will | |
5ca7bae8 | 967 | run. @xref{Programs}, for such programs. |
641ee76a AJ |
968 | |
969 | Tools are internal programs that are used to help compile or configure | |
970 | Wine. | |
971 | ||
972 | @menu | |
973 | * The build program:: A program used to build the DLL entry | |
974 | points from specifications in @file{if1632/}. | |
975 | @end menu | |
976 | ||
977 | ||
978 | @node The build program, , , Tools | |
979 | @section The @file{build} program | |
980 | ||
981 | @cindex modules of Wine | |
982 | @cindex Wine modules | |
983 | @cindex DLL's built-in in Wine | |
984 | @cindex Wine DLL's built-in | |
985 | @cindex built-in DLL's in Wine | |
986 | Wine contains several modules that implement various DLL's which are | |
987 | required to run @mswindows{} programs. | |
988 | ||
989 | The @file{build} program, located in the @file{tools/} directory, is | |
990 | used to create the bindings for the DLL entry points of the API functions. | |
991 | This program reads a @file{.spec}-file in the @file{if1632} directory | |
992 | and creates the assembly code that translates the function arguments | |
993 | correctly. | |
994 | ||
995 | ||
996 | @menu | |
997 | * The spec files:: The format of the @file{.spec}-files. | |
998 | @end menu | |
999 | ||
1000 | FIXME: where in Wine are the DLL's affixed? | |
1001 | ||
1002 | FIXME: write a description | |
1003 | ||
1004 | @xref{Implementing an API function}, for notes on using this program. | |
1005 | ||
1006 | @node The spec files, , , The build program | |
1007 | @subsection The @file{.spec}-files | |
1008 | @cindex DLL spec files | |
1009 | @cindex spec files of DLL's | |
1010 | @cindex entry points in DLL's | |
1011 | ||
1012 | This subsection describes the format of the @file{.spec}-files. | |
1013 | ||
1014 | A @file{.spec}-file contains the information about the functions, | |
1015 | variables, and constants that are contained in a DLL (dynamic link | |
1016 | library). | |
1017 | ||
1018 | To be able to interpret the contents of a @file{.spec}-file, you must | |
1019 | know about the concept of ordinals. | |
1020 | @menu | |
1021 | * The general format:: General format conventions. | |
1022 | * Ordinals:: Ordinals are indexes of entry | |
1023 | points into DLL's. | |
1024 | * Spec file header:: The header information. | |
1025 | * Variable entry points:: Entries for DLL variables. | |
1026 | * Function entry points:: Entries for DLL functions. | |
1027 | * Special entries:: Entries for stubs, dummy | |
1028 | functions, Wine symbols, and | |
1029 | constant values. | |
1030 | @end menu | |
1031 | ||
1032 | @node The general format, Ordinals, , The spec files | |
1033 | @subsubsection The general format | |
1034 | @cindex format of spec files | |
1035 | @cindex spec files format | |
1036 | ||
1037 | The @file{.spec}-file contains a header and a sequence of declarations. | |
1038 | Each declaration describes an ordinal. | |
1039 | ||
1040 | The header gives general information about the DLL and its properties. | |
1041 | ||
1042 | Ordinal declarations are optional. That means that there is a default | |
1043 | behaviour assigned to ordinals which are not mentioned in the | |
1044 | @file{.spec}-file. The default handler function of an ordinal will print | |
1045 | an error message when called. | |
1046 | ||
1047 | Comments are indicated by hash marks (@samp{#}); everything between a | |
1048 | hash mark and the end of the line is ignored. | |
1049 | ||
1050 | Empty lines are allowed. | |
1051 | @* FIXME: is that so? | |
1052 | ||
1053 | @node Ordinals, Spec file header, The general format, The spec files | |
1054 | @subsubsection Ordinals | |
1055 | @cindex ordinals in DLL's | |
1056 | @cindex DLL ordinals | |
1057 | ||
1058 | All references to DLL objects like functions or variables are indexed by | |
1059 | unique nonnegative numbers. These numbers are called | |
1060 | @dfn{ordinals}. Apparently, a program can refer to a DLL function or | |
1061 | variable by specifying its name or its ordinal. Although reference by | |
1062 | name is the common usage, some program parts (notably DLL's themselves) | |
1063 | sometimes refer to DLL entries by ordinal. Therefore, the ordinals | |
1064 | cannot be chosen arbitrarily. | |
670cdc45 AJ |
1065 | |
1066 | Regular programs that are compiled and linked against @mswindows{} DLL's | |
1067 | will import DLL functions by name. This is therefore the default | |
1068 | behaviour. Most DLL functions will be imported by name in all cases. | |
1069 | Apparently, the @WIN32{} DLL's even show some difference in the mapping | |
1070 | of functions and ordinals on @WINNT{} and @WIN95{}. For most DLL | |
1071 | functions, the ordinal number will not matter. | |
1072 | ||
1073 | There are some exceptions to that. Notable the KERNEL32 ordinals below | |
1074 | 100 are (presently) unnamed and undocumented functions which can only be | |
1075 | imported by ordinal. These functions are called by some @mswindows{} | |
1076 | programs. Also the @file{shell32.dll} functions are reported to be | |
1077 | imported by ordinal in some other DLL's. | |
1078 | ||
1079 | @xref{Getting information on the API}, for sources of further information. | |
641ee76a AJ |
1080 | |
1081 | @node Spec file header, Variable entry points, Ordinals, The spec files | |
1082 | @subsubsection The header of a @file{.spec}-file | |
1083 | ||
1084 | The @file{.spec}-file starts with two mandatory definitions. The first | |
1085 | line gives the name of the DLL which the @file{.spec}-file describes, | |
1086 | @example | |
1087 | name @var{NAME} | |
1088 | @end example | |
1089 | where @var{NAME} is the name of the DLL. The next line defines the type | |
1090 | of the DLL, | |
1091 | @example | |
1092 | type @var{TYPE} | |
1093 | @end example | |
1094 | with @var{TYPE} being either @samp{win16} or @samp{win32}. | |
1095 | ||
1096 | An optional statement of the form | |
1097 | @example | |
1098 | base @var{ORDINAL} | |
1099 | @end example | |
1100 | can be used to define the offset of the first ordinal. @var{ORDINAL} | |
1101 | must be an integer number. If no base is specified, the offset is zero. | |
1102 | @* FIXME: is this the offset of the first or an offset that is added to all | |
1103 | ordinals? | |
1104 | what is the offset? Is it added to the ordinals, or is it an address, or | |
1105 | xxx? | |
1106 | ||
1107 | An optional statement like | |
1108 | @example | |
1109 | heap @var{SIZE} | |
1110 | @end example | |
1111 | can be used to define the size of the module local heap. This is only | |
1112 | used for @WIN16{} DLL's. The local heap is the place where the segments | |
1113 | of 16 bit programs can locally allocate memory, without interfering with | |
1114 | one another. The default size of the local heap, if not specified, is 0. | |
1115 | ||
1116 | @* FIXME: to my impression, a local heap in DLL's would only be required | |
1117 | if DLL functions used it. As all DLL functions in Wine are truly 32 bit | |
1118 | functions that are mapped from 16 bit on being called and back to 16 bit | |
1119 | on returning, a local heap should never be necessary. | |
1120 | If I receive a confirmation of that here, I will state so. Otherwise I | |
1121 | am missing some information on local heaps. | |
1122 | But why is a heap defined in user.spec and gdi.spec? | |
1123 | ||
1124 | @node Variable entry points, Function entry points, Spec file header, The spec files | |
1125 | @subsubsection Variable entry points of @file{.spec}-files | |
1126 | ||
1127 | You can declare an ordinal that holds data. Data items may be of 8, 16, | |
1128 | or 32 bit in size. | |
1129 | ||
1130 | @example | |
1131 | @var{ORDINAL} @var{VARTYPE} @var{EXPORTNAME} (@var{DATA} @var{[DATA @dots{}]}) | |
1132 | @end example | |
1133 | ||
1134 | @var{ORDINAL} is the ordinal number corresponding to the | |
1135 | variable. @var{VARTYPE} must be @samp{byte}, @samp{word}, or | |
1136 | @samp{long}, for 8, 16, or 32 bits respectively. @var{EXPORTNAME} will | |
1137 | be the name available for dynamic linking. @var{DATA} can be a decimal | |
1138 | number or a hex number preceded by @samp{0x}. Each @var{DATA} item defines | |
1139 | a unit of storage. | |
1140 | ||
1141 | The following example defines the variable @samp{VariableA} at ordinal | |
1142 | 2, containing 4 bytes: | |
1143 | @example | |
1144 | 2 byte VariableA(-1 0xff 0 0) | |
1145 | @end example | |
1146 | ||
1147 | ||
1148 | @node Function entry points, Special entries, Variable entry points, The spec files | |
1149 | @subsubsection Function entry points of @file{.spec}-files | |
1150 | ||
1151 | @example | |
1152 | @var{ORDINAL} @var{FUNCTYPE} @var{EXPORTNAME} (@var{[ARGTYPE} @dots{} @var{]}) @var{HANDLERNAME} | |
1153 | @end example | |
1154 | ||
1155 | @var{ORDINAL} is the ordinal number corresponding to the | |
1156 | function. @var{FUNCTYPE} must be chosen from this table: | |
1157 | @table @samp | |
1158 | @item pascal16 | |
1159 | A @WIN16{} function that returns a 16 bit value. | |
1160 | @item pascal | |
1161 | A @WIN16{} function that returns a 32 bit value. | |
1162 | @item register | |
1163 | A function using CPU registers to pass arguments. | |
1164 | @item stdcall | |
670cdc45 AJ |
1165 | A normal @WIN32{} function. @xref{Investigating the undocumented API}, |
1166 | for an explanation of the stdcall calling convention. | |
641ee76a AJ |
1167 | @item cdecl |
1168 | A @WIN32{} function using the C calling conventions. (This is presently | |
1169 | only used for the built-in functions of the C runtime system). | |
1170 | @end table | |
1171 | ||
1172 | @var{EXPORTNAME} specifies the name (prototype) available for dynamic | |
1173 | linking. | |
1174 | ||
1175 | @var{ARGTYPE} must be chosen from this table: | |
1176 | @table @samp | |
1177 | @item byte | |
1178 | An 8 bit argument. Can be used in @WIN16{} functions only. | |
1179 | @item word | |
1180 | A 16 bit argument. Can be used in @WIN16{} functions only. | |
1181 | @item long | |
1182 | A 32 bit argument. Can be used in @WIN16{} or @WIN32{} functions. | |
1183 | @item ptr | |
1184 | A linear pointer, unsegmented. Can be used in @WIN16{} or @WIN32{} | |
1185 | functions. | |
1186 | @item str | |
1187 | A linear pointer, unsegmented, pointing to a null-terminated string. | |
1188 | Can be used in @WIN16{} or @WIN32{} functions. | |
1189 | @item s_byte | |
1190 | A signed 8 bit argument. Can be used in @WIN16{} functions only. | |
1191 | @item s_word | |
1192 | A signed 16 bit argument. Can be used in @WIN16{} functions only. | |
1193 | @item s_long | |
1194 | A signed 32 bit argument. Can be used in @WIN16{} or @WIN32{} | |
1195 | functions. | |
1196 | @item segptr | |
1197 | A segmented pointer. Can be used in @WIN16{} functions only. | |
1198 | @item segstr | |
1199 | A segmented pointer to a null-terminated string. Can be used in | |
1200 | @WIN16{} functions only. | |
1201 | @end table | |
1202 | ||
1203 | @var{HANDLERNAME} is the name of the actual Wine function that will | |
1204 | process the request in 32-bit mode. | |
1205 | ||
1206 | ||
1207 | @sp 2 | |
1208 | Here are some examples. The first example defines an entry point for the | |
1209 | @code{CreateWindow()} call (the ordinal 100 is just an example): | |
1210 | @example | |
1211 | 100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word | |
1212 | word word word ptr) WIN_CreateWindow | |
1213 | @end example | |
1214 | ||
1215 | The second example defines an entry point for the @code{GetFocus()} call | |
1216 | (again, the ordinal 100 is an example): | |
1217 | @example | |
1218 | 100 pascal GetFocus() WIN_GetFocus() | |
1219 | @end example | |
1220 | ||
1221 | To declare a function that uses a variable number of arguments, specify | |
1222 | the function as taking no arguments. In this special case, in @WIN32{} | |
1223 | the called function will be passed a pointer to the first arg; in | |
1224 | @WIN16{}, the args are available as @code{CURRENT_STACK16->args}. | |
1225 | @* FIXME: create a reference here | |
1226 | See the @code{wsprintf}* functions in @file{user.spec} and | |
1227 | @file{user32.spec} for an example. | |
1228 | ||
670cdc45 AJ |
1229 | Sometimes it is not known how many arguments an undocumented DLL |
1230 | function takes. @xref{Getting information on the API}, for some hints on | |
1231 | how to proceed in such a case. | |
641ee76a AJ |
1232 | |
1233 | @node Special entries, , Function entry points, The spec files | |
1234 | @subsubsection Special entries of @file{.spec}-files | |
1235 | ||
1236 | The @file{.spec}-files offer the possibility to use some special | |
1237 | entries. These entries are used for stubs (which allow linking for | |
1238 | non-existing functions), dummy functions that do not perform any | |
1239 | operations, Wine symbols that must be referenced directly, and constant | |
1240 | values. | |
1241 | ||
1242 | ||
1243 | @strong{Stub ordinals} | |
1244 | ||
1245 | This pseudo function type defines a stub function. It makes the name and | |
1246 | ordinal available for dynamic linking, but will terminate execution with | |
1247 | an error message if the function is ever called. | |
1248 | ||
1249 | @example | |
1250 | @var{ORDINAL} stub @var{EXPORTNAME} | |
1251 | @end example | |
1252 | ||
1253 | @var{ORDINAL} is the ordinal number corresponding to the | |
1254 | function. @var{EXPORTNAME} specifies the name (prototype) available for dynamic | |
1255 | linking. | |
1256 | ||
1257 | @strong{Return ordinals} | |
1258 | ||
1259 | This pseudo function type defines a function entry point whose handler | |
1260 | should do nothing but return a value. | |
1261 | @example | |
1262 | @var{ORDINAL} return @var{EXPORTNAME} @var{ARGLENGTH} @var{RETVALUE} | |
1263 | @end example | |
1264 | ||
1265 | @var{ORDINAL} is replaced by the ordinal number corresponding to the | |
1266 | function. @var{ARGLENGTH} is the number of bytes that need to be removed | |
670cdc45 AJ |
1267 | from the stack before returning to the caller. @xref{Investigating the |
1268 | undocumented API}, for an explanation of the stdcall calling convention. | |
1269 | @var{RETVALUE} is the return value which will be passed back to the | |
1270 | caller. | |
641ee76a AJ |
1271 | |
1272 | @strong{Extern ordinals} | |
1273 | ||
1274 | @example | |
1275 | @var{ORDINAL} extern @var{EXPORTNAME} @var{SYMBOLNAME} | |
1276 | @end example | |
1277 | This type defines an entry that simply maps to a Wine symbol | |
1278 | (variable or function); @var{EXPORTNAME} will point to the symbol | |
1279 | @var{SYMBOLNAME} that must be defined in C code. This type only works with | |
1280 | @WIN32{}. | |
1281 | ||
1282 | ||
1283 | @strong{Equate ordinals} | |
1284 | ||
1285 | @example | |
1286 | @var{ORDINAL} equate @var{EXPORTNAME} @var{DATA} | |
1287 | @end example | |
1288 | ||
1289 | This type defines an ordinal as an absolute value. | |
1290 | @var{ORDINAL} is replaced by the ordinal number corresponding to the | |
1291 | entry. @var{EXPORTNAME} will be the name available for dynamic linking. | |
1292 | @var{DATA} can be a decimal number or a hex number preceeded by @samp{0x}. | |
1293 | ||
1294 | ||
d37eb365 | 1295 | @node Installation, The Wine Project, Reference Manual, Top |
641ee76a | 1296 | @chapter Wine installation and configuration |
d37eb365 AJ |
1297 | FIXME: write installation guide |
1298 | ||
1299 | @menu | |
1300 | * Applying patches:: How to update Wine to a newer version. | |
1301 | @end menu | |
1302 | ||
1303 | @node Applying patches, , , Installation | |
1304 | @section Applying patches | |
1305 | @xref{Creating patches}, for instructions on creating patches. | |
1306 | ||
a11d7b1a AJ |
1307 | @kbd{cd} to the top source directory for Wine, and run |
1308 | @code{patch -p1 < @var{patchfile}}. | |
1309 | What needs to be done next depends to some extent on what the | |
1310 | patch touches. For small patches which only alter C source, it can be | |
1311 | enough to rerun @code{make}. In general, the sequence @code{configure}, | |
1312 | @code{make depend}, @code{make} is sufficient, unless the patch alters | |
1313 | @code{[config.in]}, in which case you must regenerate @code{configure} | |
1314 | via @code{make configure} (which just runs @code{autoconf}). | |
d37eb365 AJ |
1315 | |
1316 | ||
1317 | @node The Wine Project, , Installation, Top | |
1318 | @chapter The Wine project | |
1319 | @cindex Wine project contributions | |
1320 | @cindex project contributions to Wine | |
1321 | ||
1322 | If you are new to Wine and want to support this project, here are | |
1323 | some suggestions. | |
1324 | ||
1325 | @menu | |
670cdc45 AJ |
1326 | * Getting information on the API:: Official and unofficial sources |
1327 | of information on the @WIN32{} API. | |
1328 | * Investigating the undocumented API:: You can find out some API | |
1329 | information on your own. | |
641ee76a AJ |
1330 | * Implementing an API type:: How to implement a data type |
1331 | of the API (a checklist). | |
1332 | * Implementing an API function:: How to implement one function | |
1333 | of the API (a checklist). | |
1334 | * API function and type naming:: How to name API functions in Wine. | |
1335 | * Creating patches:: How to create patches for Wine. | |
1336 | * Adding Documentation:: Templates for the documentation. | |
1337 | * File names:: How Wine treats @mswindows{} and | |
1338 | @unix{} file names. | |
1339 | * Wide character strings:: How Wine treats wide character | |
1340 | strings. | |
d37eb365 AJ |
1341 | @end menu |
1342 | ||
1343 | @xref{Debugging}, for advice on how to debug Wine. | |
1344 | @xref{Applying patches}, for instructions on applying patches. | |
1345 | ||
d37eb365 | 1346 | |
670cdc45 AJ |
1347 | @node Getting information on the API, Investigating the undocumented API, , The Wine Project |
1348 | @section Official and unofficial documentation on the @mswindows{} API | |
1349 | @cindex documentation of API functions | |
1350 | @cindex undocumented API functions | |
1351 | ||
1352 | ||
1353 | @strong{Official documentation} | |
1354 | ||
1355 | For documentation on @WIN32{} API functions, you might try one of these | |
1356 | sources: | |
1357 | ||
1358 | @itemize @bullet | |
1359 | ||
1360 | @item | |
1361 | There is a free online version of the MSDN library (including | |
1362 | documentation for the @WIN32{} API) on | |
1363 | @url{http://www.microsoft.com/msdn/}. | |
1364 | ||
1365 | @item | |
1366 | The @WINNT{} DDK gives information about some kernel (``executive'') | |
1367 | routines. Some of the function documentation might also apply to user | |
1368 | accessible DLL's. | |
1369 | @end itemize | |
1370 | ||
1371 | @strong{Unofficial documentation} | |
1372 | ||
1373 | Not all of the @WIN32{} API is well documented. Some functions are | |
1374 | obscured, and undocumented. @xref{Ordinals}, for information about | |
1375 | undocumented functions imported by ordinal. Getting to know what these | |
1376 | functions do can be tiresome and tedious. Here is a quote from a | |
1377 | news posting concerning two books that might help: | |
1378 | @c From: vischne@ibm.net-nospam (root) | |
1379 | @c Subject: Re: Functions | |
1380 | @c Newsgroups: comp.emulators.ms-windows.wine | |
1381 | @c Date: 24 Jul 97 16:45:11 GMT | |
1382 | @c Organization: The Light | |
1383 | @c NNTP-Posting-Host: 129.37.246.203 | |
1384 | @c Message-ID: <33d78697.0@news3.ibm.net> | |
1385 | ||
1386 | @quotation | |
1387 | Well actually, there are at least _two_ books that address these problems. | |
1388 | One is by Matt Pietrek, ``Windows 95 System Programming Secrets'', which | |
1389 | gives some auxiliary programs for helping ferret out the information, and | |
1390 | the other is by Shulman, ``Undocumented Windows 95''. | |
1391 | @end quotation | |
1392 | ||
1393 | @xref{Ordinals}, for some notes on undocumented kernel functions. | |
1394 | ||
1395 | @itemize @bullet | |
1396 | ||
1397 | @item | |
1398 | @cindex book on undocumented API features by Pietrik | |
1399 | ``Windows 95 System Programming Secrets'' @* | |
1400 | by Matt Pietrek @* | |
1401 | Book & Disk Edition @* | |
1402 | Paperback, 778 pages @* | |
1403 | Published by IDG Books Worldwide @* | |
1404 | Publication date: November 1, 1995 @* | |
1405 | Dimensions (in inches): 9.25 x 7.42 x 2.06 @* | |
1406 | ISBN: 1568843186 @* | |
1407 | ||
1408 | @item | |
1409 | @cindex book on undocumented API features by Schulman | |
1410 | ``Undocumented Windows; A Programmers Guide | |
1411 | to Reserved Microsoft Windows API Functions'' @* | |
1412 | by Andrew Schulman @* | |
1413 | Paperback, 715 pages @* | |
1414 | Published by Addison-Wesley Pub Co @* | |
1415 | Publication date: February 1, 1994 @* | |
1416 | Dimensions (in inches): 9.11 x 7.37 x 1.53 @* | |
1417 | ISBN: 0201608340 @* | |
1418 | ||
1419 | @item | |
1420 | More books on these topics (including Schulman and Pietrik): @* | |
1421 | @url{http://www.sonic.net/~undoc/bookstore.html} | |
1422 | ||
1423 | @item | |
1424 | More details about calling undocumented functions can be found at | |
1425 | @url{http://ftp.uni-mannheim.de/info/OReilly/windows/win95.update/dirty.html}. | |
1426 | ||
1427 | @item | |
1428 | In 1993 Dr. Dobbs Journal published a column called ``Undocumented | |
1429 | Corner''. | |
1430 | @item | |
1431 | You might want to check out BYTE from December 1983 as well. | |
1432 | @* FIXME: is that to be taken seriously? | |
1433 | @item | |
1434 | And you might try to find out something on your own. @xref{Investigating | |
1435 | the undocumented API}, for details. | |
1436 | @end itemize | |
1437 | ||
1438 | But, all in all, @url{news:comp.emulators.ms-windows.wine} says | |
1439 | @c From: dacut@henry.ece.cmu.edu (David A. Cuthbert) | |
1440 | @c Subject: Re: Getting Internet Explorer to work | |
1441 | @c Newsgroups: comp.emulators.ms-windows.wine | |
1442 | @c Date: 24 Jul 1997 03:10:30 GMT | |
1443 | @c Organization: Electrical & Computer Engineering, Carnegie Mellon University | |
1444 | @c Reply-To: henry.ece.cmu.edu!dacut | |
1445 | @c Message-ID: <5r6h36$86c@fs7.ece.cmu.edu> | |
1446 | @c NNTP-Posting-Host: henry.ece.cmu.edu | |
1447 | ||
1448 | @quotation | |
1449 | Unfortunately, short of getting something like NuMega's SoftIce, I | |
1450 | don't think there's a ``good'' reference on the mystery <100 ordinals in | |
1451 | KERNEL32.DLL. | |
1452 | @end quotation | |
1453 | ||
1454 | ||
1455 | @node Investigating the undocumented API, Implementing an API type, Getting information on the API, The Wine Project | |
1456 | @section Investigating the undocumented API | |
1457 | @cindex undocumented API investigation | |
1458 | @cindex parameters of undocumented API functions | |
1459 | @cindex stdcall calling convention | |
1460 | @cindex C calling convention | |
1461 | @cindex API function parameters investigation | |
1462 | @cindex stack handling under stdcall calling | |
1463 | ||
1464 | Besides reading the documentation in @ref{Getting information on the API}, | |
1465 | you can find out some properties of API functions on your own. | |
1466 | ||
1467 | Sometimes it is not known how many arguments an undocumented DLL | |
1468 | function takes. Here is a text from a news posting that gives some | |
1469 | hints on how you might proceed in this case. | |
1470 | ||
1471 | @c The following text is closely quoted from: | |
1472 | @c From: dacut@henry.ece.cmu.edu (David A. Cuthbert) | |
1473 | @c Subject: Win32 stub functions (Claus Fischer, please read) | |
1474 | @c Newsgroups: comp.emulators.ms-windows.wine | |
1475 | @c Date: 7 Aug 1997 22:33:09 GMT | |
1476 | @c Organization: Electrical & Computer Engineering, Carnegie Mellon University | |
1477 | @c Reply-To: henry.ece.cmu.edu!dacut | |
1478 | @c Message-ID: <5sdif5$qt3@fs7.ece.cmu.edu> | |
1479 | ||
1480 | The problem with implementing stubs for @WIN32{} functions is that it is | |
1481 | not sufficient to return a default value (usually 0) and leave the | |
1482 | stack the way we found it. For most @WIN32{} functions -- those that use | |
1483 | the @dfn{stdcall} calling convention -- the arguments sent to the function | |
1484 | are removed from the stack. | |
1485 | ||
1486 | Some background: On the i386 class of machines, stack entries are | |
1487 | usually dword (4 bytes) in size, little-endian. The stack grows | |
1488 | downward in memory. The stack pointer, maintained in the @samp{esp} | |
1489 | register, points to the last valid entry; thus, the operation of | |
1490 | pushing a value onto the stack involves decrementing @samp{esp} and then | |
1491 | moving the value into the memory pointed to by esp (i.e., @code{push p} | |
1492 | in assembly resembles @code{*(--esp) = p;} in C). Removing (popping) | |
1493 | values off the stack is the reverse (i.e., @code{pop p} corresponds to | |
1494 | @code{p = *(esp++);}). | |
1495 | ||
1496 | In the @dfn{stdcall} calling convention, arguments are pushed onto the | |
1497 | stack right-to-left. For example, the C call | |
1498 | ||
1499 | @example | |
1500 | myfunction(40, 20, 70, 30); | |
1501 | @end example | |
1502 | ||
1503 | is expressed in Intel assembly as: | |
1504 | ||
1505 | @example | |
1506 | push 30 | |
1507 | push 70 | |
1508 | push 20 | |
1509 | push 40 | |
1510 | call myfunction | |
1511 | @end example | |
1512 | ||
1513 | In addition, the called function is responsible for removing the | |
1514 | arguments off the stack. Thus, before the call to myfunction, the | |
1515 | stack would look like: | |
1516 | ||
1517 | @example | |
1518 | [local variable or temporary] | |
1519 | [local variable or temporary] | |
1520 | 30 | |
1521 | 70 | |
1522 | 20 | |
1523 | esp -> 40 | |
1524 | @end example | |
1525 | ||
1526 | After the call returns, it should look like: | |
1527 | ||
1528 | @example | |
1529 | [local variable or temporary] | |
1530 | esp -> [local variable or temporary] | |
1531 | @end example | |
1532 | ||
1533 | To restore the stack to this state, the called function must know how | |
1534 | many arguments to remove (which is the number of arguments it takes). | |
1535 | This is a problem if the function is undocumented. | |
1536 | ||
1537 | One way to attempt to document the number of arguments each function | |
1538 | takes is to create a wrapper around that function that detects the | |
1539 | stack offset. @file{WinRelay} (see below) was written to create such | |
1540 | wrappers. Essentially, each wrapper assumes that the function will take | |
1541 | a large number of arguments (by default, 64 in @file{WinRelay}). The | |
1542 | wrapper copies each of these arguments into its stack, calls the actual | |
1543 | function, and then calculates the number of arguments by checking esp | |
1544 | before and after the call. | |
1545 | ||
1546 | @cindex bsod (blue screen of death) | |
1547 | @cindex blue screen of death | |
1548 | The main problem with this scheme is that the function must actually | |
1549 | be called from another program. Many of these functions are seldom | |
1550 | used. An attempt was made to aggressively query each function in a | |
1551 | given library (@file{ntdll.dll}) by passing 64 arguments, all 0, to each | |
1552 | function. Unfortunately, @WINNT40{} quickly goes to a blue screen | |
1553 | of death (@dfn{bsod}), even if the program is run from a | |
1554 | non-administrator account. | |
1555 | ||
1556 | Another method that has been much more successful is to attempt to | |
1557 | figure out how many arguments each function is removing from the | |
1558 | stack. This instruction, @code{ret hhll} (where @samp{hhll} is the | |
1559 | number of bytes to remove, i.e. the number of arguments times 4), contains | |
1560 | the bytes @samp{0xc2 ll hh} in memory. It is a reasonable assumption | |
1561 | that few, if any, functions take more than 16 arguments; therefore, | |
1562 | @samp{hh} is 0x0 and @samp{ll} is less than 0x40. This utility, | |
1563 | @file{MakeSpec} (see below), simply queries the address of a function | |
1564 | and looks for the first occurrence of the bytes @samp{0xc2 ll 0x0}, | |
1565 | where @math{@samp{ll} <= 0x40}. | |
1566 | ||
1567 | Of course, this is not without errors. @code{ret 00ll} is not the only | |
1568 | instruction that can have the byte sequence @samp{0xc2 ll 0x0}; for | |
1569 | example, @code{push 0x000040c2} has the byte sequence | |
1570 | @samp{0x68 0xc2 0x40 0x0 0x0}, which matches the above. Properly, the | |
1571 | utility should look for this sequence only on an instruction boundary; | |
1572 | unfortunately, finding instruction boundaries on an i386 requires | |
1573 | implementing a full disassemble -- quite a daunting task. Besides, | |
1574 | the probability of having such a byte sequence that is not the actual | |
1575 | return instruction is fairly low. | |
1576 | ||
1577 | Much more troublesome is the non-linear flow of a function. For | |
1578 | example, consider the following two functions: | |
1579 | ||
1580 | @example | |
1581 | somefunction1: | |
1582 | jmp somefunction1_impl | |
1583 | ||
1584 | somefunction2: | |
1585 | ret 0004 | |
1586 | ||
1587 | somefunction1_impl: | |
1588 | ret 0008 | |
1589 | @end example | |
1590 | ||
1591 | @file{MakeSpec} would incorrectly list both @code{somefunction1} and | |
1592 | @code{somefunction2} as taking only a single argument, whereas | |
1593 | @code{somefunction1} really takes two arguments. | |
1594 | ||
1595 | With these limitations in mind, it is possible to implement more stubs | |
1596 | in Wine and, eventually, the functions themselves. | |
1597 | ||
1598 | @c end of quote | |
1599 | ||
1600 | The program @file{WinRelay} can be downloaded from | |
1601 | @url{http://www.ece.cmu.edu/afs/ece/usr/dacut/www/src}, | |
1602 | and @file{MakeSpec} will be available from the same location. You can | |
1603 | compile them with Borland's C++Builder; you should not optimize when | |
1604 | compiling (@file{WinRelay} needs the stack frames). | |
1605 | ||
1606 | ||
1607 | @node Implementing an API type, Implementing an API function, Investigating the undocumented API, The Wine Project | |
641ee76a AJ |
1608 | @section Implementing an API type |
1609 | ||
1610 | Here is a checklist that should help you writing your first API type. It | |
1611 | will of course not tell you which elements to put into the type | |
1612 | (assuming it is a structure), but it should help you along the way of | |
1613 | integrating this type into Wine. | |
1614 | @xref{Implementing an API function}, for comparison. | |
1615 | ||
1616 | @enumerate | |
1617 | @item | |
1618 | Find out how the type should be named in Wine and in the DLL's. | |
1619 | @xref{API function and type naming}, for details. | |
1620 | ||
1621 | @item | |
1622 | Find out where the type should go. Please try to keep the header files | |
1623 | structure as similar to @mswindows{} as possible. | |
1624 | ||
1625 | @item | |
1626 | Prepare for the later patch (by saving the original files before you | |
1627 | work on them). @xref{Creating patches}, for details. | |
1628 | ||
1629 | @item | |
1630 | Put the type declaration into the header file. | |
1631 | ||
1632 | @item | |
1633 | Make sure the declaration is syntactically correct, i.e. it does not | |
1634 | keep Wine from compiling. | |
1635 | ||
1636 | @item | |
1637 | Make sure the declared type is layout-compatible with | |
1638 | @mswindows{}-compiled types. Especially keep an eye on the packing of | |
1639 | the structure. | |
1640 | @* FIXME: a reference to packed structures here. | |
1641 | ||
1642 | @item | |
1643 | Build Wine and test the type, if possible. If you cannot test the | |
1644 | type by implementing a proper API function, write a small test program | |
1645 | to test it on its own. Or rather stop here. | |
1646 | ||
1647 | @item | |
1648 | Write the documentation of the type in the @file{wine.texinfo} | |
1649 | file. @xref{Adding Documentation}, for details. | |
1650 | With types, be especially careful and document all the details. Also | |
1651 | document all constants or flags that are used in the type. | |
1652 | ||
1653 | @item | |
1654 | Create an entry in the @file{ChangeLog} file. | |
1655 | ||
1656 | @item | |
1657 | Collect some of these changes, and create a patch. @xref{Creating | |
1658 | patches}, for details. | |
1659 | ||
1660 | @item | |
1661 | Mail the patch to Alexandre Julliard, @email{julliard@@lrc.epfl.ch}. | |
1662 | ||
1663 | @item | |
1664 | Wait for the patch to appear in the official distribution. | |
1665 | @end enumerate | |
1666 | ||
1667 | ||
1668 | @node Implementing an API function, API function and type naming, Implementing an API type, The Wine Project | |
1669 | @section Implementing an API function | |
1670 | ||
1671 | Here is a checklist that should help you writing your first API | |
1672 | function. It will of course not tell you what to do in the function, | |
1673 | but it should help you along the way of integrating this function into | |
1674 | Wine. | |
1675 | ||
1676 | @enumerate | |
1677 | @item | |
1678 | Make sure all data types that appear in function arguments are properly | |
1679 | declared in Wine. Otherwise, start with the data types. | |
1680 | ||
1681 | @item | |
1682 | Find out how the function should be named in Wine and in the DLL's. | |
1683 | @xref{API function and type naming}, for details. | |
1684 | ||
670cdc45 AJ |
1685 | @item |
1686 | Find out what the function should do. This may be tricky for | |
1687 | undocumented functions. @xref{Getting information on the API}, for some | |
1688 | hints. | |
1689 | ||
641ee76a AJ |
1690 | @item |
1691 | Find out where the function should go: | |
1692 | @enumerate | |
1693 | @item | |
1694 | Which header file for the prototype. | |
1695 | @item | |
1696 | Which C source file. | |
1697 | @item | |
1698 | Which DLL(s), and which ordinal the function will take there. Perhaps | |
1699 | the function name is already present in one of the @file{.spec}-files in | |
1700 | the @file{if1632} directory. | |
1701 | @end enumerate | |
1702 | ||
1703 | @item | |
1704 | Prepare for the later patch (by saving the original files before you | |
1705 | work on them). @xref{Creating patches}, for details. | |
1706 | ||
1707 | @item | |
1708 | Put the prototype into the header file, and the code into the C file. | |
1709 | ||
1710 | @item | |
1711 | Make sure the code compiles. | |
1712 | ||
1713 | @item | |
1714 | Create or change the information for the DLL entry points in the | |
1715 | @file{.spec}-file in the @file{if1632} directory. | |
1716 | @xref{The build program}, for details of the DLL spec files. | |
1717 | ||
1718 | @item | |
1719 | Build Wine and test the function, if possible. If you cannot test the | |
1720 | function in Wine, write a small test program to test it on its own. | |
1721 | ||
1722 | @item | |
1723 | Write the documentation of the function in the @file{wine.texinfo} | |
1724 | file. @xref{Adding Documentation}, for details. | |
1725 | ||
1726 | @item | |
1727 | Create an entry in the @file{ChangeLog} file. | |
1728 | ||
1729 | @item | |
1730 | Collect some of these changes, and create a patch. @xref{Creating | |
1731 | patches}, for details. | |
1732 | ||
1733 | @item | |
1734 | Mail the patch to Alexandre Julliard, @email{julliard@@lrc.epfl.ch}. | |
1735 | ||
1736 | @item | |
1737 | Wait for the patch to appear in the official distribution. | |
1738 | @end enumerate | |
1739 | ||
1740 | ||
1741 | @node API function and type naming, Creating patches, Implementing an API function, The Wine Project | |
1742 | @section API function and data type naming conventions | |
1743 | @cindex API function names | |
1744 | @cindex API type names | |
1745 | @cindex names of API functions and types | |
1746 | @cindex naming scheme for API functions and types | |
1747 | @cindex suffixes for API functions and types | |
1748 | @cindex endings of API function and type names | |
1749 | ||
1750 | This section describes Wine's naming scheme for API functions and data | |
1751 | types. | |
1752 | ||
1753 | The purpose of these naming conventions is to ensure that | |
1754 | @itemize @bullet | |
1755 | @item | |
1756 | both the @WIN16{} and @WIN32{} API are supported within the same source | |
1757 | code, | |
1758 | @item | |
1759 | both wide character functions (with @unicode{} strings) and 8 bit | |
1760 | character functions (with @ascii{} or extended @ascii{} encoding) are | |
1761 | supported, and | |
1762 | @item | |
1763 | the source code can be shared between the emulator and the library | |
1764 | version of Wine. | |
1765 | @end itemize | |
1766 | ||
1767 | A function or data type whose name in the @mswindows{} API is @var{xxx} | |
1768 | will in the Wine code have the following name(s): | |
1769 | @table @code | |
1770 | @item @var{xxx}16 | |
1771 | This is the version for the 16 bit API. You might call it the ``16 bit | |
1772 | version'' except that the function itself of course runs in true 32 bit | |
1773 | mode (being part of Wine). So, the correct meaning of the suffix is that | |
1774 | this function is part of the 16 bit API. | |
1775 | @item @var{xxx}32 | |
1776 | This is the version for the 32 bit API. Use this suffix only if the | |
1777 | function does not use character strings in its parameters or return | |
1778 | values. Otherwise use the next two. | |
1779 | @item @var{xxx}32A | |
1780 | This is the version for the 32 bit API which uses @ascii{} strings (or | |
1781 | rather, strings with 8 bit character encodings, i.e. the standard C | |
1782 | @code{char} type). This version always goes together with another | |
1783 | version, using the next suffix. | |
1784 | @item @var{xxx}32W | |
1785 | This is the version for the 32 bit API which uses @unicode{} strings, | |
1786 | i.e. strings with wide characters. It goes together with the @ascii{} | |
1787 | version. | |
1788 | @end table | |
1789 | ||
1790 | So, where the @mswindows{} API offers one name, Wine actually has two or | |
1791 | three different functions implemented (which will hopefully share a | |
1792 | large part of the code). | |
1793 | ||
1794 | Wine allows to use its API functions in two ways. The emulator part of | |
1795 | Wine provides DLL's for the @mswindows{} programs it can run. The | |
1796 | library part of Wine provides a @unix{} programmer with the facility to | |
1797 | use the Wine API's in a standard @unix{} program. | |
1798 | ||
1799 | @menu | |
1800 | * Access from the emulator:: How to access API functions and types | |
1801 | from applications that are run in the | |
1802 | Wine emulator. | |
1803 | * Access in the library:: How to access API functions and types | |
1804 | from applications that are linked with | |
1805 | the Wine library. | |
1806 | * Access from inside Wine:: How to access API functions and types | |
1807 | from inside the Wine code. | |
1808 | @end menu | |
1809 | ||
1810 | @node Access from the emulator, Access in the library, , API function and type naming | |
1811 | @subsection Accessing API functions and types from the emulator | |
1812 | @cindex access to DLL API functions and types | |
1813 | @cindex Wine emulator access to API functions and types | |
1814 | @cindex emulator access to Wine API functions and types | |
1815 | ||
1816 | The emulator part of Wine provides the hooks for dynamically linking the | |
1817 | API functions to the @mswindows{} executables (@file{.EXE}-files). The | |
1818 | Wine emulator contains all versions (16 or 32 bit, @ascii{} or | |
1819 | @unicode{}) of the API functions in one executable. The emulator | |
1820 | performs a mapping from the @mswindows{} name of the function, | |
1821 | by which the executable calls it, to one of the Wine internal names that | |
1822 | have been used in coding it. | |
1823 | ||
1824 | This mapping is done by the built-in DLL handling code of Wine. A | |
1825 | programmer of Wine has to declare the function in one of the virtual | |
1826 | DLL's that are provided by Wine. The declarations are done in the | |
1827 | @file{.spec}-files in the @file{if1632/} directory. @xref{The build | |
1828 | program}, for details. | |
1829 | ||
1830 | The @mswindows{} application simply calls the API function by its | |
1831 | standard @mswindows{} name. Wine will apply the correct mapping | |
1832 | according to Wine's selected appearance (as a 16 bit or 32 bit emulator, | |
1833 | which is a parameter on invocation of Wine). | |
1834 | ||
1835 | ||
1836 | @node Access in the library, Access from inside Wine, Access from the emulator, API function and type naming | |
1837 | @subsection Accessing API functions and types in the library | |
1838 | @cindex Wine library API function and type access | |
1839 | @cindex access to Wine library API functions and types | |
1840 | ||
1841 | If Wine is built as a library, and linked to a user-level main program, | |
1842 | the user will also use the standard @mswindows{} names for the API | |
1843 | functions. | |
1844 | ||
1845 | Some macros are defined in @file{include/wintypes.h} which perform the | |
1846 | necessary name mappings. | |
1847 | ||
1848 | These macros are (see the examples below): | |
1849 | @deffn_winemacro WINELIB_NAME (@var{xxx}) | |
1850 | This macro replaces @var{xxx} by one of @var{xxx}16 or | |
1851 | @var{xxx}32, depending on the definition of the symbols | |
1852 | @code{WINELIB16} and @code{WINELIB32}. @var{xxx} should | |
1853 | be the name of an API function that uses no string arguments. | |
1854 | Use this macro with a @code{#define} to establish the API name @var{xxx}. | |
1855 | @end deffn | |
1856 | @deffn_winemacro WINELIB_NAME_AW (@var{xxx}) | |
1857 | This macro replaces @var{xxx} by one of @var{xxx}16, @var{xxx}32A, or | |
1858 | @var{xxx}32W, depending on the definition of the symbols | |
1859 | @code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. @var{xxx} should | |
1860 | be the name of an API function that uses string arguments. | |
1861 | Use this macro with a @code{#define} to establish the API name @var{xxx}. | |
1862 | @end deffn | |
1863 | @deffn_winemacro DECL_WINELIB_TYPE (@var{xxx}) | |
1864 | This macro declares @var{xxx} to be an equivalent to @var{xxx}16 or | |
1865 | @var{xxx}32, depending on the definition of the symbols | |
1866 | @code{WINELIB16} and @code{WINELIB32}. @var{xxx} should | |
1867 | be the name of an API data type that contains no string arguments. | |
1868 | @end deffn | |
1869 | @deffn_winemacro DECL_WINELIB_TYPE_AW (@var{xxx}) | |
1870 | This macro declares the type @var{xxx} to be an equivalent to | |
1871 | @var{xxx}16, @var{xxx}32A, or @var{xxx}32W, depending on the definition | |
1872 | of the symbols @code{WINELIB16}, @code{WINELIB32}, and | |
1873 | @code{UNICODE}. @var{xxx} should be the name of an API data type that | |
1874 | contains string arguments. | |
1875 | @end deffn | |
1876 | ||
1877 | If Wine is compiled as an emulator, these macros have no effect, for the | |
1878 | mapping is then done by the DLL code. This means that within Wine the | |
1879 | name @var{xxx} itself will not be defined. | |
1880 | ||
1881 | Note: If the definition of @var{xxx} is exactly the same in @WIN16{} and | |
1882 | @WIN32{}, you can simply use the same name as @mswindows{}. | |
1883 | ||
1884 | Here are some examples: | |
1885 | @example | |
1886 | /* A simple type without strings */ | |
1887 | typedef short INT16; | |
1888 | typedef int INT32; | |
1889 | DECL_WINELIB_TYPE(INT); | |
1890 | ||
1891 | /* A type with strings */ | |
1892 | typedef struct @{ /* Win32 ASCII data structure */ @} WNDCLASS32A; | |
1893 | typedef struct @{ /* Win32 Unicode data structure */ @} WNDCLASS32W; | |
1894 | typedef struct @{ /* Win16 data structure */ @} WNDCLASS16; | |
1895 | DECL_WINELIB_TYPE_AW(WNDCLASS); | |
1896 | ||
1897 | /* A function with strings */ | |
1898 | ATOM RegisterClass16( WNDCLASS16 * ); | |
1899 | ATOM RegisterClass32A( WNDCLASS32A * ); | |
1900 | ATOM RegisterClass32W( WNDCLASS32W * ); | |
1901 | #define RegisterClass WINELIB_NAME_AW(RegisterClass) | |
1902 | @end example | |
1903 | ||
1904 | The Winelib user can then say (in the application program): | |
1905 | @example | |
1906 | INT i; | |
1907 | WNDCLASS wc = @{ @dots{} @}; | |
1908 | RegisterClass( &wc ); | |
1909 | @end example | |
1910 | and this will use the correct declaration depending on the definitions | |
1911 | @code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. | |
1912 | ||
1913 | Here are the primary defines that are used when Wine is compiled as a | |
1914 | library: | |
1915 | @defvr_cwine WINELIB16 | |
1916 | If this @code{#define} is set, the Wine library is to be compiled in its | |
1917 | 16 bit form. That means, the 16 bit variants of all functions will be | |
1918 | used and the appearance of the application linked with the Wine library | |
1919 | will be that of a 16 bit application. Of course, both the application | |
1920 | and the Wine library function really run in 32 bit mode. The switch only | |
1921 | selects the function with the name ending in @code{@dots{}16}, which | |
1922 | will perhaps have a behaviour different from its 32 bit counterpart. | |
1923 | @end defvr | |
1924 | @defvr_cwine WINELIB32 | |
1925 | If this @code{#define} is set, the Wine library is to be compiled in its | |
1926 | 32 bit form. That means, the 32 bit variants of all functions will be | |
1927 | used and the appearance of the application linked with the Wine library | |
1928 | will be that of a 32 bit application. | |
1929 | @end defvr | |
1930 | @defvr_cwine UNICODE | |
1931 | This @code{define} is used to select one of two possible 32 bit | |
1932 | variants. Functions and data types of the 32 bit API come in two | |
1933 | flavours: one handling @ascii{} strings (or rather strings with | |
1934 | characters encoded in 8 bit), the other @unicode{} strings. This define | |
1935 | selects the correct variant. As a user of the Wine library, you are | |
1936 | responsible to use the correct character type in your part of the | |
1937 | application which accesses the Wine API functions and data types. | |
1938 | @end defvr | |
1939 | ||
1940 | These switches are automatically set when Wine is compiled as a library. | |
1941 | ||
1942 | ||
1943 | @node Access from inside Wine, , Access in the library, API function and type naming | |
1944 | @subsection Accessing API functions from within Wine | |
1945 | @cindex explicit names of API functions and types | |
1946 | ||
1947 | Within Wine and during the compilation of Wine, you cannot rely on the | |
1948 | @mswindows{} names of the API functions and data types. If Wine is | |
1949 | compiled as a library, they will be defined; if Wine is compiled as an | |
1950 | emulator, they won't. | |
1951 | ||
1952 | You therefore have to access all functions and data types by their full | |
a11d7b1a | 1953 | names, with the proper suffix explicitly appended. In Wine, the 16 bit |
641ee76a AJ |
1954 | and 32 bit versions of the functions are distinct entities, which might |
1955 | (theoretically) show a completely different behaviour. They may even | |
1956 | call each other (and they will quite frequently). | |
1957 | ||
1958 | Therefore Wine is a conglomerate that contains all two or | |
1959 | three flavours of each function at once, and exports to the | |
1960 | application whichever of these is appropriate. Remember that inside | |
1961 | Wine, there is no memory segmentation, so all functions are 32 bit. | |
1962 | The 16-to-32 bit mapping is done on exporting the DLL functions. | |
1963 | ||
1964 | ||
1965 | @node Creating patches, Adding Documentation, API function and type naming, The Wine Project | |
d37eb365 AJ |
1966 | @section Creating patches |
1967 | @xref{Applying patches}, for instructions on applying patches. | |
1968 | ||
a11d7b1a AJ |
1969 | Patches are created with the program @code{diff}. You need a copy |
1970 | of clean source tree to diff against. The @samp{-u} option, to create | |
1971 | unified diffs, is popular but not obligatory. | |
1972 | For changes to a single file, | |
1973 | @code{diff -u wine990101/windows/win.c mywine/windows/win.c > win_patch} | |
1974 | is sufficient. | |
1975 | To generate a complete diff between your tree and the distribution, | |
1976 | use @code{diff -uR wine990101 mywine}. | |
1977 | ||
1978 | This assumes that the original distribution and your personal tree | |
1979 | have the same parent directory, from which you make the diff. | |
1980 | This ensures a consistent format for the diffs, which in turn | |
1981 | is necessary so that they can be applied consistently as described in | |
1982 | @xref{Applying patches}. | |
d37eb365 | 1983 | |
641ee76a | 1984 | @node Adding Documentation, File names, Creating patches, The Wine Project |
d37eb365 AJ |
1985 | @section Adding Documentation |
1986 | ||
1987 | @ifinfo | |
1988 | Here are some templates which should help you collaborate on this | |
1989 | documentation. Read the text below before examining them. | |
1990 | @end ifinfo | |
1991 | ||
d37eb365 AJ |
1992 | @menu |
1993 | * Type Template:: How to document data types in Wine's | |
1994 | include files. | |
1995 | * Function Template:: How to document an (API) function of | |
1996 | Wine. | |
1997 | @end menu | |
1998 | ||
1999 | ||
2000 | These are my tips for adding documentation. | |
2001 | ||
2002 | Do not simply copy documentation from @mswindows{} related | |
2003 | material. Except from risking copyright violations, which you would not | |
2004 | want to do, there is another aspect to that: | |
2005 | As Wine is a product to run on @unix{} and @unix{}-like workstations, | |
2006 | it seems a good idea to me to organize this documentation primarily for | |
2007 | the well-trained @unix{} reader. Please keep that in mind when you add | |
2008 | some documentation. | |
2009 | ||
2010 | Finally, read the info pages for @code{texinfo}. | |
2011 | ||
641ee76a AJ |
2012 | The rest of this section provides some templates which can serve as a |
2013 | start in writing documentation. | |
2014 | ||
d37eb365 AJ |
2015 | @subsection Template introduction |
2016 | @iftex | |
2017 | On the following pages you will find some @code{texinfo} templates, which | |
2018 | should help you collaborate on this documentation. | |
2019 | @end iftex | |
2020 | ||
2021 | These templates give hints on how to document data types, functions, | |
2022 | variables, constants etc. in Wine. | |
2023 | As documentation evolves, you will find common features of data types | |
2024 | that should be described in a unified fashion. In such a case, please | |
2025 | add a corresponding style guide-line here, in this very place, to help | |
2026 | keeping documentation of data types unified. | |
2027 | ||
2028 | ||
2029 | Start out the type or function with a new node. Write a comment before | |
2030 | the node, listing all data types (and functions) described in the node, | |
2031 | like this: | |
2032 | @example | |
2033 | @@c | |
2034 | @@c *** struct FILETIME *** | |
2035 | @@c | |
2036 | @@node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName | |
2037 | @end example | |
2038 | ||
2039 | The node command describes the node name and the names of the next node, | |
2040 | the previous node, and the parent node. The parent node should contain | |
2041 | a menu entry for this node. The previous node is the node that appears | |
2042 | before this node in the parent node menu. The next node is the node | |
2043 | succeeding this one in the parent node menu. If there is no previous or | |
2044 | next node, omit the name (putting just a single space between the two | |
2045 | commata). | |
2046 | ||
2047 | The node name must be a unique sequence of words. Case is important, so | |
2048 | @emph{Type} and @emph{type} are distinct. The node name must not contain | |
2049 | special characters like @samp{@@, @{, @}} or the comma. If you need to | |
2050 | give a node the same name as a function, data type, etc., use the words | |
2051 | @samp{Type}, @samp{Function}, etc. before the identifier. | |
2052 | ||
2053 | Always put the names of the node and its links on the same line, even if | |
2054 | it gets rather long. | |
2055 | ||
2056 | If there are two or more data types or functions described in the node, | |
2057 | adapt the comment like this: | |
2058 | @example | |
2059 | @@c | |
2060 | @@c *** int X *** | |
2061 | @@c *** long Y() *** | |
2062 | @@c | |
2063 | @@node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName | |
2064 | @end example | |
2065 | ||
641ee76a AJ |
2066 | After the node name, put a sectioning command, such as @samp{@@chapter}, |
2067 | @samp{@@section}, @samp{@@subsection}, or @samp{@@subsubsection}. | |
2068 | Without that command, cross references to the node will fail. | |
2069 | @example | |
2070 | @@subsubsection Type FILETIME | |
2071 | @end example | |
2072 | ||
d37eb365 AJ |
2073 | Start the description of the type(s) or function(s) with a single |
2074 | non-indented paragraph that gives a one-line description of the type(s) | |
2075 | or function(s) and states the include files that are required. | |
2076 | @example | |
2077 | @@noindent | |
2078 | File times in Wine are specified by the data type @@code@{FILETIME@}, | |
2079 | defined in @@file@{windows.h@}. | |
2080 | @end example | |
2081 | If several types or functions are closely connected, use one paragraph | |
2082 | as a common description. If more paragraphs are required for a proper | |
2083 | description, indent all but the first of them. | |
2084 | ||
2085 | Then start the definition of the data type or function. Use the proper | |
641ee76a AJ |
2086 | macro, which you will find defined in the beginning of the texinfo file. |
2087 | If appropriate, add your own macros. | |
d37eb365 | 2088 | Again, put everything that belongs to the header into a single line. |
641ee76a | 2089 | Use continuation lines for additional headers. |
d37eb365 | 2090 | @example |
641ee76a AJ |
2091 | @@deftp_w32 FILETIME |
2092 | @@deftpx_w32 LPFILETIME | |
d37eb365 AJ |
2093 | @end example |
2094 | ||
2095 | In the definition, give a verbal explanation of the data type or | |
2096 | function. The explanation should be rather complete, exact, and | |
2097 | comprehensible, than well-structured. This is the point where you can | |
2098 | tell everything you want. Do not be afraid of wasting space. | |
2099 | Do not describe the @mswindows{} situation but only say what Wine | |
2100 | does. That is important. (Sometimes they might even do the same.) | |
2101 | @example | |
2102 | This is the data type for specifying file times. The file times are | |
2103 | stored with 64 bit precision. The actual data type is a structure with | |
2104 | two 32 bit values which are interpreted as the low and high parts of a | |
2105 | 64-bit value. This value gives a time measured in a granularity of 100 | |
2106 | nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In | |
2107 | Wine, this 64-bit value is signed, with the sign taken from the high | |
2108 | part. The lower part is used as unsigned. | |
2109 | @end example | |
2110 | ||
2111 | For data types, it is recommended to quote the definition from the | |
2112 | header file. For a function, you might give a short example of its | |
2113 | usage. You may also put one example in the end of a node that explains | |
2114 | several of the functions in the node. Remember that cut-and-paste from a | |
2115 | well prepared example will help the readers write their code. | |
2116 | @example | |
2117 | The definition of @@code@{FILETIME@} reads: | |
2118 | @@example | |
641ee76a | 2119 | typedef struct |
d37eb365 AJ |
2120 | @@@{ |
2121 | INT32 dwLowDateTime; | |
2122 | INT32 dwHighDateTime; | |
641ee76a | 2123 | @@@} FILETIME, *LPFILETIME; |
d37eb365 AJ |
2124 | @@end example |
2125 | @end example | |
2126 | ||
2127 | You could also use the @code{cindex} command which creates an entry in | |
2128 | the concept index. The @code{texinfo} manual recommends to keep concept | |
2129 | entries distinct, so that a single concept index entry puts to one | |
2130 | well-defined place in the document. Use lower case letters for index | |
2131 | entries, unless they are proper names or quotes from actual code. | |
2132 | @example | |
2133 | @@cindex epoch in file time | |
2134 | The @@code@{FILETIME@} structure may be used to hold absolute or relative | |
2135 | times. Absolute times are given as the number of 100 nanoseconds | |
2136 | intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated | |
2137 | Universal Time, which is GMT, Greenwich Mean Time). This might be | |
2138 | called the @@dfn@{epoch@} for file times. With a signed 64-bit value, this | |
2139 | representation covers absolute times of 29247 years around the epoch. | |
2140 | @end example | |
2141 | ||
2142 | After the verbal documentation, you can add some special fields | |
2143 | describing bugs, implementation dependencies etc. Two of these are | |
2144 | recommended to attach to all descriptions. One describes the | |
2145 | conformance of the data type or function to @mswindows{} products, | |
2146 | i.e. whether the item is also present in @WINNT{} and @WIN95{}. The | |
2147 | other one describes known differences of the Wine item to its | |
2148 | @mswindows{} counterpart. Both will greatly help in porting software | |
2149 | from @mswindows{} to Wine and vice versa. | |
2150 | @example | |
2151 | @@winconfall@{@} | |
2152 | ||
2153 | @@windiff@{@} | |
2154 | In @@mswindows@{@}, the elements of the structure are apparently of type | |
2155 | @@code@{DWORD@}. Whether the full 64 bit value is interpreted as signed or | |
2156 | unsigned I do not know. | |
2157 | @end example | |
2158 | ||
2159 | If you find that more of these property attributes are necessary, feel | |
2160 | free to create your own ones. But keep in mind that they should be | |
2161 | applicable more or less to all described items. Very special properties | |
2162 | will better be put into the verbal text. | |
2163 | ||
2164 | Finally end the definition of the data type or function: | |
2165 | @example | |
2166 | @@end deftp | |
2167 | @end example | |
2168 | ||
2169 | Do not forget to enter the node in the menu of its top node, and do | |
2170 | properly link the node to its successor and predecessor. | |
2171 | ||
2172 | ||
2173 | ||
2174 | ||
2175 | ||
2176 | ||
2177 | @node Type Template, Function Template, , Adding Documentation | |
2178 | @subsection Data type template | |
2179 | ||
2180 | Category: Data type | |
2181 | ||
2182 | @node Function Template, , Type Template, Adding Documentation | |
2183 | @subsection API function template | |
2184 | ||
2185 | Functions should be given category names, to indicate which API they | |
2186 | belong to. Please add items to the list of categories possible. | |
2187 | ||
2188 | Category: WIN32 function | |
2189 | ||
2190 | @example | |
2191 | @@c | |
2192 | @@c ***GetFileTime() *** | |
2193 | @@c | |
2194 | @@node Get File Times, , Compare File Times, File Times | |
2195 | @@noindent | |
2196 | The Wine function @@code@{GetFileTime@} returns the creation time and | |
2197 | the times of last the read and modification access to a file. It is | |
2198 | defined in @@file@{windows.h@}. | |
2199 | ||
641ee76a | 2200 | @@deftypefn_w32 BOOL GetFileTime (@@w@{HANDLE @@var@{file@},@} @@w@{LPFILETIME @@var@{ctime@},@} @@w@{LPFILETIME @@var@{atime@},@} @@w@{LPFILETIME @@var@{mtime@})@} |
d37eb365 AJ |
2201 | This function obtains for the specified @@var@{file@} the creation time |
2202 | @@var@{ctime@}, the time of the last access to the file @@var@{atime@}, and | |
2203 | the time of the last modification (write) to the file, @@var@{mtime@}. | |
2204 | The @@var@{file@} handle must have been obtained by opening the file with | |
2205 | @@code@{GENERIC_READ@} access. The file time arguments of this function are | |
2206 | pointers to @@code@{FILETIME@} variables, which are filled with a value that | |
2207 | indicates an absolute time in UTC. To convert these values to local | |
2208 | times, use the function @@code@{FileTimeToLocalFileTime@}. If you do not | |
2209 | need some of the times, you can pass a @@code@{NULL@} pointer. | |
2210 | The function returns @@code@{TRUE@} on success, @@code@{FALSE@} on failure. | |
2211 | ||
2212 | @@winconfall@{@} | |
2213 | ||
2214 | @@windiffnone@{@} | |
2215 | @@end deftypefn | |
2216 | @end example | |
2217 | ||
2218 | ||
641ee76a AJ |
2219 | @node File names, Wide character strings, Adding Documentation, The Wine Project |
2220 | @section @mswindows{} and @unix{} file names in Wine | |
2221 | @cindex file names in Wine | |
2222 | @cindex Windows file names | |
2223 | @cindex DOS file names in Wine | |
2224 | @cindex UNIX file names in Wine | |
2225 | @cindex POSIX file names in Wine | |
2226 | ||
2227 | FIXME: | |
2228 | ||
2229 | @node Wide character strings, , File names, The Wine Project | |
2230 | @section Wide character strings in API functions | |
2231 | @cindex unicode strings in API functions | |
2232 | @cindex wide character strings in API functions | |
2233 | @cindex strings in API functions | |
2234 | @cindex ascii strings in API functions | |
2235 | @cindex 16 bit characters in API functions | |
2236 | @cindex wchar_t in API functions | |
2237 | ||
2238 | Presently, all wide character strings in API functions of Wine are | |
2239 | internally converted to 8 bit representation. Thus, the @WIN32{} API | |
2240 | with @unicode{} strings is not fully functional for the application | |
2241 | programmer at present. | |
2242 | ||
2243 | Even so, application programmers might consider developing their | |
2244 | applications in wide character format with Wine, as future versions | |
2245 | might bring a change. This might come when a @unix{} filesystem can | |
2246 | handle @unicode{} file names. | |
d37eb365 | 2247 | |
641ee76a AJ |
2248 | Furthermore, the @unicode{} API is required to let Wine run @mswindows{} |
2249 | applications which have been compiled for wide character strings. | |
d37eb365 | 2250 | |
641ee76a AJ |
2251 | In Wine, wide characters are strictly 16 bit; the @code{wchar_t} type of |
2252 | standard C can therefore not be used. | |
d37eb365 AJ |
2253 | |
2254 | @node Concept Index, , , Top | |
2255 | @comment node-name, next, previous, up | |
2256 | @unnumbered Concept Index | |
2257 | @printindex cp | |
2258 | ||
2259 | @node Type Index, , , Top | |
2260 | @comment node-name, next, previous, up | |
2261 | @unnumbered Type Index | |
2262 | @printindex tp | |
2263 | ||
2264 | @node Function Index, , , Top | |
2265 | @comment node-name, next, previous, up | |
2266 | @unnumbered Function Index | |
2267 | @printindex fn | |
2268 | ||
2269 | @node Variable Index, , , Top | |
2270 | @comment node-name, next, previous, up | |
641ee76a | 2271 | @unnumbered Variable, Constants, and Variable-like Macros Index |
d37eb365 AJ |
2272 | @printindex vr |
2273 | ||
2274 | @node File Index, , , Top | |
2275 | @comment node-name, next, previous, up | |
2276 | @unnumbered File and Program Index | |
2277 | @printindex pg | |
2278 | ||
2279 | ||
2280 | @contents | |
2281 | @bye |