mirror of
git://source.winehq.org/git/wine.git
synced 2024-08-31 10:34:07 +00:00
2286 lines
80 KiB
Plaintext
2286 lines
80 KiB
Plaintext
\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
|