From 59bec5030123d18af7bdd2461d1a6e4495e95bbd Mon Sep 17 00:00:00 2001 From: "Dimitrie O. Paun" Date: Thu, 25 Sep 2003 23:48:39 +0000 Subject: [PATCH] Merge the non-obsolete bits from wine.texinfo into the Wine Developers Guide. --- documentation/implementation.sgml | 126 ++ documentation/wine-devel.sgml | 4 + documentation/wine.texinfo | 2285 ----------------------------- 3 files changed, 130 insertions(+), 2285 deletions(-) delete mode 100644 documentation/wine.texinfo diff --git a/documentation/implementation.sgml b/documentation/implementation.sgml index c2f7efc900d..c35587e1c9e 100644 --- a/documentation/implementation.sgml +++ b/documentation/implementation.sgml @@ -2,6 +2,132 @@ Low-level Implementation Details of Wine's Low-level Implementation... + + Undocumented APIs + + + Some background: On the i386 class of machines, stack entries are + usually dword (4 bytes) in size, little-endian. The stack grows + downward in memory. The stack pointer, maintained in the + esp register, points to the last valid entry; + thus, the operation of pushing a value onto the stack involves + decrementing esp and then moving the value into + the memory pointed to by esp + (i.e., push p in assembly resembles + *(--esp) = p; in C). Removing (popping) + values off the stack is the reverse (i.e., pop p + corresponds to p = *(esp++); in C). + + + + In the stdcall calling convention, arguments are + pushed onto the stack right-to-left. For example, the C call + myfunction(40, 20, 70, 30); is expressed in + Intel assembly as: + + push 30 + push 70 + push 20 + push 40 + call myfunction + + The called function is responsible for removing the arguments + off the stack. Thus, before the call to myfunction, the + stack would look like: + + [local variable or temporary] + [local variable or temporary] + 30 + 70 + 20 + esp -> 40 + + After the call returns, it should look like: + + [local variable or temporary] + esp -> [local variable or temporary] + + + + + To restore the stack to this state, the called function must know how + many arguments to remove (which is the number of arguments it takes). + This is a problem if the function is undocumented. + + + + One way to attempt to document the number of arguments each function + takes is to create a wrapper around that function that detects the + stack offset. Essentially, each wrapper assumes that the function will + take a large number of arguments. The wrapper copies each of these + arguments into its stack, calls the actual function, and then calculates + the number of arguments by checking esp before and after the call. + + + + The main problem with this scheme is that the function must actually + be called from another program. Many of these functions are seldom + used. An attempt was made to aggressively query each function in a + given library (ntdll.dll) by passing 64 arguments, + all 0, to each function. Unfortunately, Windows NT quickly goes to a + blue screen of death, even if the program is run from a + non-administrator account. + + + + Another method that has been much more successful is to attempt to + figure out how many arguments each function is removing from the + stack. This instruction, ret hhll (where + hhll is the number of bytes to remove, i.e. the + number of arguments times 4), contains the bytes + 0xc2 ll hh in memory. It is a reasonable + assumption that few, if any, functions take more than 16 arguments; + therefore, simply searching for + hh == 0 && ll < 0x40 starting from the + address of a function yields the correct number of arguments most + of the time. + + + + Of course, this is not without errors. ret 00ll + is not the only instruction that can have the byte sequence + 0xc2 ll 0x0; for example, + push 0x000040c2 has the byte sequence + 0x68 0xc2 0x40 0x0 0x0, which matches + the above. Properly, the utility should look for this sequence + only on an instruction boundary; unfortunately, finding + instruction boundaries on an i386 requires implementing a full + disassembler -- quite a daunting task. Besides, the probability + of having such a byte sequence that is not the actual return + instruction is fairly low. + + + + Much more troublesome is the non-linear flow of a function. For + example, consider the following two functions: + + somefunction1: + jmp somefunction1_impl + + somefunction2: + ret 0004 + + somefunction1_impl: + ret 0008 + + In this case, we would incorrectly detect both + somefunction1 and + somefunction2 as taking only a single + argument, whereas somefunction1 really + takes two arguments. + + + + With these limitations in mind, it is possible to implement more stubs + in Wine and, eventually, the functions themselves. + + + Accelerators diff --git a/documentation/wine-devel.sgml b/documentation/wine-devel.sgml index e39c873ad79..bfcee26afe5 100644 --- a/documentation/wine-devel.sgml +++ b/documentation/wine-devel.sgml @@ -82,6 +82,10 @@ Eric Pouech + + Douglas + Ridgway + John Sheets diff --git a/documentation/wine.texinfo b/documentation/wine.texinfo deleted file mode 100644 index 8167e108389..00000000000 --- a/documentation/wine.texinfo +++ /dev/null @@ -1,2285 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename wine.info -@settitle Wine Reference Manual -@iftex -@afourpaper -@end iftex -@c %**end of header - -@ifinfo -@format -START-INFO-DIR-ENTRY -* wine: (wine.info). Windows on Unix. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@iftex -@c @finalout -@end iftex - -@ifinfo -This file documents Wine, a system providing Microsoft Windows compatibility -to Unix. - -@c -Copyright @copyright{} 1997,1998 The Wine authors. @* -@xref{Authors, The Wine Authors, The Wine Authors}, -for a list of the copyright holders. - -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX -and print the results, provided the printed document -carries a copying permission notice identical to this -one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified -versions of this manual under the conditions stated in -the section entitled ``License, Warranty, and Authors of Wine''. - -@sp 4 -UNIX is a registered trademark of the Open Group. -POSIX is a registered trademark of the IEEE Inc. -X Window System is a trademark of X Consortium, Inc. -Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are -registered trademarks of Microsoft Corporation. -NT is a trademark of Northern Telecom Limited. -C++Builder is a trademark of Borland International, Inc. -Postscript is a registered trademark of Adobe Systems Inc. -Other trademarks are the property of their respective owners, which may -be registered in certain jurisdictions. -@end ifinfo - -@c begin chapters on right pages -@setchapternewpage odd - -@titlepage - -@title{The Wine Reference Manual} -@subtitle{Edition 0.0.5, February 1998} - -@author{The Wine Team} -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll - -Copyright @copyright{} 1997, 1998 The Wine authors. @* -@xref{Authors, The Wine Authors, The Wine Authors}, -for a list of the copyright holders. - -Permission is granted to make and distribute verbatim -copies of this manual provided the copyright notice and -this permission notice are preserved on all copies. - -Permission is granted to copy and distribute modified -versions of this manual under the conditions stated in -the section entitled ``License, Warranty, and Authors of Wine''. - -@sp 4 -UNIX is a registered trademark of the Open Group. -POSIX is a registered trademark of the IEEE Inc. -X Window System is a trademark of X Consortium, Inc. -Microsoft, Windows, MS-Windows, Windows-NT, Windows 95, and MS-DOS are -registered trademarks of Microsoft Corporation. -NT is a trademark of Northern Telecom Limited. -C++Builder is a trademark of Borland International, Inc. -Postscript is a registered trademark of Adobe Systems Inc. -Other trademarks are the property of their respective owners, which may -be registered in certain jurisdictions. -@end titlepage - - - -@c -@c SETTINGS, DEFINES, MACROS -@c - -@c Edit this macro manually in the above parts of the document -@macro winemanualversion -0.0.4 -@end macro - -@c Edit this macro manually in the above parts of the document -@macro winemanualdate -February 1998 -@end macro - -@c Edit this macro manually into the TeX titlepage -@macro winemanualtitle -The Wine Reference Manual -@end macro - -@c -@macro winelib -Winelib -@end macro -@c -@c MICROSOFT -@c - -@c FIXME: automatic trademark reference -@macro mswindows -MS-Windows -@end macro - -@c FIXME: automatic trademark reference -@c spell it always the same -@macro WIN32 -WIN32 -@end macro -@macro WIN16 -WIN16 -@end macro - -@c FIXME: automatic trademark reference -@macro WINNT -Windows NT -@end macro - -@c FIXME: automatic trademark reference -@macro WINNT40 -Windows NT 4.0 -@end macro - -@c FIXME: automatic trademark reference -@macro WIN95 -Windows 95 -@end macro - - -@c -@c THE OTHERS -@c -@c FIXME: automatic trademark reference -@macro unix -UNIX -@end macro - -@c FIXME: automatic trademark reference -@macro posix -POSIX -@end macro - -@macro unicode -Unicode -@end macro - -@macro ascii -ASCII -@end macro - -@c -@c THIS MANUAL -@c - -@c flag out differences to MS-Windows -@macro windiff -@emph{Differences to @mswindows{}:} @* -@end macro - -@macro windiffnone -@windiff{} -No differences known. -@end macro - -@c tell whether function is present in Windows 95 and/or NT -@macro winconf -@emph{Conformance to @mswindows{}:} @* -@end macro - -@macro winconfall -@winconf{} -Present in @WIN95{} and @WINNT{}. -@end macro - -@c give information about completion -@macro completion -@emph{Completion status:} @* -@end macro - -@macro completionnone -@completion{} -Not yet implemented. -@end macro - -@c -@c MACROS FOR FUNCTIONS, TYPES, CONSTANTS, VARIABLES -@c - -@c Constants in the WIN32 API -@macro defvr_cw32 {restofline} -@defvr Constant \restofline\ -@end macro -@macro defvrx_cw32 {restofline} -@defvrx Constant \restofline\ -@end macro - -@c Functions in the WIN32 API -@macro deftypefn_w32 {restofline} -@deftypefn {WIN32 function} \restofline\ -@end macro -@macro deftypefnx_w32 {restofline} -@deftypefnx {WIN32 function} \restofline\ -@end macro - -@c Types in the WIN32 API -@macro deftp_w32 {restofline} -@deftp {Data type} \restofline\ -@end macro -@macro deftpx_w32 {restofline} -@deftpx {Data type} \restofline\ -@end macro - -@c Macros internal to Wine -@macro deffn_winemacro {restofline} -@deffn {Wine internal macro} \restofline\ -@end macro -@macro deffnx_winemacro {restofline} -@deffn {Wine internal macro} \restofline\ -@end macro - -@c Constants internal to Wine -@macro defvr_cwine {restofline} -@defvr {Wine internal constant} \restofline\ -@end macro -@macro defvrx_cwine {restofline} -@defvrx {Wine internal constant} \restofline\ -@end macro - - -@c -@c TOP NODE -@c -@ifinfo -@node Top, Copying, (dir), (dir) -@top Wine - -This is edition @winemanualversion{}, last updated @winemanualdate{}, -of @winemanualtitle{}. - -Wine provides both source and binary compatibility with Microsoft Windows. -The Wine API is designed to be as compatible as possible with various -implementations of the Windows APIs. The Wine library allows porting -Windows source to Unix, and a program loader allows unaltered Windows binaries -to be run on Unix. - -Wine is free software. Wine is still under development. -@end ifinfo - -@menu -* Copying:: License, Warranty, and Authors of Wine. -* Introduction:: A short overview. -* Wine Design:: The design of Wine. -* Reference Manual:: The Wine reference manual. -* Installation:: Installing and configuring Wine. -* The Wine Project:: How to contribute to Wine. -* Concept Index:: Index of concepts and names. -* Type Index:: Index of types and type qualifiers. -* Function Index:: Index of functions and function-like - macros. -* Variable Index:: Index of variables, constants, and - variable-like macros. -* File Index:: Index of programs and files. -@end menu - -@node Copying, Introduction, Top, Top - -@unnumbered License, Warranty, and Authors of Wine -@cindex copying conditions for Wine -@cindex conditions for copying Wine -@cindex Wine copying conditions - -The Wine license, warranty, and list of authors together form the -copyright for Wine. Read these sections carefully. - -@menu -* License:: The Wine license. -* Warranty:: Wine comes with no warranty. -* Authors:: The persons that contributed to Wine. -@end menu - -@node License, Warranty, , Copying -@cindex Wine license -@cindex license of Wine - -@unnumberedsec The Wine License -Wine is distributed under the following copyright. - -@quotation -@include LICENSE -@end quotation - -@node Warranty, Authors, License, Copying -@cindex Wine warranty -@cindex warranty of Wine - -@unnumberedsec The Wine Warranty - -@quotation -Wine comes with no warranty. -@end quotation - -@node Authors, , Warranty, Copying -@cindex Wine authors -@cindex authors of Wine -@cindex copyright holders of Wine -@cindex Wine copyright holders - -@unnumberedsec The Wine Authors - -@quotation -@include AUTHORS -@end quotation - -These persons also hold the copyright on Wine. - -The overall coordination is done by @* -Alexandre Julliard @* -@email{julliard@@winehq.com} - - - -@node Introduction, Wine Design, Copying, Top -@chapter Introduction - -@strong{What is Wine?} - -Wine is a Windows-compatibility layer for Unix and X11. -The Wine system consists of several thing: -@enumerate -@item -An API, sometimes referred to as the Wine API, -designed to be as compatible as possible with the -@mswindows{} API -@item -A library, called @winelib{}, which implements this API -@item -A binary compatibility layer -acts as a program loader for native Windows binaries. -It works for both 16 and 32 bit Intel binaries, and -provides all the appropriate translation between 16 and 32 bit code -(thunking). Real mode interrupts are also supported, and their -functionality is implemented in @winelib{}. - -@end enumerate - -@strong{System Requirements} - - -Wine provides binary support for Intel code on Intel hardware only. -Neither hardware emulation -nor non-Intel binaries are supported. -@winelib{} should be possible to port to just about any Unix system. - -Currently, you must have one of: -@itemize @bullet -@item -Linux version 0.99.13 or above -@item -NetBSD-current -@item -FreeBSD-current or FreeBSD 1.1 -@item -OpenBSD/i386 2.1 or later -@item -Solaris x86 2.5 or later -@end itemize -You need X11, and you must have @file{libXpm} installed on your system. - -@strong{Availability} - -Wine is free software; the license is BSD-style. Basically, you can do -anything with it, except claim that you wrote it. -@xref{Copying}, for more information. - -@strong{Further information} - -You should consult the files @file{README}, @file{ANNOUNCE}, -@file{RELEASE-NOTES}, @file{BUGS}, @file{LICENSE}, and @file{WARRANTY}, -in the root directory of the Wine distribution. - -The Wine USENET newsgroup @url{news:comp.emulators.ms-windows.wine} -is useful for both Wine developers and Wine users. The Wine home page -is @url{http://www.winehq.com/}. - -@node Wine Design, Reference Manual, Introduction, Top -@chapter Wine Design - -@subsection The Wine Graphics Driver Model - -Wine, like Windows, abstracts drawing code so that applications may access -a wide variety of devices, from different kinds of graphics cards, -X displays and printers, using a single unified graphics model. -This model is referred to as GDI: _G_raphics _D_river _I_nterface. -This section discusses the Wine implementation of GDI. -There are 61 functions in the Wine graphics model, including Arc, BitBlt, -Chord, etc. For a complete list and prototypes, see the definition -of DC_FUNCTIONS in [include/gdi.h]. - -Wine, as of 2Q1998, has three native drivers: these provide support -for rendering to X displays, metafiles, and Win16 native printer drivers. -As far as Wine is concerned, a driver -simply consists of a name and a table of function pointers -(see [graphics/driver.c]). These functions -are the driver's implementation of the various Wine graphics -operations (the GDI). Wine maintains a linked list of all drivers which -register themselves with Wine, as well as a ``generic'' -driver. Currently, the X11 driver registers itself as DISPLAY, the -win16 driver registers itself as the generic driver, and the metafile -driver doesn't register itself at all. - -@subsubsection How a driver function gets invoked - -All drawing by Wine applications -is done in terms of a Device Context (DC). -Before an application can draw, it must create a DC, and all drawing calls -must pass a handle to the DC they wish to draw to. -[include/gdi.h] defines several structures relating to DCs, including -DC, WIN_DC_INFO, and DeviceCaps. The DeviceCaps structure is at the lowest -level: it holds -information relating to specifics of the graphics display -hardware and associated -driver. -WIN_DC_INFO holds information about several device independent -modes the DC can be in, plus a pointer to DeviceCaps. -Finally, -the DC structure is the toplevel structure usually passed around. -It holds viewport information, a pointer to WIN_DC_INFO, and a -pointer to the function table to be used while rendering that DC. -This function table is filled at the time of creating the DC. - -@c Modes - -@c Some discussion of the various modalities available to a DC would be nice. - -@c Coordinate Systems - -@c Some discussion of the maze of coordinate systems would also be nice. - -@c Device Coordinates - -@c Logical Coordinates - -@c World transforms - - -@subsubsection The X11 driver - -As a part of the Wine loading process, -X11DRV_Init in [graphics/x11drv/init.c] is called. -This initializes various aspects of the X11 driver and -registers it as DISPLAY. This function first -calls initialization procedures for various parts of the X11 driver. -It then -creates and -fills a static DeviceCaps -structure to be used for every X11 DC. -Finally, it fills the table of GDI functions to be used for X11 -rendering and registers itself as ``DISPLAY''. - -@subsubsection The Metafile Driver - -The metafile driver is unusual, in that it is not a driver for any -kind of display device, but rather a mechanism which allows using -the Wine graphics model as a file format for saving graphics. -The advantage of this is that it allows using identical formats for -saving pictures as is actually used to display them; it is analogous -to Display PostScript. - -The metafile driver is invoked explicitly by the application. The -application calls CreateMetaFile() to create a special DC for recording -graphics drawing operations in a metafile. Any drawing operations -performed in this DC are not drawn physically anywhere, they are -instead stored in the metafile. The DC is explicitly destroyed by a -call to CloseMetaFile(), which also finishes writing the metafile. -Metafiles may be written either to a file or to memory. Later, the -metafile can be rendered (in a physical DC) by PlayMetaFile(). - -The way that this works is that device contexts contain a pointer -to the function lookup table for drawing operations appropriate for -that device. - -Not all functions in the Wine graphics model are relevant to metafiles, but -some relevant but rarely used functions are unimplemented. - -@subsubsection The WIN16 Driver - -WIN16DRV_Init is called by MAIN_EmulatorInit, and registers the -WIN16DRV function table WIN16DRV_Funcs [graphics/win16drv/init.c] -for the generic driver. The WIN16 driver is designed to load -specified native Windows printer drivers. I don't understand -how the whole scheme works, -start studying what happens when a printer DC is -created via WIN16DRV_CreateDC. - -If a DC is created explicitly, via the -CreateDC() call, the driver name is specified explicitly and Wine -finds the appropriate driver by leafing through its table of registered -drivers. Metafile DCs can only be created by the CreateMetaFile function. - -Alternatively, most of the time, the DISPLAY driver is invoked -implicitly. -The application creates a window with -CreateWindow(). If the CS_CLASSDC or CS_OWNDC flag is passed, a new DC -is created and saved for the window in a structure called DCE, which holds -a DC, a clipping region, and flags. Whenever the application wants to -paint in that window, it calls GetDC(hwnd), which returns the DC in the -DCE saved in the window. - -If neither of those flags are used, the window gets a DCE assigned to it -from a pool of DCEs created during Wine initialization and temporarily -assigned during the GetDC() call. -All DCEs, whether part of the Wine DC pool or created by request of a window, -use the ``DISPLAY'' driver. - - -@node Reference Manual, Installation, Wine Design, Top - -@menu -* @WIN32{} Reference Manual:: The @WIN32{} function calls and data types. -* Resources and INI files:: How to determine the appearance and - behaviour of Wine programs. -* Metafiles--Icons--Bitmaps:: FIXME missing. -* Debugging:: Debugging Wine. -* Programs:: Programs written to run in/with Wine. -* Tools:: Programs to support Wine. -@end menu - -@node @WIN32{} Reference Manual, Resources and INI files, , Reference Manual -@chapter The @WIN32{} Reference Manual - -@menu -* Kernel Objects:: How the Wine kernel keeps information. -* Processes and Threads:: Job control and management in Wine. -* Users and Groups:: Security in Wine. -* Date and Time:: Functions for getting the date and time - and for conversion between formats. -* System Information:: Getting information about the hardware - and software the system runs on. -* Memory Management:: How your programs get memory from - Wine. -* I/O Facilities:: Input/Output in Wine. -* Communication:: How processes can communicate. -* Windows and Graphics:: GUI functions of @WIN32{}. -* Errors and Exceptions:: How your program can report errors. - (messaging) -* Resources:: Functions for dealing with resources. -* The Registry:: FIXME missing. -* Dynamic Link Libraries:: Functions for dealing with DLL's. -@end menu - -@node Kernel Objects, Processes and Threads, , @WIN32{} Reference Manual -@section Kernel Objects - - -@node Processes and Threads, Users and Groups, Kernel Objects, @WIN32{} Reference Manual -@section Processes and Threads - -@node Users and Groups, Date and Time, Processes and Threads, @WIN32{} Reference Manual -@section Users and Groups - -@node Date and Time, System Information, Users and Groups, @WIN32{} Reference Manual -@section Date and Time - -This section describes functions for manipulating dates and times. This -includes the current time, the creation or manipulation times of files -and other objects, and conversion between different time -representations. - -@menu -* File Times:: Creation and manipulation times of files. -@end menu - -@node File Times, , , Date and Time -@subsection File Times - -@menu -* Type FILETIME:: The data structure used for specifying - file times. -* Compare File Times:: Compare two file times. -@end menu - -@c -@c *** struct FILETIME *** -@c -@node Type FILETIME, Compare File Times, , File Times -@subsubsection Type FILETIME - -@noindent -File times in Wine are specified by the data type @code{FILETIME}, -defined in @file{windows.h}. -@deftp_w32 FILETIME -@deftpx_w32 LPFILETIME -This is the data type for specifying file times. The file times are -stored with 64 bit precision. The actual data type is a structure with -two 32-bit values which are interpreted as the low and high parts of a -64-bit value. This value gives a time measured in a granularity of 100 -nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In -Wine, this 64-bit value is signed, with the sign taken from the high -part. The lower part is used as unsigned. - -The definition of @code{FILETIME} reads: -@example -typedef struct -@{ - INT32 dwLowDateTime; - INT32 dwHighDateTime; -@} FILETIME, *LPFILETIME; -@end example - -@cindex epoch in file time -The @code{FILETIME} structure may be used to hold absolute or relative -times. Absolute times are given as the number of 100 nanoseconds -intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated -Universal Time, which is GMT, Greenwich Mean Time). This might be -called the @dfn{epoch} for file times. With a signed 64-bit value, this -representation covers absolute times of 29247 years around the epoch. -To convert this type to local time, use the function -@code{FileTimeToLocalFileTime}. - -@windiff{} -In @mswindows{}, the elements of the structure are apparently of type -@code{DWORD}. Whether the full 64 bit value is interpreted as signed or -unsigned I do not know. -@end deftp - -@c -@c *** CompareFileTime *** -@c -@node Compare File Times, , Type FILETIME, File Times - -@noindent -The Wine function @code{CompareFileTime} compares two file times, and -returns whether the first time is less than, equal to, or greater than -the second file time. It is defined in @file{windows.h}. -@deftypefn_w32 LONG CompareFileTime (@w{CONST FILETIME* @var{time_1},} @w{CONST FILETIME* @var{time_2})} -This function returns @code{1}, if @var{time_1} is greater than -@var{time_2}, @code{-1} if it is less, and @code{0} if both times are -equal. - -@winconfall{} - -@windiffnone{} - -@completionnone{} -@end deftypefn - -@node System Information, Memory Management, Date and Time, @WIN32{} Reference Manual -@section System Information - -@node Memory Management, I/O Facilities, System Information, @WIN32{} Reference Manual -@section Memory Management - -@node I/O Facilities, Communication, Memory Management, @WIN32{} Reference Manual -@section I/O Facilities - -This section describes all input/output of a process, except for two -topics: communication with other processes, and communication with the -windowing system. - -@menu -* I/O on Files:: Accessing the contents of files. -* File System Interface:: Functions for manipulating files as a whole. -@end menu - -@node I/O on Files, File System Interface, , I/O Facilities -@subsection I/O on Files - -@node File System Interface, , I/O on Files, I/O Facilities -@subsection File System Interface - -These functions are concerned with operating on files themselves, rather -than on their contents. - -@menu -* Type BY_HANDLE_FILE_INFORMATION:: The data structure used to - specify file information. -* File attributes:: The file attributes flags in - a file information structure. -* Getting file information:: These functions let you obtain - information about a file. -@end menu - -@node Type BY_HANDLE_FILE_INFORMATION, File attributes, , File System Interface -@subsubsection The file information structure - -The file information structure of Wine is used to obtain information -about files. It is declared in the header @file{winedows.h}. -@deftp_w32 BY_HANDLE_FILE_INFORMATION -This is the data type for specifying information about files as objects -of the file system. It contains the following members: -@table @code -@item int dwFileAttributes - @cindex file attributes in file information - @cindex attributes of file in file information - @xref{File attributes}, for details. -@item FILETIME ftCreationTime - @cindex creation time in file information - @cindex time of file creation in file information - The time when the file was created. - @xref{Type FILETIME}, for details. -@item FILETIME ftLastAccessTime - @cindex access time in file information - @cindex time of file access in file information - The time when the file was last accessed. - @xref{Type FILETIME}, for details. -@item FILETIME ftLastWriteTime - @cindex write time in file information - @cindex time of last file write in file information - The time when the file was last written to. - @xref{Type FILETIME}, for details. -@item int dwVolumeSerialNumber - @cindex serial number of volume in file information - @cindex volume number (serial) in file information - The serial number of the volume containing the file. In Wine, - currently 0. -@item int nFileSizeHigh - @cindex file size in file information - @cindex size of file in file information - A 32 bit value which contains the high part of the 64 bit file size. -@item int nFileSizeLow - A 32 bit value which contains the low part of the 64 bit file size. -@item int nNumberOfLinks - @cindex hard links number in file information - @cindex links (number of hard) in file information - This is the number of hard links to the file. In a file system which - does not support hard links, this is 1. -@item int nFileIndexHigh - @cindex inode number in file information - @cindex file index in file information - @cindex index of file in file information - A 32 bit value which contains the high part of the 64 bit file - index. The file index is a unique number for a file on a volume. - This identifier cannot change while the file is opened by a process. - Together with the volume number, the file index is a unique - identifier for the file. This can be used by an application to check - whether two handles refer to the same file. Wine currently uses the - inode number for the file index. -@item int nFileIndexLow - A 32 bit value which contains the low part of the 64 bit file index. -@end table - -The definition of @code{BY_HANDLE_FILE_INFORMATION} reads: -@example -typedef struct -@{ - int dwFileAttributes; - FILETIME ftCreationTime; - FILETIME ftLastAccessTime; - FILETIME ftLastWriteTime; - int dwVolumeSerialNumber; - int nFileSizeHigh; - int nFileSizeLow; - int nNumberOfLinks; - int nFileIndexHigh; - int nFileIndexLow; -@} BY_HANDLE_FILE_INFORMATION ; -@end example - -The @code{BY_HANDLE_FILE_INFORMATION} structure can be obtained by the -@code{GetFileInformationByHandle} function (@pxref{Getting file information}, for -details). - -@windiff{} -In @mswindows{}, the @code{int} elements of the structure are apparently -of type @code{DWORD}. -@end deftp - -@node File attributes, Getting file information, Type BY_HANDLE_FILE_INFORMATION, File System Interface -@subsubsection The file attributes in a file information structure - -The file attributes in a file information structure and in other structures -are a logical @emph{or} of one or more of the following constants: - -@defvr_cw32 FILE_ATTRIBUTE_READONLY -The file is a read-only file. (Wine value: 0x0001). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_HIDDEN -The file is a hidden file. Wine can set this attribute for files starting -with a dot (normally considered hidden in a Unix environment). This behaviour -is controlled by the @code{ShowDotFiles} configuration setting. -(Wine value: 0x0002). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_SYSTEM -The file belongs to the operating system. Files in Wine do not have this -attribute. (Wine value: 0x0004). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_LABEL -This is not present in the @mswindows{} API. (Wine value: 0x0008). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_DIRECTORY -The file is a directory. (Wine value: 0x0010). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_ARCHIVE -The file is an archive file. Currently, all non-directory files are -reported by Wine to have this attribute. This attribute is normally set -by @mswindows{} to indicate that a file is to be archived; when the file -is archived, the flag is cleared. (Wine value: 0x0020). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_NORMAL -The file does not have any other attributes set. This value must be used -alone. In Wine, normal files are reported as archive files. (Wine value: -0x0080). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_TEMPORARY -The file is used as a temporary storage. Files in Wine do not have this -attribute. (Wine value: 0x0100). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_ATOMIC_WRITE -This is reserved for future use. Files in Wine do not have this -attribute. (Wine value: 0x0200). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_XACTION_WRITE -This is reserved for future use. Files in Wine do not have this -attribute. (Wine value: 0x0400). -@end defvr -@defvr_cw32 FILE_ATTRIBUTE_COMPRESSED -The file is compressed. Files in Wine do not have this attribute. (Wine -value: 0x0800). -@end defvr - -@node Getting file information, , File attributes, File System Interface -@subsubsection Getting file information - -The functions in this section describe how to get information about -files. - -@c -@c *** GetFileInformationByHandle -@c -@noindent -The Wine function @code{GetFileInformationByHandle} returns a file -information structure. It is defined in @file{windows.h}. - -@deftypefn_w32 BOOL GetFileInformationByHandle (@w{HFILE32 @var{file},} @w{BY_HANDLE_FILE_INFORMATION *@var{info})} -This function obtains for the specified @var{file} the file information, -and stores it in @var{info}. The file information contains the file -attributes, the file times, the volume serial number, the file size, the -number of links, and a unique file identifier. The function returns -@code{TRUE} on success, @code{FALSE} on failure. - -@winconfall{} - -@windiff{} -The Wine function can of course only give back information that is -accessible in the @unix{} file system. File times are produced in a -granularity of full seconds. Most file attributes are not present in the -@unix{} file system. @xref{File attributes}, for details. The volume -serial number is set to 0. -@end deftypefn - - -@c -@c *** GetFileTime *** -@c -@noindent -The Wine function @code{GetFileTime} returns the creation time and -the times of last the read and modification access to a file. It is -defined in @file{windows.h}. - -@deftypefn_w32 BOOL GetFileTime (@w{HANDLE @var{file},} @w{LPFILETIME @var{ctime},} @w{LPFILETIME @var{atime},} @w{LPFILETIME @var{mtime})} -This function obtains for the specified @var{file} the creation time -@var{ctime}, the time of the last access to the file @var{atime}, and -the time of the last modification (write) to the file, @var{mtime}. -The file time arguments of this function are pointers to @code{FILETIME} -variables, which are filled with a value that indicates an absolute time -in UTC. @xref{Type FILETIME}, for details. If you do not need some of -the times, you can pass a @code{NULL} pointer. -The function returns @code{TRUE} on -success, @code{FALSE} on failure. - -@winconfall{} - -@windiff{} -The file times are produced in a granularity of full seconds, due to the -underlying @unix{} file system. -@end deftypefn - -@c -@c *** GetFileAttributes *** -@c -@noindent -The Wine function @code{GetFileAttributes} returns the file attributes -for a file. It is defined in @file{windows.h}. - -@deftypefn_w32 DWORD GetFileAttributes (@w{LPCTSTR @var{name})} -This function looks up the file with name @var{name}, and returns the -attributes of the file. @xref{File attributes}, for details on the file -attributes. If the function is not successful, it returns a word with -all bits set (@samp{0xffffffff}). - -@winconfall{} - -@windiff{} -Most file attributes are not present in the -@unix{} file system. @xref{File attributes}, for details. -@end deftypefn - - - - -@node Communication, Windows and Graphics, I/O Facilities, @WIN32{} Reference Manual -@section Communication - -@node Windows and Graphics, Errors and Exceptions, Communication, @WIN32{} Reference Manual -@section Windows and Graphics - -@node Errors and Exceptions, Resources, Windows and Graphics, @WIN32{} Reference Manual -@section Errors and Exceptions - -@node Resources, The Registry, Errors and Exceptions, @WIN32{} Reference Manual -@section Resources - -@node The Registry, Dynamic Link Libraries, Resources, @WIN32{} Reference Manual -@section The Registry - -@node Dynamic Link Libraries, , The Registry, @WIN32{} Reference Manual -@section Dynamic Link Libraries (DLL's) - -This section deals with API functions for handling DLL's (dynamic link -libraries). It does not describe DLL's themselves; nor does it give -information on how Wine handles DLL's. @xref{The build program}, for -information on how DLL's are integrated into Wine. - - - - -@node Resources and INI files, Metafiles--Icons--Bitmaps, @WIN32{} Reference Manual, Reference Manual -@chapter Resources and @file{INI} Files - -@node Metafiles--Icons--Bitmaps, Debugging, Resources and INI files, Reference Manual -@chapter Metafiles --- Icons --- Bitmaps - -@node Debugging, Programs, Metafiles--Icons--Bitmaps, Reference Manual -@chapter Debugging - -@node Programs, Tools, Debugging, Reference Manual -@chapter Programs - -@node Tools, , Programs, Reference Manual -@chapter Tools - -This chapter describes some of the tools that are used by Wine. These -are not user-level programs which the user of Wine will -run. @xref{Programs}, for such programs. - -Tools are internal programs that are used to help compile or configure -Wine. - -@menu -* The build program:: A program used to build the DLL entry - points from specifications in @file{if1632/}. -@end menu - - -@node The build program, , , Tools -@section The @file{build} program - -@cindex modules of Wine -@cindex Wine modules -@cindex DLL's built-in in Wine -@cindex Wine DLL's built-in -@cindex built-in DLL's in Wine -Wine contains several modules that implement various DLL's which are -required to run @mswindows{} programs. - -The @file{build} program, located in the @file{tools/} directory, is -used to create the bindings for the DLL entry points of the API functions. -This program reads a @file{.spec}-file in the @file{if1632} directory -and creates the assembly code that translates the function arguments -correctly. - - -@menu -* The spec files:: The format of the @file{.spec}-files. -@end menu - -FIXME: where in Wine are the DLL's affixed? - -FIXME: write a description - -@xref{Implementing an API function}, for notes on using this program. - -@node The spec files, , , The build program -@subsection The @file{.spec}-files -@cindex DLL spec files -@cindex spec files of DLL's -@cindex entry points in DLL's - -This subsection describes the format of the @file{.spec}-files. - -A @file{.spec}-file contains the information about the functions, -variables, and constants that are contained in a DLL (dynamic link -library). - -To be able to interpret the contents of a @file{.spec}-file, you must -know about the concept of ordinals. -@menu -* The general format:: General format conventions. -* Ordinals:: Ordinals are indexes of entry - points into DLL's. -* Spec file header:: The header information. -* Variable entry points:: Entries for DLL variables. -* Function entry points:: Entries for DLL functions. -* Special entries:: Entries for stubs, dummy - functions, Wine symbols, and - constant values. -@end menu - -@node The general format, Ordinals, , The spec files -@subsubsection The general format -@cindex format of spec files -@cindex spec files format - -The @file{.spec}-file contains a header and a sequence of declarations. -Each declaration describes an ordinal. - -The header gives general information about the DLL and its properties. - -Ordinal declarations are optional. That means that there is a default -behaviour assigned to ordinals which are not mentioned in the -@file{.spec}-file. The default handler function of an ordinal will print -an error message when called. - -Comments are indicated by hash marks (@samp{#}); everything between a -hash mark and the end of the line is ignored. - -Empty lines are allowed. -@* FIXME: is that so? - -@node Ordinals, Spec file header, The general format, The spec files -@subsubsection Ordinals -@cindex ordinals in DLL's -@cindex DLL ordinals - -All references to DLL objects like functions or variables are indexed by -unique nonnegative numbers. These numbers are called -@dfn{ordinals}. Apparently, a program can refer to a DLL function or -variable by specifying its name or its ordinal. Although reference by -name is the common usage, some program parts (notably DLL's themselves) -sometimes refer to DLL entries by ordinal. Therefore, the ordinals -cannot be chosen arbitrarily. - -Regular programs that are compiled and linked against @mswindows{} DLL's -will import DLL functions by name. This is therefore the default -behaviour. Most DLL functions will be imported by name in all cases. -Apparently, the @WIN32{} DLL's even show some difference in the mapping -of functions and ordinals on @WINNT{} and @WIN95{}. For most DLL -functions, the ordinal number will not matter. - -There are some exceptions to that. Notable the KERNEL32 ordinals below -100 are (presently) unnamed and undocumented functions which can only be -imported by ordinal. These functions are called by some @mswindows{} -programs. Also the @file{shell32.dll} functions are reported to be -imported by ordinal in some other DLL's. - -@xref{Getting information on the API}, for sources of further information. - -@node Spec file header, Variable entry points, Ordinals, The spec files -@subsubsection The header of a @file{.spec}-file - -The @file{.spec}-file starts with two mandatory definitions. The first -line gives the name of the DLL which the @file{.spec}-file describes, -@example -name @var{NAME} -@end example -where @var{NAME} is the name of the DLL. The next line defines the type -of the DLL, -@example -type @var{TYPE} -@end example -with @var{TYPE} being either @samp{win16} or @samp{win32}. - -An optional statement of the form -@example -base @var{ORDINAL} -@end example -can be used to define the offset of the first ordinal. @var{ORDINAL} -must be an integer number. If no base is specified, the offset is zero. -@* FIXME: is this the offset of the first or an offset that is added to all -ordinals? -what is the offset? Is it added to the ordinals, or is it an address, or -xxx? - -An optional statement like -@example -heap @var{SIZE} -@end example -can be used to define the size of the module local heap. This is only -used for @WIN16{} DLL's. The local heap is the place where the segments -of 16 bit programs can locally allocate memory, without interfering with -one another. The default size of the local heap, if not specified, is 0. - -@* FIXME: to my impression, a local heap in DLL's would only be required -if DLL functions used it. As all DLL functions in Wine are truly 32 bit -functions that are mapped from 16 bit on being called and back to 16 bit -on returning, a local heap should never be necessary. -If I receive a confirmation of that here, I will state so. Otherwise I -am missing some information on local heaps. -But why is a heap defined in user.spec and gdi.spec? - -@node Variable entry points, Function entry points, Spec file header, The spec files -@subsubsection Variable entry points of @file{.spec}-files - -You can declare an ordinal that holds data. Data items may be of 8, 16, -or 32 bit in size. - -@example -@var{ORDINAL} @var{VARTYPE} @var{EXPORTNAME} (@var{DATA} @var{DATA @dots{}}) -@end example - -@var{ORDINAL} is the ordinal number corresponding to the -variable. @var{VARTYPE} must be @samp{byte}, @samp{word}, or -@samp{long}, for 8, 16, or 32 bits respectively. @var{EXPORTNAME} will -be the name available for dynamic linking. @var{DATA} can be a decimal -number or a hex number preceded by @samp{0x}. Each @var{DATA} item defines -a unit of storage. - -The following example defines the variable @samp{VariableA} at ordinal -2, containing 4 bytes: -@example -2 byte VariableA(-1 0xff 0 0) -@end example - - -@node Function entry points, Special entries, Variable entry points, The spec files -@subsubsection Function entry points of @file{.spec}-files - -@example -@var{ORDINAL} @var{FUNCTYPE} @var{EXPORTNAME} (@var{ARGTYPE} @dots{} @var{}) @var{HANDLERNAME} -@end example - -@var{ORDINAL} is the ordinal number corresponding to the -function. @var{FUNCTYPE} must be chosen from this table: -@table @samp -@item pascal16 -A @WIN16{} function that returns a 16 bit value. -@item pascal -A @WIN16{} function that returns a 32 bit value. -@item register -A function using CPU registers to pass arguments. -@item stdcall -A normal @WIN32{} function. @xref{Investigating the undocumented API}, -for an explanation of the stdcall calling convention. -@item cdecl -A @WIN32{} function using the C calling conventions. (This is presently -only used for the built-in functions of the C runtime system). -@end table - -@var{EXPORTNAME} specifies the name (prototype) available for dynamic -linking. - -@var{ARGTYPE} must be chosen from this table: -@table @samp -@item byte - An 8 bit argument. Can be used in @WIN16{} functions only. -@item word - A 16 bit argument. Can be used in @WIN16{} functions only. -@item long - A 32 bit argument. Can be used in @WIN16{} or @WIN32{} functions. -@item ptr - A linear pointer, unsegmented. Can be used in @WIN16{} or @WIN32{} - functions. -@item str - A linear pointer, unsegmented, pointing to a null-terminated string. - Can be used in @WIN16{} or @WIN32{} functions. -@item s_byte - A signed 8 bit argument. Can be used in @WIN16{} functions only. -@item s_word - A signed 16 bit argument. Can be used in @WIN16{} functions only. -@item s_long - A signed 32 bit argument. Can be used in @WIN16{} or @WIN32{} - functions. -@item segptr - A segmented pointer. Can be used in @WIN16{} functions only. -@item segstr - A segmented pointer to a null-terminated string. Can be used in - @WIN16{} functions only. -@end table - -@var{HANDLERNAME} is the name of the actual Wine function that will -process the request in 32-bit mode. - - -@sp 2 -Here are some examples. The first example defines an entry point for the -@code{CreateWindow()} call (the ordinal 100 is just an example): -@example -100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word - word word word ptr) WIN_CreateWindow -@end example - -The second example defines an entry point for the @code{GetFocus()} call -(again, the ordinal 100 is an example): -@example -100 pascal GetFocus() WIN_GetFocus() -@end example - -To declare a function that uses a variable number of arguments, specify -the function as taking no arguments. In this special case, in @WIN32{} -the called function will be passed a pointer to the first arg; in -@WIN16{}, the args are available as @code{CURRENT_STACK16->args}. -@* FIXME: create a reference here -See the @code{wsprintf}* functions in @file{user.spec} and -@file{user32.spec} for an example. - -Sometimes it is not known how many arguments an undocumented DLL -function takes. @xref{Getting information on the API}, for some hints on -how to proceed in such a case. - -@node Special entries, , Function entry points, The spec files -@subsubsection Special entries of @file{.spec}-files - -The @file{.spec}-files offer the possibility to use some special -entries. These entries are used for stubs (which allow linking for -non-existing functions), dummy functions that do not perform any -operations, Wine symbols that must be referenced directly, and constant -values. - - -@strong{Stub ordinals} - -This pseudo function type defines a stub function. It makes the name and -ordinal available for dynamic linking, but will terminate execution with -an error message if the function is ever called. - -@example -@var{ORDINAL} stub @var{EXPORTNAME} -@end example - -@var{ORDINAL} is the ordinal number corresponding to the -function. @var{EXPORTNAME} specifies the name (prototype) available for dynamic -linking. - -@strong{Return ordinals} - -This pseudo function type defines a function entry point whose handler -should do nothing but return a value. -@example -@var{ORDINAL} return @var{EXPORTNAME} @var{ARGLENGTH} @var{RETVALUE} -@end example - -@var{ORDINAL} is replaced by the ordinal number corresponding to the -function. @var{ARGLENGTH} is the number of bytes that need to be removed -from the stack before returning to the caller. @xref{Investigating the -undocumented API}, for an explanation of the stdcall calling convention. -@var{RETVALUE} is the return value which will be passed back to the -caller. - -@strong{Extern ordinals} - -@example -@var{ORDINAL} extern @var{EXPORTNAME} @var{SYMBOLNAME} -@end example -This type defines an entry that simply maps to a Wine symbol -(variable or function); @var{EXPORTNAME} will point to the symbol -@var{SYMBOLNAME} that must be defined in C code. This type only works with -@WIN32{}. - - -@strong{Equate ordinals} - -@example -@var{ORDINAL} equate @var{EXPORTNAME} @var{DATA} -@end example - -This type defines an ordinal as an absolute value. -@var{ORDINAL} is replaced by the ordinal number corresponding to the -entry. @var{EXPORTNAME} will be the name available for dynamic linking. -@var{DATA} can be a decimal number or a hex number preceeded by @samp{0x}. - - -@node Installation, The Wine Project, Reference Manual, Top -@chapter Wine installation and configuration -FIXME: write installation guide - -@menu -* Applying patches:: How to update Wine to a newer version. -@end menu - -@node Applying patches, , , Installation -@section Applying patches -@xref{Creating patches}, for instructions on creating patches. - -@kbd{cd} to the top source directory for Wine, and run -@code{patch -p1 < @var{patchfile}}. -What needs to be done next depends to some extent on what the -patch touches. For small patches which only alter C source, it can be -enough to rerun @code{make}. In general, the sequence @code{configure}, -@code{make depend}, @code{make} is sufficient, unless the patch alters -@code{[config.in]}, in which case you must regenerate @code{configure} -via @code{make configure} (which just runs @code{autoconf}). - - -@node The Wine Project, , Installation, Top -@chapter The Wine project -@cindex Wine project contributions -@cindex project contributions to Wine - -If you are new to Wine and want to support this project, here are -some suggestions. - -@menu -* Getting information on the API:: Official and unofficial sources - of information on the @WIN32{} API. -* Investigating the undocumented API:: You can find out some API - information on your own. -* Implementing an API type:: How to implement a data type - of the API (a checklist). -* Implementing an API function:: How to implement one function - of the API (a checklist). -* API function and type naming:: How to name API functions in Wine. -* Creating patches:: How to create patches for Wine. -* Adding Documentation:: Templates for the documentation. -* File names:: How Wine treats @mswindows{} and - @unix{} file names. -* Wide character strings:: How Wine treats wide character - strings. -@end menu - -@xref{Debugging}, for advice on how to debug Wine. -@xref{Applying patches}, for instructions on applying patches. - - -@node Getting information on the API, Investigating the undocumented API, , The Wine Project -@section Official and unofficial documentation on the @mswindows{} API -@cindex documentation of API functions -@cindex undocumented API functions - - -@strong{Official documentation} - -For documentation on @WIN32{} API functions, you might try one of these -sources: - -@itemize @bullet - -@item -There is a free online version of the MSDN library (including -documentation for the @WIN32{} API) on -@url{http://www.microsoft.com/msdn/}. - -@item -The @WINNT{} DDK gives information about some kernel (``executive'') -routines. Some of the function documentation might also apply to user -accessible DLL's. -@end itemize - -@strong{Unofficial documentation} - -Not all of the @WIN32{} API is well documented. Some functions are -obscured, and undocumented. @xref{Ordinals}, for information about -undocumented functions imported by ordinal. Getting to know what these -functions do can be tiresome and tedious. Here is a quote from a -news posting concerning two books that might help: -@c From: vischne@ibm.net-nospam (root) -@c Subject: Re: Functions -@c Newsgroups: comp.emulators.ms-windows.wine -@c Date: 24 Jul 97 16:45:11 GMT -@c Organization: The Light -@c NNTP-Posting-Host: 129.37.246.203 -@c Message-ID: <33d78697.0@news3.ibm.net> - -@quotation -Well actually, there are at least _two_ books that address these problems. -One is by Matt Pietrek, ``Windows 95 System Programming Secrets'', which -gives some auxiliary programs for helping ferret out the information, and -the other is by Shulman, ``Undocumented Windows 95''. -@end quotation - -@xref{Ordinals}, for some notes on undocumented kernel functions. - -@itemize @bullet - -@item -@cindex book on undocumented API features by Pietrik -``Windows 95 System Programming Secrets'' @* -by Matt Pietrek @* -Book & Disk Edition @* -Paperback, 778 pages @* -Published by IDG Books Worldwide @* -Publication date: November 1, 1995 @* -Dimensions (in inches): 9.25 x 7.42 x 2.06 @* -ISBN: 1568843186 @* - -@item -@cindex book on undocumented API features by Schulman -``Undocumented Windows; A Programmers Guide -to Reserved Microsoft Windows API Functions'' @* -by Andrew Schulman @* -Paperback, 715 pages @* -Published by Addison-Wesley Pub Co @* -Publication date: February 1, 1994 @* -Dimensions (in inches): 9.11 x 7.37 x 1.53 @* -ISBN: 0201608340 @* - -@item -More books on these topics (including Schulman and Pietrik): @* -@url{http://www.sonic.net/~undoc/bookstore.html} - -@item -More details about calling undocumented functions can be found at -@url{http://ftp.uni-mannheim.de/info/OReilly/windows/win95.update/dirty.html}. - -@item -In 1993 Dr. Dobbs Journal published a column called ``Undocumented -Corner''. -@item -You might want to check out BYTE from December 1983 as well. -@* FIXME: is that to be taken seriously? -@item -And you might try to find out something on your own. @xref{Investigating -the undocumented API}, for details. -@end itemize - -But, all in all, @url{news:comp.emulators.ms-windows.wine} says -@c From: dacut@henry.ece.cmu.edu (David A. Cuthbert) -@c Subject: Re: Getting Internet Explorer to work -@c Newsgroups: comp.emulators.ms-windows.wine -@c Date: 24 Jul 1997 03:10:30 GMT -@c Organization: Electrical & Computer Engineering, Carnegie Mellon University -@c Reply-To: henry.ece.cmu.edu!dacut -@c Message-ID: <5r6h36$86c@fs7.ece.cmu.edu> -@c NNTP-Posting-Host: henry.ece.cmu.edu - -@quotation -Unfortunately, short of getting something like NuMega's SoftIce, I -don't think there's a ``good'' reference on the mystery <100 ordinals in -KERNEL32.DLL. -@end quotation - - -@node Investigating the undocumented API, Implementing an API type, Getting information on the API, The Wine Project -@section Investigating the undocumented API -@cindex undocumented API investigation -@cindex parameters of undocumented API functions -@cindex stdcall calling convention -@cindex C calling convention -@cindex API function parameters investigation -@cindex stack handling under stdcall calling - -Besides reading the documentation in @ref{Getting information on the API}, -you can find out some properties of API functions on your own. - -Sometimes it is not known how many arguments an undocumented DLL -function takes. Here is a text from a news posting that gives some -hints on how you might proceed in this case. - -@c The following text is closely quoted from: -@c From: dacut@henry.ece.cmu.edu (David A. Cuthbert) -@c Subject: Win32 stub functions (Claus Fischer, please read) -@c Newsgroups: comp.emulators.ms-windows.wine -@c Date: 7 Aug 1997 22:33:09 GMT -@c Organization: Electrical & Computer Engineering, Carnegie Mellon University -@c Reply-To: henry.ece.cmu.edu!dacut -@c Message-ID: <5sdif5$qt3@fs7.ece.cmu.edu> - -The problem with implementing stubs for @WIN32{} functions is that it is -not sufficient to return a default value (usually 0) and leave the -stack the way we found it. For most @WIN32{} functions -- those that use -the @dfn{stdcall} calling convention -- the arguments sent to the function -are removed from the stack. - -Some background: On the i386 class of machines, stack entries are -usually dword (4 bytes) in size, little-endian. The stack grows -downward in memory. The stack pointer, maintained in the @samp{esp} -register, points to the last valid entry; thus, the operation of -pushing a value onto the stack involves decrementing @samp{esp} and then -moving the value into the memory pointed to by esp (i.e., @code{push p} -in assembly resembles @code{*(--esp) = p;} in C). Removing (popping) -values off the stack is the reverse (i.e., @code{pop p} corresponds to -@code{p = *(esp++);}). - -In the @dfn{stdcall} calling convention, arguments are pushed onto the -stack right-to-left. For example, the C call - -@example - myfunction(40, 20, 70, 30); -@end example - -is expressed in Intel assembly as: - -@example - push 30 - push 70 - push 20 - push 40 - call myfunction -@end example - -In addition, the called function is responsible for removing the -arguments off the stack. Thus, before the call to myfunction, the -stack would look like: - -@example - [local variable or temporary] - [local variable or temporary] - 30 - 70 - 20 - esp -> 40 -@end example - -After the call returns, it should look like: - -@example - [local variable or temporary] - esp -> [local variable or temporary] -@end example - -To restore the stack to this state, the called function must know how -many arguments to remove (which is the number of arguments it takes). -This is a problem if the function is undocumented. - -One way to attempt to document the number of arguments each function -takes is to create a wrapper around that function that detects the -stack offset. @file{WinRelay} (see below) was written to create such -wrappers. Essentially, each wrapper assumes that the function will take -a large number of arguments (by default, 64 in @file{WinRelay}). The -wrapper copies each of these arguments into its stack, calls the actual -function, and then calculates the number of arguments by checking esp -before and after the call. - -@cindex bsod (blue screen of death) -@cindex blue screen of death -The main problem with this scheme is that the function must actually -be called from another program. Many of these functions are seldom -used. An attempt was made to aggressively query each function in a -given library (@file{ntdll.dll}) by passing 64 arguments, all 0, to each -function. Unfortunately, @WINNT40{} quickly goes to a blue screen -of death (@dfn{bsod}), even if the program is run from a -non-administrator account. - -Another method that has been much more successful is to attempt to -figure out how many arguments each function is removing from the -stack. This instruction, @code{ret hhll} (where @samp{hhll} is the -number of bytes to remove, i.e. the number of arguments times 4), contains -the bytes @samp{0xc2 ll hh} in memory. It is a reasonable assumption -that few, if any, functions take more than 16 arguments; therefore, -@samp{hh} is 0x0 and @samp{ll} is less than 0x40. This utility, -@file{MakeSpec} (see below), simply queries the address of a function -and looks for the first occurrence of the bytes @samp{0xc2 ll 0x0}, -where @math{@samp{ll} <= 0x40}. - -Of course, this is not without errors. @code{ret 00ll} is not the only -instruction that can have the byte sequence @samp{0xc2 ll 0x0}; for -example, @code{push 0x000040c2} has the byte sequence -@samp{0x68 0xc2 0x40 0x0 0x0}, which matches the above. Properly, the -utility should look for this sequence only on an instruction boundary; -unfortunately, finding instruction boundaries on an i386 requires -implementing a full disassemble -- quite a daunting task. Besides, -the probability of having such a byte sequence that is not the actual -return instruction is fairly low. - -Much more troublesome is the non-linear flow of a function. For -example, consider the following two functions: - -@example - somefunction1: - jmp somefunction1_impl - - somefunction2: - ret 0004 - - somefunction1_impl: - ret 0008 -@end example - -@file{MakeSpec} would incorrectly list both @code{somefunction1} and -@code{somefunction2} as taking only a single argument, whereas -@code{somefunction1} really takes two arguments. - -With these limitations in mind, it is possible to implement more stubs -in Wine and, eventually, the functions themselves. - -@c end of quote - -The program @file{WinRelay} can be downloaded from -@url{http://www.ece.cmu.edu/afs/ece/usr/dacut/www/src}, -and @file{MakeSpec} will be available from the same location. You can -compile them with Borland's C++Builder; you should not optimize when -compiling (@file{WinRelay} needs the stack frames). - - -@node Implementing an API type, Implementing an API function, Investigating the undocumented API, The Wine Project -@section Implementing an API type - -Here is a checklist that should help you writing your first API type. It -will of course not tell you which elements to put into the type -(assuming it is a structure), but it should help you along the way of -integrating this type into Wine. -@xref{Implementing an API function}, for comparison. - -@enumerate -@item -Find out how the type should be named in Wine and in the DLL's. -@xref{API function and type naming}, for details. - -@item -Find out where the type should go. Please try to keep the header files -structure as similar to @mswindows{} as possible. - -@item -Prepare for the later patch (by saving the original files before you -work on them). @xref{Creating patches}, for details. - -@item -Put the type declaration into the header file. - -@item -Make sure the declaration is syntactically correct, i.e. it does not -keep Wine from compiling. - -@item -Make sure the declared type is layout-compatible with -@mswindows{}-compiled types. Especially keep an eye on the packing of -the structure. -@* FIXME: a reference to packed structures here. - -@item -Build Wine and test the type, if possible. If you cannot test the -type by implementing a proper API function, write a small test program -to test it on its own. Or rather stop here. - -@item -Write the documentation of the type in the @file{wine.texinfo} -file. @xref{Adding Documentation}, for details. -With types, be especially careful and document all the details. Also -document all constants or flags that are used in the type. - -@item -Create an entry in the @file{ChangeLog} file. - -@item -Collect some of these changes, and create a patch. @xref{Creating -patches}, for details. - -@item -Mail the patch to Alexandre Julliard, @email{julliard@@winehq.com}. - -@item -Wait for the patch to appear in the official distribution. -@end enumerate - - -@node Implementing an API function, API function and type naming, Implementing an API type, The Wine Project -@section Implementing an API function - -Here is a checklist that should help you writing your first API -function. It will of course not tell you what to do in the function, -but it should help you along the way of integrating this function into -Wine. - -@enumerate -@item -Make sure all data types that appear in function arguments are properly -declared in Wine. Otherwise, start with the data types. - -@item -Find out how the function should be named in Wine and in the DLL's. -@xref{API function and type naming}, for details. - -@item -Find out what the function should do. This may be tricky for -undocumented functions. @xref{Getting information on the API}, for some -hints. - -@item -Find out where the function should go: -@enumerate -@item -Which header file for the prototype. -@item -Which C source file. -@item -Which DLL(s), and which ordinal the function will take there. Perhaps -the function name is already present in one of the @file{.spec}-files in -the @file{if1632} directory. -@end enumerate - -@item -Prepare for the later patch (by saving the original files before you -work on them). @xref{Creating patches}, for details. - -@item -Put the prototype into the header file, and the code into the C file. - -@item -Make sure the code compiles. - -@item -Create or change the information for the DLL entry points in the -@file{.spec}-file in the @file{if1632} directory. -@xref{The build program}, for details of the DLL spec files. - -@item -Build Wine and test the function, if possible. If you cannot test the -function in Wine, write a small test program to test it on its own. - -@item -Write the documentation of the function in the @file{wine.texinfo} -file. @xref{Adding Documentation}, for details. - -@item -Create an entry in the @file{ChangeLog} file. - -@item -Collect some of these changes, and create a patch. @xref{Creating -patches}, for details. - -@item -Mail the patch to Alexandre Julliard, @email{julliard@@winehq.com}. - -@item -Wait for the patch to appear in the official distribution. -@end enumerate - - -@node API function and type naming, Creating patches, Implementing an API function, The Wine Project -@section API function and data type naming conventions -@cindex API function names -@cindex API type names -@cindex names of API functions and types -@cindex naming scheme for API functions and types -@cindex suffixes for API functions and types -@cindex endings of API function and type names - -This section describes Wine's naming scheme for API functions and data -types. - -The purpose of these naming conventions is to ensure that -@itemize @bullet -@item -both the @WIN16{} and @WIN32{} API are supported within the same source -code, -@item -both wide character functions (with @unicode{} strings) and 8 bit -character functions (with @ascii{} or extended @ascii{} encoding) are -supported, and -@item -the source code can be shared between the emulator and the library -version of Wine. -@end itemize - -A function or data type whose name in the @mswindows{} API is @var{xxx} -will in the Wine code have the following name(s): -@table @code -@item @var{xxx}16 -This is the version for the 16 bit API. You might call it the ``16 bit -version'' except that the function itself of course runs in true 32 bit -mode (being part of Wine). So, the correct meaning of the suffix is that -this function is part of the 16 bit API. -@item @var{xxx}32 -This is the version for the 32 bit API. Use this suffix only if the -function does not use character strings in its parameters or return -values. Otherwise use the next two. -@item @var{xxx}32A -This is the version for the 32 bit API which uses @ascii{} strings (or -rather, strings with 8 bit character encodings, i.e. the standard C -@code{char} type). This version always goes together with another -version, using the next suffix. -@item @var{xxx}32W -This is the version for the 32 bit API which uses @unicode{} strings, -i.e. strings with wide characters. It goes together with the @ascii{} -version. -@end table - -So, where the @mswindows{} API offers one name, Wine actually has two or -three different functions implemented (which will hopefully share a -large part of the code). - -Wine allows to use its API functions in two ways. The emulator part of -Wine provides DLL's for the @mswindows{} programs it can run. The -library part of Wine provides a @unix{} programmer with the facility to -use the Wine API's in a standard @unix{} program. - -@menu -* Access from the emulator:: How to access API functions and types - from applications that are run in the - Wine emulator. -* Access in the library:: How to access API functions and types - from applications that are linked with - the Wine library. -* Access from inside Wine:: How to access API functions and types - from inside the Wine code. -@end menu - -@node Access from the emulator, Access in the library, , API function and type naming -@subsection Accessing API functions and types from the emulator -@cindex access to DLL API functions and types -@cindex Wine emulator access to API functions and types -@cindex emulator access to Wine API functions and types - -The emulator part of Wine provides the hooks for dynamically linking the -API functions to the @mswindows{} executables (@file{.EXE}-files). The -Wine emulator contains all versions (16 or 32 bit, @ascii{} or -@unicode{}) of the API functions in one executable. The emulator -performs a mapping from the @mswindows{} name of the function, -by which the executable calls it, to one of the Wine internal names that -have been used in coding it. - -This mapping is done by the built-in DLL handling code of Wine. A -programmer of Wine has to declare the function in one of the virtual -DLL's that are provided by Wine. The declarations are done in the -@file{.spec}-files in the @file{if1632/} directory. @xref{The build -program}, for details. - -The @mswindows{} application simply calls the API function by its -standard @mswindows{} name. Wine will apply the correct mapping -according to Wine's selected appearance (as a 16 bit or 32 bit emulator, -which is a parameter on invocation of Wine). - - -@node Access in the library, Access from inside Wine, Access from the emulator, API function and type naming -@subsection Accessing API functions and types in the library -@cindex Wine library API function and type access -@cindex access to Wine library API functions and types - -If Wine is built as a library, and linked to a user-level main program, -the user will also use the standard @mswindows{} names for the API -functions. - -Some macros are defined in @file{include/wintypes.h} which perform the -necessary name mappings. - -These macros are (see the examples below): -@deffn_winemacro WINELIB_NAME (@var{xxx}) -This macro replaces @var{xxx} by one of @var{xxx}16 or -@var{xxx}32, depending on the definition of the symbols -@code{WINELIB16} and @code{WINELIB32}. @var{xxx} should -be the name of an API function that uses no string arguments. -Use this macro with a @code{#define} to establish the API name @var{xxx}. -@end deffn -@deffn_winemacro WINELIB_NAME_AW (@var{xxx}) -This macro replaces @var{xxx} by one of @var{xxx}16, @var{xxx}32A, or -@var{xxx}32W, depending on the definition of the symbols -@code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. @var{xxx} should -be the name of an API function that uses string arguments. -Use this macro with a @code{#define} to establish the API name @var{xxx}. -@end deffn -@deffn_winemacro DECL_WINELIB_TYPE (@var{xxx}) -This macro declares @var{xxx} to be an equivalent to @var{xxx}16 or -@var{xxx}32, depending on the definition of the symbols -@code{WINELIB16} and @code{WINELIB32}. @var{xxx} should -be the name of an API data type that contains no string arguments. -@end deffn -@deffn_winemacro DECL_WINELIB_TYPE_AW (@var{xxx}) -This macro declares the type @var{xxx} to be an equivalent to -@var{xxx}16, @var{xxx}32A, or @var{xxx}32W, depending on the definition -of the symbols @code{WINELIB16}, @code{WINELIB32}, and -@code{UNICODE}. @var{xxx} should be the name of an API data type that -contains string arguments. -@end deffn - -If Wine is compiled as an emulator, these macros have no effect, for the -mapping is then done by the DLL code. This means that within Wine the -name @var{xxx} itself will not be defined. - -Note: If the definition of @var{xxx} is exactly the same in @WIN16{} and -@WIN32{}, you can simply use the same name as @mswindows{}. - -Here are some examples: -@example -/* A simple type without strings */ -typedef short INT16; -typedef int INT32; -DECL_WINELIB_TYPE(INT); - -/* A type with strings */ -typedef struct @{ /* Win32 ASCII data structure */ @} WNDCLASS32A; -typedef struct @{ /* Win32 Unicode data structure */ @} WNDCLASS32W; -typedef struct @{ /* Win16 data structure */ @} WNDCLASS16; -DECL_WINELIB_TYPE_AW(WNDCLASS); - -/* A function with strings */ -ATOM RegisterClass16( WNDCLASS16 * ); -ATOM RegisterClass32A( WNDCLASS32A * ); -ATOM RegisterClass32W( WNDCLASS32W * ); -#define RegisterClass WINELIB_NAME_AW(RegisterClass) -@end example - -The Winelib user can then say (in the application program): -@example - INT i; - WNDCLASS wc = @{ @dots{} @}; - RegisterClass( &wc ); -@end example -and this will use the correct declaration depending on the definitions -@code{WINELIB16}, @code{WINELIB32}, and @code{UNICODE}. - -Here are the primary defines that are used when Wine is compiled as a -library: -@defvr_cwine WINELIB16 -If this @code{#define} is set, the Wine library is to be compiled in its -16 bit form. That means, the 16 bit variants of all functions will be -used and the appearance of the application linked with the Wine library -will be that of a 16 bit application. Of course, both the application -and the Wine library function really run in 32 bit mode. The switch only -selects the function with the name ending in @code{@dots{}16}, which -will perhaps have a behaviour different from its 32 bit counterpart. -@end defvr -@defvr_cwine WINELIB32 -If this @code{#define} is set, the Wine library is to be compiled in its -32 bit form. That means, the 32 bit variants of all functions will be -used and the appearance of the application linked with the Wine library -will be that of a 32 bit application. -@end defvr -@defvr_cwine UNICODE -This @code{define} is used to select one of two possible 32 bit -variants. Functions and data types of the 32 bit API come in two -flavours: one handling @ascii{} strings (or rather strings with -characters encoded in 8 bit), the other @unicode{} strings. This define -selects the correct variant. As a user of the Wine library, you are -responsible to use the correct character type in your part of the -application which accesses the Wine API functions and data types. -@end defvr - -These switches are automatically set when Wine is compiled as a library. - - -@node Access from inside Wine, , Access in the library, API function and type naming -@subsection Accessing API functions from within Wine -@cindex explicit names of API functions and types - -Within Wine and during the compilation of Wine, you cannot rely on the -@mswindows{} names of the API functions and data types. If Wine is -compiled as a library, they will be defined; if Wine is compiled as an -emulator, they won't. - -You therefore have to access all functions and data types by their full -names, with the proper suffix explicitly appended. In Wine, the 16 bit -and 32 bit versions of the functions are distinct entities, which might -(theoretically) show a completely different behaviour. They may even -call each other (and they will quite frequently). - -Therefore Wine is a conglomerate that contains all two or -three flavours of each function at once, and exports to the -application whichever of these is appropriate. Remember that inside -Wine, there is no memory segmentation, so all functions are 32 bit. -The 16-to-32 bit mapping is done on exporting the DLL functions. - - -@node Creating patches, Adding Documentation, API function and type naming, The Wine Project -@section Creating patches -@xref{Applying patches}, for instructions on applying patches. - -Patches are created with the program @code{diff}. You need a copy -of clean source tree to diff against. The @samp{-u} option, to create -unified diffs, is popular but not obligatory. -For changes to a single file, -@code{diff -u wine990101/windows/win.c mywine/windows/win.c > win_patch} -is sufficient. -To generate a complete diff between your tree and the distribution, -use @code{diff -uR wine990101 mywine}. - -This assumes that the original distribution and your personal tree -have the same parent directory, from which you make the diff. -This ensures a consistent format for the diffs, which in turn -is necessary so that they can be applied consistently as described in -@xref{Applying patches}. - -@node Adding Documentation, File names, Creating patches, The Wine Project -@section Adding Documentation - -@ifinfo -Here are some templates which should help you collaborate on this -documentation. Read the text below before examining them. -@end ifinfo - -@menu -* Type Template:: How to document data types in Wine's - include files. -* Function Template:: How to document an (API) function of - Wine. -@end menu - - -These are my tips for adding documentation. - -Do not simply copy documentation from @mswindows{} related -material. Except from risking copyright violations, which you would not -want to do, there is another aspect to that: -As Wine is a product to run on @unix{} and @unix{}-like workstations, -it seems a good idea to me to organize this documentation primarily for -the well-trained @unix{} reader. Please keep that in mind when you add -some documentation. - -Finally, read the info pages for @code{texinfo}. - -The rest of this section provides some templates which can serve as a -start in writing documentation. - -@subsection Template introduction -@iftex -On the following pages you will find some @code{texinfo} templates, which -should help you collaborate on this documentation. -@end iftex - -These templates give hints on how to document data types, functions, -variables, constants etc. in Wine. -As documentation evolves, you will find common features of data types -that should be described in a unified fashion. In such a case, please -add a corresponding style guide-line here, in this very place, to help -keeping documentation of data types unified. - - -Start out the type or function with a new node. Write a comment before -the node, listing all data types (and functions) described in the node, -like this: -@example -@@c -@@c *** struct FILETIME *** -@@c -@@node Type FILETIME, NextNodeName, PreviousNodeName, ParentNodeName -@end example - -The node command describes the node name and the names of the next node, -the previous node, and the parent node. The parent node should contain -a menu entry for this node. The previous node is the node that appears -before this node in the parent node menu. The next node is the node -succeeding this one in the parent node menu. If there is no previous or -next node, omit the name (putting just a single space between the two -commata). - -The node name must be a unique sequence of words. Case is important, so -@emph{Type} and @emph{type} are distinct. The node name must not contain -special characters like @samp{@@, @{, @}} or the comma. If you need to -give a node the same name as a function, data type, etc., use the words -@samp{Type}, @samp{Function}, etc. before the identifier. - -Always put the names of the node and its links on the same line, even if -it gets rather long. - -If there are two or more data types or functions described in the node, -adapt the comment like this: -@example -@@c -@@c *** int X *** -@@c *** long Y() *** -@@c -@@node Ints and Longs, NextNodeName, PreviousNodeName, ParentNodeName -@end example - -After the node name, put a sectioning command, such as @samp{@@chapter}, -@samp{@@section}, @samp{@@subsection}, or @samp{@@subsubsection}. -Without that command, cross references to the node will fail. -@example -@@subsubsection Type FILETIME -@end example - -Start the description of the type(s) or function(s) with a single -non-indented paragraph that gives a one-line description of the type(s) -or function(s) and states the include files that are required. -@example -@@noindent -File times in Wine are specified by the data type @@code@{FILETIME@}, -defined in @@file@{windows.h@}. -@end example -If several types or functions are closely connected, use one paragraph -as a common description. If more paragraphs are required for a proper -description, indent all but the first of them. - -Then start the definition of the data type or function. Use the proper -macro, which you will find defined in the beginning of the texinfo file. -If appropriate, add your own macros. -Again, put everything that belongs to the header into a single line. -Use continuation lines for additional headers. -@example -@@deftp_w32 FILETIME -@@deftpx_w32 LPFILETIME -@end example - -In the definition, give a verbal explanation of the data type or -function. The explanation should be rather complete, exact, and -comprehensible, than well-structured. This is the point where you can -tell everything you want. Do not be afraid of wasting space. -Do not describe the @mswindows{} situation but only say what Wine -does. That is important. (Sometimes they might even do the same.) -@example -This is the data type for specifying file times. The file times are -stored with 64 bit precision. The actual data type is a structure with -two 32 bit values which are interpreted as the low and high parts of a -64-bit value. This value gives a time measured in a granularity of 100 -nanoseconds, so 1.5 seconds are specified by a value of 15,000,000. In -Wine, this 64-bit value is signed, with the sign taken from the high -part. The lower part is used as unsigned. -@end example - -For data types, it is recommended to quote the definition from the -header file. For a function, you might give a short example of its -usage. You may also put one example in the end of a node that explains -several of the functions in the node. Remember that cut-and-paste from a -well prepared example will help the readers write their code. -@example -The definition of @@code@{FILETIME@} reads: -@@example -typedef struct -@@@{ - INT32 dwLowDateTime; - INT32 dwHighDateTime; -@@@} FILETIME, *LPFILETIME; -@@end example -@end example - -You could also use the @code{cindex} command which creates an entry in -the concept index. The @code{texinfo} manual recommends to keep concept -entries distinct, so that a single concept index entry puts to one -well-defined place in the document. Use lower case letters for index -entries, unless they are proper names or quotes from actual code. -@example -@@cindex epoch in file time -The @@code@{FILETIME@} structure may be used to hold absolute or relative -times. Absolute times are given as the number of 100 nanoseconds -intervals elapsed since 1 January 1601, 00:00:00 UTC (Coordinated -Universal Time, which is GMT, Greenwich Mean Time). This might be -called the @@dfn@{epoch@} for file times. With a signed 64-bit value, this -representation covers absolute times of 29247 years around the epoch. -@end example - -After the verbal documentation, you can add some special fields -describing bugs, implementation dependencies etc. Two of these are -recommended to attach to all descriptions. One describes the -conformance of the data type or function to @mswindows{} products, -i.e. whether the item is also present in @WINNT{} and @WIN95{}. The -other one describes known differences of the Wine item to its -@mswindows{} counterpart. Both will greatly help in porting software -from @mswindows{} to Wine and vice versa. -@example -@@winconfall@{@} - -@@windiff@{@} -In @@mswindows@{@}, the elements of the structure are apparently of type -@@code@{DWORD@}. Whether the full 64 bit value is interpreted as signed or -unsigned I do not know. -@end example - -If you find that more of these property attributes are necessary, feel -free to create your own ones. But keep in mind that they should be -applicable more or less to all described items. Very special properties -will better be put into the verbal text. - -Finally end the definition of the data type or function: -@example -@@end deftp -@end example - -Do not forget to enter the node in the menu of its top node, and do -properly link the node to its successor and predecessor. - - - - - - -@node Type Template, Function Template, , Adding Documentation -@subsection Data type template - -Category: Data type - -@node Function Template, , Type Template, Adding Documentation -@subsection API function template - -Functions should be given category names, to indicate which API they -belong to. Please add items to the list of categories possible. - -Category: WIN32 function - -@example -@@c -@@c ***GetFileTime() *** -@@c -@@node Get File Times, , Compare File Times, File Times -@@noindent -The Wine function @@code@{GetFileTime@} returns the creation time and -the times of last the read and modification access to a file. It is -defined in @@file@{windows.h@}. - -@@deftypefn_w32 BOOL GetFileTime (@@w@{HANDLE @@var@{file@},@} @@w@{LPFILETIME @@var@{ctime@},@} @@w@{LPFILETIME @@var@{atime@},@} @@w@{LPFILETIME @@var@{mtime@})@} -This function obtains for the specified @@var@{file@} the creation time -@@var@{ctime@}, the time of the last access to the file @@var@{atime@}, and -the time of the last modification (write) to the file, @@var@{mtime@}. -The @@var@{file@} handle must have been obtained by opening the file with -@@code@{GENERIC_READ@} access. The file time arguments of this function are -pointers to @@code@{FILETIME@} variables, which are filled with a value that -indicates an absolute time in UTC. To convert these values to local -times, use the function @@code@{FileTimeToLocalFileTime@}. If you do not -need some of the times, you can pass a @@code@{NULL@} pointer. -The function returns @@code@{TRUE@} on success, @@code@{FALSE@} on failure. - -@@winconfall@{@} - -@@windiffnone@{@} -@@end deftypefn -@end example - - -@node File names, Wide character strings, Adding Documentation, The Wine Project -@section @mswindows{} and @unix{} file names in Wine -@cindex file names in Wine -@cindex Windows file names -@cindex DOS file names in Wine -@cindex UNIX file names in Wine -@cindex POSIX file names in Wine - -FIXME: - -@node Wide character strings, , File names, The Wine Project -@section Wide character strings in API functions -@cindex unicode strings in API functions -@cindex wide character strings in API functions -@cindex strings in API functions -@cindex ascii strings in API functions -@cindex 16 bit characters in API functions -@cindex wchar_t in API functions - -Presently, all wide character strings in API functions of Wine are -internally converted to 8 bit representation. Thus, the @WIN32{} API -with @unicode{} strings is not fully functional for the application -programmer at present. - -Even so, application programmers might consider developing their -applications in wide character format with Wine, as future versions -might bring a change. This might come when a @unix{} filesystem can -handle @unicode{} file names. - -Furthermore, the @unicode{} API is required to let Wine run @mswindows{} -applications which have been compiled for wide character strings. - -In Wine, wide characters are strictly 16 bit; the @code{wchar_t} type of -standard C can therefore not be used. - -@node Concept Index, , , Top -@comment node-name, next, previous, up -@unnumbered Concept Index -@printindex cp - -@node Type Index, , , Top -@comment node-name, next, previous, up -@unnumbered Type Index -@printindex tp - -@node Function Index, , , Top -@comment node-name, next, previous, up -@unnumbered Function Index -@printindex fn - -@node Variable Index, , , Top -@comment node-name, next, previous, up -@unnumbered Variable, Constants, and Variable-like Macros Index -@printindex vr - -@node File Index, , , Top -@comment node-name, next, previous, up -@unnumbered File and Program Index -@printindex pg - - -@contents -@bye