Document BSTR functions, add SetOANoCache().

[wine/gsoc_dplay.git] / documentation / wine.texinfo

\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