| \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 |
| FIXME: X11 and POSIX trademarks. @* |
| UNIX is a registered trademark of the Open Group. |
| 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 |
| FIXME: UNIX and POSIX trademarks. @* |
| X11 @* |
| 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 |
| @include 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@@lrc.epfl.ch} |
| |
| |
| |
| @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. Files in Wine do not have this attribute. (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@@lrc.epfl.ch}. |
| |
| @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@@lrc.epfl.ch}. |
| |
| @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 |