Clear menu handle after destroying menu.
[wine] / documentation / wine.texinfo
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
13 * wine: (wine.info).             Windows on Unix.
14 END-INFO-DIR-ENTRY
15 @end format
16 @end ifinfo
17
18 @iftex
19 @c @finalout
20 @end iftex
21
22 @ifinfo
23 This file documents Wine, a system providing Microsoft Windows compatibility
24 to Unix.
25
26 @c 
27 Copyright @copyright{} 1997,1998 The Wine authors. @*
28 @xref{Authors, The Wine Authors, The Wine Authors},
29 for a list of the copyright holders.
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
48 FIXME: X11 and POSIX trademarks. @*
49 UNIX is a registered trademark of the Open Group.
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.
57 @end ifinfo
58
59 @c begin chapters on right pages
60 @setchapternewpage odd
61
62 @titlepage
63
64 @title{The Wine Reference Manual}
65 @subtitle{Edition 0.0.5, February 1998}
66
67 @author{The Wine Team}
68 @c The following two commands start the copyright page.
69 @page
70 @vskip 0pt plus 1filll
71
72 Copyright @copyright{} 1997, 1998 The Wine authors. @*
73 @xref{Authors, The Wine Authors, The Wine Authors},
74 for a list of the copyright holders.
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. @*
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.
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
104 0.0.4
105 @end macro
106
107 @c Edit this macro manually in the above parts of the document
108 @macro winemanualdate
109 February 1998
110 @end macro
111
112 @c Edit this macro manually into the TeX titlepage
113 @macro winemanualtitle
114 The Wine Reference Manual
115 @end macro
116
117 @c
118 @macro winelib
119 Winelib
120 @end macro
121 @c
122 @c MICROSOFT
123 @c
124
125 @c FIXME: automatic trademark reference
126 @macro mswindows
127 MS-Windows
128 @end macro
129
130 @c FIXME: automatic trademark reference
131 @c spell it always the same
132 @macro WIN32
133 WIN32
134 @end macro
135 @macro WIN16
136 WIN16
137 @end macro
138
139 @c FIXME: automatic trademark reference
140 @macro WINNT
141 Windows NT
142 @end macro
143
144 @c FIXME: automatic trademark reference
145 @macro WINNT40
146 Windows NT 4.0
147 @end macro
148
149 @c FIXME: automatic trademark reference
150 @macro WIN95
151 Windows 95
152 @end macro
153
154
155 @c
156 @c THE OTHERS
157 @c
158 @c FIXME: automatic trademark reference
159 @macro unix
160 UNIX
161 @end macro
162
163 @c FIXME: automatic trademark reference
164 @macro posix
165 POSIX
166 @end macro
167
168 @macro unicode
169 Unicode
170 @end macro
171
172 @macro ascii
173 ASCII
174 @end macro
175
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
210 @c
211 @c MACROS FOR FUNCTIONS, TYPES, CONSTANTS, VARIABLES
212 @c
213
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
221
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
229
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
237
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
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
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.
270
271 Wine is free software. Wine is still under development.
272 @end ifinfo
273
274 @menu
275 * Copying::                     License, Warranty, and Authors of Wine.
276 * Introduction::                A short overview.
277 * Wine Design::                 The design of Wine.
278 * Reference Manual::            The Wine reference manual.
279 * Installation::                Installing and configuring Wine.
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.
285 * Variable Index::              Index of variables, constants, and
286                                 variable-like macros.
287 * File Index::                  Index of programs and files.
288 @end menu
289
290 @node Copying, Introduction, Top, Top
291
292 @unnumbered License, Warranty, and Authors of Wine
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
347 @node Introduction, Wine Design, Copying, Top
348 @chapter Introduction
349
350 @strong{What is Wine?}
351
352 Wine is a Windows-compatibility layer for Unix and X11.
353 The Wine system consists of several thing:
354 @enumerate
355 @item
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
361 @item
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
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{}.
368
369 @end enumerate
370
371 @strong{System Requirements}
372
373
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.
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
387 @item
388 OpenBSD/i386 2.1 or later
389 @item
390 Solaris x86 2.5 or later
391 @end itemize
392 You need X11, and you must have @file{libXpm} installed on your system.
393
394 @strong{Availability}
395
396 Wine is free software; the license is BSD-style. Basically, you can do
397 anything with it, except claim that you wrote it.
398 @xref{Copying}, for more information.
399
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
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
542
543 @menu
544 * @WIN32{} Reference Manual::   The @WIN32{} function calls and data types.
545 * Resources and INI files::     How to determine the appearance and
546                                 behaviour of Wine programs.
547 * Metafiles--Icons--Bitmaps::   FIXME missing.
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.
567 * Communication::               How processes can communicate.
568 * Windows and Graphics::        GUI functions of @WIN32{}.
569 * Errors and Exceptions::       How your program can report errors.
570                                 (messaging)
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.
605 @end menu
606
607 @c
608 @c *** struct FILETIME ***
609 @c
610 @node Type FILETIME, Compare File Times, , File Times
611 @subsubsection Type FILETIME
612
613 @noindent
614 File times in Wine are specified by the data type @code{FILETIME},
615 defined in @file{windows.h}.
616 @deftp_w32  FILETIME
617 @deftpx_w32 LPFILETIME
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
620 two 32-bit values which are interpreted as the low and high parts of a
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
628 typedef struct
629 @{
630     INT32 dwLowDateTime;
631     INT32 dwHighDateTime;
632 @} FILETIME, *LPFILETIME;
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.
642 To convert this type to local time, use the function
643 @code{FileTimeToLocalFileTime}. 
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
654 @node Compare File Times, , Type FILETIME, File Times
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}.
660 @deftypefn_w32 LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})}
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
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
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).
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
875 @c
876 @c *** GetFileTime ***
877 @c
878 @noindent
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
883 @deftypefn_w32 BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})}
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}.
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.
893
894 @winconfall{}
895
896 @windiff{}
897 The file times are produced in a granularity of full seconds, due to the
898 underlying @unix{} file system. 
899 @end deftypefn
900
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
920
921
922
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
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
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
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
967 run. @xref{Programs}, for such programs.
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.
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.
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
1165 A normal @WIN32{} function. @xref{Investigating the undocumented API},
1166 for an explanation of the stdcall calling convention.
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
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.
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
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.
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
1295 @node Installation, The Wine Project, Reference Manual, Top
1296 @chapter Wine installation and configuration
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
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}).
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
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.
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.
1341 @end menu
1342
1343 @xref{Debugging}, for advice on how to debug Wine.
1344 @xref{Applying patches}, for instructions on applying patches.
1345
1346
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
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
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
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
1953 names, with the proper suffix explicitly appended. In Wine, the 16 bit
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
1966 @section Creating patches
1967 @xref{Applying patches}, for instructions on applying patches.
1968
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}.
1983
1984 @node Adding Documentation, File names, Creating patches, The Wine Project
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
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
2012 The rest of this section provides some templates which can serve as a
2013 start in writing documentation.
2014
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
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
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
2086 macro, which you will find defined in the beginning of the texinfo file.
2087 If appropriate, add your own macros.
2088 Again, put everything that belongs to the header into a single line.
2089 Use continuation lines for additional headers.
2090 @example
2091 @@deftp_w32  FILETIME
2092 @@deftpx_w32 LPFILETIME
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
2119 typedef struct
2120 @@@{
2121     INT32 dwLowDateTime;
2122     INT32 dwHighDateTime;
2123 @@@} FILETIME, *LPFILETIME;
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
2200 @@deftypefn_w32 BOOL GetFileTime (@@w@{HANDLE @@var@{file@},@} @@w@{LPFILETIME @@var@{ctime@},@} @@w@{LPFILETIME @@var@{atime@},@} @@w@{LPFILETIME @@var@{mtime@})@}
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
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.
2247
2248 Furthermore, the @unicode{} API is required to let Wine run @mswindows{}
2249 applications which have been compiled for wide character strings.
2250
2251 In Wine, wide characters are strictly 16 bit; the @code{wchar_t} type of
2252 standard C can therefore not be used.
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
2271 @unnumbered Variable, Constants, and Variable-like Macros Index
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