Commit | Line | Data |
---|---|---|
692389d0 DR |
1 | This document should help new developers get started. Like all of Wine, it |
2 | is a work in progress. | |
dba420a7 | 3 | |
0a7aa169 | 4 | |
889f7424 AJ |
5 | SOURCE TREE STRUCTURE |
6 | ===================== | |
7 | ||
692389d0 DR |
8 | The Wine source tree is loosely based on the original Windows modules. |
9 | Most of the source is concerned with implementing the Wine API, although | |
10 | there are also various tools, documentation, sample Winelib code, and | |
344ed41d JS |
11 | code specific to the binary loader. Note that several of the libraries |
12 | listed here are "stubbed out", meaning they still need to be implemented. | |
889f7424 | 13 | |
ab9cd6e4 DP |
14 | DLLs (under dlls/): |
15 | ------------------- | |
889f7424 | 16 | |
ab9cd6e4 | 17 | advapi32/ - Crypto, systeminfo, security, eventlogging |
d8f4a0ab | 18 | advpack/ - Reads and verifies .INF files |
c5da9b2f | 19 | amstream/ - MultiMedia Streams |
206937ec | 20 | atl/ - Active Template Library |
ab9cd6e4 DP |
21 | avicap32/ - AVI capture window class |
22 | avifil32/ - COM object to play AVI files | |
23 | cabinet/ - Cabinet file interface | |
24 | capi2032/ - Wrapper library for CAPI4Linux access | |
c5da9b2f | 25 | cards/ - Card graphics |
ab9cd6e4 DP |
26 | cfgmgr32/ - Config manager |
27 | comcat/ - Component category manager | |
28 | comctl32/ - Common controls | |
29 | commdlg/ - Common dialog boxes (both 16 & 32 bit) | |
30 | crtdll/ - Old C runtime library | |
31 | crypt32/ - Cryptography | |
1b5bc2a0 | 32 | cryptdll/ - Cryptography Manager |
ab9cd6e4 DP |
33 | ctl3d/ - 3D Effects for Common GUI Components |
34 | d3d8/ - Direct3D (3D graphics) | |
35 | d3d9/ - Direct3D (3D graphics) | |
36 | d3dim/ - Direct3D Immediate Mode | |
8f14eb0e | 37 | d3drm/ - Direct3D Retained Mode |
ab9cd6e4 | 38 | d3dx8/ - Direct3D (3D graphics) |
49e5fda6 | 39 | d3dxof/ - DirectX Files Functions |
c5da9b2f | 40 | dbghelp/ - Engine for symbol and module enumeration |
ab9cd6e4 DP |
41 | dciman32/ - DCI Manager (graphics) |
42 | ddraw/ - DirectDraw (graphics) | |
43 | devenum/ - Device enumeration (part of DirectShow) | |
44 | dinput/ - DirectInput (device input) | |
45 | dinput8/ - DirectInput (device input) | |
c24c30ff TW |
46 | dmband/ - DirectMusic Band |
47 | dmcompos/ - DirectMusic Composer | |
48 | dmime/ - DirectMusic Interactive Engine | |
49 | dmloader/ - DirectMusic Loader | |
50 | dmscript/ - DirectMusic Scripting | |
51 | dmstyle/ - DirectMusic Style Engine | |
52 | dmsynth/ - DirectMusic Software Synthesizer | |
53 | dmusic/ - DirectMusic Core Services | |
54 | dmusic32/ - DirectMusic Legacy Port | |
ab9cd6e4 DP |
55 | dplay/ - DirectPlay (networking) |
56 | dplayx/ - DirectPlay (networking) | |
c5da9b2f | 57 | dpnet/ - DirectPlay (networking) |
c24c30ff | 58 | dpnhpast/ - DirectPlay NAT Helper PAST |
ab9cd6e4 | 59 | dsound/ - DirectSound (audio) |
d9e53caa | 60 | dswave/ - DirectMusic Wave |
c5da9b2f | 61 | dxdiagn/ - DirectX Diagnostic Tool |
ab9cd6e4 | 62 | gdi/ - GDI (graphics) |
ab9cd6e4 | 63 | glu32/ - OpenGL Utility library (graphics) |
7470fa73 | 64 | glut32/ - OpenGL Utility Toolkit |
c5da9b2f | 65 | hhctrl.ocx/ - HHCTRL OCX implementation |
d9e53caa | 66 | iccvid/ - Radius Cinepak Video Decoder |
ab9cd6e4 | 67 | icmp/ - ICMP protocol (networking) |
29872b8b | 68 | ifsmgr.vxd/ - IFSMGR VxD implementation |
ab9cd6e4 DP |
69 | imagehlp/ - PE (Portable Executable) Image Helper lib |
70 | imm32/ - Input Method Manager | |
71 | iphlpapi/ - IP Helper API | |
91207428 | 72 | itss/ - Infotech Structured Storage (HTML Help) |
ab9cd6e4 DP |
73 | kernel/ - The Windows kernel |
74 | lzexpand/ - Lempel-Ziv compression/decompression | |
75 | mapi32/ - Mail interface | |
49e5fda6 | 76 | mlang/ - Multi Language Support |
29872b8b DP |
77 | mmdevldr.vxd/ - MMDEVLDR VxD implementation |
78 | monodebg.vxd/ - MONODEBG VxD implementation | |
ab9cd6e4 DP |
79 | mpr/ - Multi-Protocol Router (networking) |
80 | msacm/ - Audio Compression Manager (multimedia) | |
7470fa73 DP |
81 | msacm/imaadp32/ - IMA ADPCM Audio Codec |
82 | msacm/msadp32/ - MS ADPCM Audio Codec | |
83 | msacm/msg711/ - MS G711 Audio Codec (includes A-Law & MU-Law) | |
84 | msacm/winemp3/ - Mpeg Layer 3 Audio Codec | |
5164757c | 85 | mscms/ - Color Management System |
ab9cd6e4 | 86 | msdmo/ - DirectX Media Objects |
7470fa73 | 87 | mshtml/ - MS HTML component |
c5da9b2f | 88 | msi/ - Microsoft Installer |
ab9cd6e4 DP |
89 | msimg32/ - Gradient and transparency (graphics) |
90 | msisys/ - System information | |
ab9cd6e4 | 91 | msnet32/ - Network interface |
49e5fda6 | 92 | msrle32/ - Video codecs |
ab9cd6e4 DP |
93 | msvcrt/ - C runtime library |
94 | msvcrt20/ - C runtime library version 2.0 | |
d9e53caa | 95 | msvcrt40/ - C runtime library version 4.0 |
ab9cd6e4 | 96 | msvcrtd/ - C runtime library debugging |
d9e53caa | 97 | msvidc32/ - Microsoft Video-1 Decoder |
ab9cd6e4 | 98 | msvideo/ - 16 bit video manager |
ab9cd6e4 DP |
99 | mswsock/ - Misc networking |
100 | netapi32/ - Network interface | |
c24c30ff | 101 | newdev/ - New Hardware Device Library |
ab9cd6e4 DP |
102 | ntdll/ - NT implementation of kernel calls |
103 | odbc32/ - Open DataBase Connectivity driver manager | |
104 | ole32/ - 32 bit OLE 2.0 libraries | |
7470fa73 | 105 | oleacc/ - OLE accessibility support |
ab9cd6e4 DP |
106 | oleaut32/ - 32 bit OLE 2.0 automation |
107 | olecli/ - 16 bit OLE client | |
108 | oledlg/ - OLE 2.0 user interface support | |
109 | olepro32/ - 32 bit OLE 2.0 automation | |
110 | olesvr/ - 16 bit OLE server | |
111 | opengl32/ - OpenGL implementation (graphics) | |
250a8aec | 112 | powrprof/ - Power Management and Profiling |
ab9cd6e4 DP |
113 | psapi/ - Process Status interface |
114 | qcap/ - DirectShow runtime | |
115 | quartz/ - DirectShow runtime | |
116 | rasapi32/ - Remote Access Server interface | |
a812b61d | 117 | riched20/ - Rich text editing control version 2.0 |
ab9cd6e4 DP |
118 | richedit/ - Rich text editing control |
119 | rpcrt4/ - Remote Procedure Call runtime | |
8e7f81c4 | 120 | rsabase/ - RSA encryption |
d8f4a0ab | 121 | rsaenh/ - Crypto API that provides algorithms for DES, 3DES, and RSA among others |
c5da9b2f | 122 | secur32/ - Contains Windows Security functions |
a812b61d | 123 | sensapi/ - System Event Notification Service |
ab9cd6e4 DP |
124 | serialui/ - Serial port property pages |
125 | setupapi/ - Setup interface | |
126 | shdocvw/ - Shell document object and control | |
ab9cd6e4 | 127 | shell32/ - COM object implementing shell views |
c5da9b2f | 128 | shfolder/ - Shell folder service |
ab9cd6e4 DP |
129 | shlwapi/ - Shell Light-Weight interface |
130 | snmpapi/ - SNMP protocol interface (networking) | |
1b5bc2a0 | 131 | stdole32.tlb/ - Standard OLE typelib |
ab9cd6e4 DP |
132 | sti/ - Still Image service |
133 | tapi32/ - Telephone interface | |
134 | ttydrv/ - TTY display driver (Wine specific) | |
135 | twain/ - TWAIN Imaging device communications | |
7470fa73 | 136 | unicows/ - Unicows replacement (Unicode layer for Win9x) |
ab9cd6e4 DP |
137 | url/ - Internet shortcut shell extension |
138 | urlmon/ - URL Moniker allows binding to a URL (like KIO/gnome-vfs) | |
139 | user/ - Window management, standard controls, etc. | |
140 | uxtheme/ - Theme library | |
29872b8b | 141 | vdhcp.vxd/ - VDHCP VxD implementation |
49e5fda6 | 142 | vdmdbg/ - Virtual DOS machine debug library |
ab9cd6e4 | 143 | version/ - File installation library |
31dd689b | 144 | vmm.vxd/ - VMM VxD implementation |
c5da9b2f | 145 | vnbt.vxd/ - VNBT VxD implementation |
29872b8b DP |
146 | vnetbios.vxd/ - VNETBIOS VxD implementation |
147 | vtdapi.vxd/ - VTDAPI VxD implementation | |
148 | vwin32.vxd/ - VWIN32 VxD implementation | |
ab9cd6e4 DP |
149 | win32s/ - 32-bit function access for 16-bit systems |
150 | winaspi/ - 16 bit Advanced SCSI Peripheral Interface | |
7470fa73 | 151 | wined3d/ - Wine internal Direct3D helper |
ab9cd6e4 DP |
152 | winedos/ - DOS features and BIOS calls (interrupts) (wine specific) |
153 | wineps/ - Postscript driver (Wine specific) | |
154 | wininet/ - Internet extensions | |
155 | winmm/ - Multimedia (16 & 32 bit) | |
156 | winmm/joystick/ - Joystick driver | |
157 | winmm/mcianim/ - MCI animation driver | |
158 | winmm/mciavi/ - MCI video driver | |
159 | winmm/mcicda/ - MCI audio CD driver | |
160 | winmm/mciseq/ - MCI MIDI driver | |
161 | winmm/mciwave/ - MCI wave driver | |
162 | winmm/midimap/ - MIDI mapper | |
163 | winmm/wavemap/ - Audio mapper | |
164 | winmm/winealsa/ - ALSA audio driver | |
165 | winmm/winearts/ - aRts audio driver | |
166 | winmm/wineaudioio/ - audioio audio driver | |
167 | winmm/winejack/ - JACK audio server driver | |
168 | winmm/winenas/ - NAS audio driver | |
169 | winmm/wineoss/ - OSS audio driver | |
170 | winnls/ - National Language Support | |
171 | winsock/ - Sockets 2.0 (networking) | |
ab9cd6e4 | 172 | winspool/ - Printing & Print Spooler |
c5da9b2f | 173 | wintab32/ - Tablet device interface |
ab9cd6e4 DP |
174 | wintrust/ - Trust verification interface |
175 | wow32/ - WOW subsystem | |
c5da9b2f | 176 | wsock32/ - Sockets 1.1 (networking) |
a812b61d | 177 | wtsapi32/ - Terminal Services |
ab9cd6e4 | 178 | x11drv/ - X11 display driver (Wine specific) |
c513a30e | 179 | |
ab9cd6e4 DP |
180 | Winelib programs (under programs/): |
181 | ----------------------------------- | |
c513a30e | 182 | |
ab9cd6e4 DP |
183 | avitools/ - AVI information viewer and player |
184 | clock/ - Graphical clock | |
185 | cmdlgtst/ - Common dialog tests | |
186 | control/ - Control panel | |
187 | expand/ - Decompress Lempel-Ziv compressed archive | |
3565f5fa | 188 | msiexec/ - Microsoft Installer frontend |
26fe914d | 189 | notepad/ - Notepad replacement |
ab9cd6e4 DP |
190 | progman/ - Program manager |
191 | regedit/ - Registry editor | |
192 | regsvr32/ - Register COM server | |
193 | rpcss/ - RPC services | |
194 | rundll32/ - Execute DLL functions directly | |
195 | start/ - Replacement for start.exe | |
26fe914d | 196 | taskmgr/ - Manage running Windows/Winelib applications |
ab9cd6e4 DP |
197 | uninstaller/ - Remove installed programs |
198 | view/ - Metafile viewer | |
199 | wcmd/ - Command line interface | |
200 | wineboot/ - Wine bootstrap process | |
201 | winecfg/ - Wine configuration utility | |
202 | wineconsole/ - Console | |
203 | winedbg/ - Debugger | |
204 | winefile/ - File manager | |
205 | winemenubuilder/ - Helper program for building Unix menu entries | |
206 | winemine/ - Mine game | |
207 | winepath/ - Translate between Wine and Unix paths | |
208 | winetest/ - Wine testing shell | |
209 | winevdm/ - Wine virtual DOS machine | |
210 | winhelp/ - Help viewer | |
211 | winver/ - Windows Version Program | |
c513a30e AJ |
212 | |
213 | ||
214 | Support programs, libraries, etc: | |
215 | --------------------------------- | |
692389d0 | 216 | |
cc02d954 RR |
217 | dlls/dxerr8/ - DirectX 8 error import lib |
218 | dlls/dxerr9/ - DirectX 9 error import lib | |
6d4e3923 | 219 | dlls/dxguid/ - DirectX UUID import lib |
d8f4a0ab | 220 | dlls/strmiids/ - Exports class (CLSIDs) and interface (IIDs) identifiers |
6d4e3923 | 221 | dlls/uuid/ - Windows-compatible UUID import lib |
c513a30e | 222 | documentation/ - some documentation |
6d4e3923 | 223 | documentation/samples/ - sample configuration files |
c513a30e | 224 | include/ - Windows standard includes |
6d4e3923 DP |
225 | include/msvcrt/ - MSVC compatible libc headers |
226 | include/wine/ - Wine specific headers | |
4ebc8067 | 227 | libs/ - the Wine libraries |
7d2aefd8 DP |
228 | libs/port/ - portability library |
229 | libs/unicode/ - Unicode support shared | |
7d2aefd8 DP |
230 | libs/wine/ - Wine bootstrap library |
231 | libs/wpp/ - C preprocessor | |
357c7401 | 232 | loader/ - the main Wine loader |
344ed41d | 233 | server/ - the Wine server |
6be1997b | 234 | tools/ - various tools used to build/check Wine |
6d4e3923 DP |
235 | tools/widl/ - the IDL compiler |
236 | tools/winapi{,_check}/ - A Win32 API checker | |
237 | tools/winebuild/ - Wine build tool | |
238 | tools/winedump/ - a .DLL dump utility | |
239 | tools/winegcc/ - a MinGW command line compatible gcc wrapper | |
240 | tools/wmc/ - the message compiler | |
241 | tools/wpp/ - the C pre-processor library | |
242 | tools/wrc/ - the resource compiler | |
889f7424 | 243 | |
889f7424 | 244 | |
0a7aa169 | 245 | |
c7c217b3 AJ |
246 | IMPLEMENTING NEW API CALLS |
247 | ========================== | |
248 | ||
c513a30e AJ |
249 | This is the simple version, and covers only Win32. Win16 is slightly |
250 | uglier, because of the Pascal heritage and the segmented memory model. | |
c7c217b3 | 251 | |
c513a30e AJ |
252 | All of the Win32 APIs known to Wine are listed in the .spec file of |
253 | their corresponding dll. An unimplemented call will look like (from | |
254 | gdi32.spec) | |
c7c217b3 AJ |
255 | 269 stub PolyBezierTo |
256 | To implement this call, you need to do the following four things. | |
257 | ||
258 | 1. Find the appropriate parameters for the call, and add a prototype to | |
0a7aa169 KG |
259 | the correct header file. In this case, that means [include/wingdi.h], |
260 | and it might look like | |
9f69d893 AJ |
261 | BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD); |
262 | If the function has both an ASCII and a Unicode version, you need to | |
263 | define both and add a #define WINELIB_NAME_AW declaration. See below | |
264 | for discussion of function naming conventions. | |
c7c217b3 AJ |
265 | |
266 | 2. Modify the .spec file to tell Wine that the function has an | |
267 | implementation, what the parameters look like and what Wine function | |
268 | to use for the implementation. In Win32, things are simple--everything | |
269 | is 32-bits. However, the relay code handles pointers and pointers to | |
270 | strings slightly differently, so you should use 'str' and 'wstr' for | |
271 | strings, 'ptr' for other pointer types, and 'long' for everything else. | |
9f69d893 AJ |
272 | 269 stdcall PolyBezierTo(long ptr long) PolyBezierTo |
273 | The 'PolyBezierTo' at the end of the line is which Wine function to use | |
c7c217b3 AJ |
274 | for the implementation. |
275 | ||
276 | 3. Implement the function as a stub. Once you add the function to the .spec | |
277 | file, you must add the function to the Wine source before it will link. | |
9f69d893 | 278 | Add a function called 'PolyBezierTo' somewhere. Good things to put |
c7c217b3 AJ |
279 | into a stub: |
280 | o a correct prototype, including the WINAPI | |
281 | o header comments, including full documentation for the function and | |
0a7aa169 | 282 | arguments (see documentation/README.documentation) |
c7c217b3 AJ |
283 | o A FIXME message and an appropriate return value are good things to |
284 | put in a stub. | |
285 | ||
286 | /************************************************************ | |
0a7aa169 KG |
287 | * PolyBezierTo (GDI32.269) |
288 | * | |
f554f8f5 | 289 | * Draw many Bezier curves. |
0a7aa169 | 290 | * |
d0bc4c26 DP |
291 | * PARAMS |
292 | * hdc [I] Device context to draw to | |
293 | * p [I] Array of POINT structs | |
294 | * count [I] Number of points in p | |
295 | * | |
0a7aa169 | 296 | * RETURNS |
f554f8f5 JG |
297 | * Success: Non-zero. |
298 | * Failure: FALSE. Use GetLastError() to find the error cause. | |
c7c217b3 AJ |
299 | * |
300 | * BUGS | |
301 | * Unimplemented | |
302 | */ | |
d0bc4c26 | 303 | BOOL WINAPI PolyBezierTo(HDC hdc, LPCVOID p, DWORD count) |
0a7aa169 | 304 | { |
d0bc4c26 | 305 | /* tell the user they've got a substandard implementation */ |
b9aba914 | 306 | FIXME("(%x,%p,%d): stub\n", hdc, p, count); |
d0bc4c26 DP |
307 | |
308 | /* some programs may be able to compensate, | |
309 | * if they know what happened | |
310 | */ | |
311 | SetLastError(ERROR_CALL_NOT_IMPLEMENTED); | |
312 | return FALSE; /* error value */ | |
c7c217b3 AJ |
313 | } |
314 | ||
0a7aa169 KG |
315 | 4. Implement and test the rest of the function. |
316 | ||
889f7424 | 317 | |
19dc2087 EP |
318 | IMPLEMENTING A NEW DLL |
319 | ====================== | |
320 | ||
31b41cf6 EP |
321 | Generic directions |
322 | ------------------ | |
323 | ||
19dc2087 EP |
324 | Apart from writing the set of needed .c files, you also need to do the |
325 | following: | |
326 | ||
327 | 1. Create a directory <MyDll> where to store the implementation of | |
c513a30e AJ |
328 | the DLL. This directory has to be put under the dlls/ directory. |
329 | If the DLL exists under Windows as both 16 and 32 bit DLL, you | |
330 | should have a single directory with both implementations. | |
19dc2087 EP |
331 | |
332 | 2. Create the Makefile.in in the ./dlls/<MyDll>/ directory. You can | |
333 | copy an existing Makefile.in from another ./dlls/ subdirectory. | |
c513a30e | 334 | You need at least to change the MODULE and C_SRCS macros. |
19dc2087 | 335 | |
c513a30e AJ |
336 | 3. Add the directory in ./configure.ac (in AC_OUTPUT macro at the end |
337 | of the file to trigger the Makefile generation) | |
19dc2087 | 338 | |
c513a30e AJ |
339 | 4. Run ./make_dlls in the dlls directory to update Makefile.in in |
340 | that directory. | |
19dc2087 | 341 | |
69653da2 | 342 | 5. You can now regenerate ./configure file (with 'autoconf') |
19dc2087 EP |
343 | and the various Makefiles (with 'configure; make depend') (run |
344 | from the top of Wine's tree). | |
c513a30e | 345 | You should now have a Makefile file in ./dlls/<MyDll>/ |
19dc2087 | 346 | |
c513a30e | 347 | 6. Create the .spec file for the DLL exported functions in your |
19dc2087 EP |
348 | directory. Refer to 'Implementation of new API calls' earlier in |
349 | this document for more information on this part. | |
350 | ||
c513a30e AJ |
351 | 7. You can now start adding .c files. For the .h files, if they are |
352 | standard Windows one, put them in include/. If they are linked to | |
353 | *your* implementation of the dll, put them in your newly created | |
354 | directory. | |
19dc2087 | 355 | |
31b41cf6 EP |
356 | Debug channels |
357 | -------------- | |
358 | ||
19dc2087 | 359 | If you need to create a new debug channel, just add the |
d95ce8ce DP |
360 | WINE_DEFAULT_DEBUG_CHANNEL to your .c file(s), and use them. |
361 | All the housekeeping will happen automatically. | |
19dc2087 | 362 | |
31b41cf6 EP |
363 | Resources |
364 | --------- | |
365 | ||
344ed41d | 366 | If you also need to add resources to your DLL, then create the .rc |
c513a30e AJ |
367 | file. Add to your ./dlls/<MyDll>/Makefile.in, in the RC_SRCS macro, |
368 | the list of .rc files to add to the DLL. See dlls/comctl32/ for an | |
369 | example of this. | |
31b41cf6 EP |
370 | |
371 | Thunking | |
372 | -------- | |
373 | ||
374 | If you're building a 16 & 32 bit DLLs pair, then from the 32 bit code | |
375 | you might need to call 16 bit routine. The way to do it to add in the | |
376 | code, fragments like: | |
377 | /* ### Start build ### */ | |
378 | extern WORD CALLBACK <PREFIX>_CallTo16_word_wwlll(FARPROC16,WORD,WORD,LONG,LONG,LONG); | |
379 | /* ### stop build ### */ | |
380 | Where <PREFIX>_ is an internal prefix for your module. The first | |
381 | parameter is always of type FARPROC16. Then, you can get the regular | |
382 | list of parameters. The _word_wwlll indicates the type of return (long | |
383 | or word) and the size of the parameters (here l=>long, w=>word; which | |
384 | maps to WORD,WORD,LONG,LONG,LONG. | |
385 | You can put several functions between the Start/Stop build pair. | |
386 | ||
c513a30e AJ |
387 | You can also read the winebuild manpage for more details on this. |
388 | ||
389 | Then, add to ./dlls/<MyDll>/Makefile.in a line like: | |
31b41cf6 | 390 | |
c513a30e | 391 | EXTRA_OBJS = $(MODULE).glue.o |
31b41cf6 EP |
392 | |
393 | See dlls/winmm/ for an example of this. | |
394 | ||
1285c2f9 AJ |
395 | MEMORY AND SEGMENTS |
396 | =================== | |
dba420a7 AJ |
397 | |
398 | NE (Win16) executables consist of multiple segments. The Wine loader | |
e2abbb1b AJ |
399 | loads each segment into a unique location in the Wine processes memory |
400 | and assigns a selector to that segment. Because of this, it's not | |
401 | possible to exchange addresses freely between 16-bit and 32-bit code. | |
402 | Addresses used by 16-bit code are segmented addresses (16:16), formed | |
403 | by a 16-bit selector and a 16-bit offset. Those used by the Wine code | |
404 | are regular 32-bit linear addresses. | |
dba420a7 | 405 | |
1e37a181 | 406 | There are four ways to obtain a segmented pointer: |
c513a30e | 407 | - Using the MapLS function (recommended). |
e2abbb1b AJ |
408 | - Allocate a block of memory from the global heap and use |
409 | WIN16_GlobalLock to get its segmented address. | |
e2abbb1b AJ |
410 | - Declare the argument as 'segptr' instead of 'ptr' in the spec file |
411 | for a given API function. | |
dba420a7 | 412 | |
e2abbb1b AJ |
413 | Once you have a segmented pointer, it must be converted to a linear |
414 | pointer before you can use it from 32-bit code. This can be done with | |
c513a30e AJ |
415 | the MapSL function. The linear pointer can then be used freely with |
416 | standard Unix functions like memcpy() etc. without worrying about 64k | |
417 | boundaries. Note: there's no easy way to convert back from a linear | |
418 | to a segmented address. | |
dba420a7 | 419 | |
e2abbb1b AJ |
420 | In most cases, you don't need to worry about segmented address, as the |
421 | conversion is made automatically by the callback code and the API | |
422 | functions only see linear addresses. However, in some cases it is | |
423 | necessary to manipulate segmented addresses; the most frequent cases | |
424 | are: | |
425 | - API functions that return a pointer | |
426 | - lParam of Windows messages that point to a structure | |
427 | - Pointers contained inside structures accessed by 16-bit code. | |
dba420a7 | 428 | |
e2abbb1b AJ |
429 | It is usually a good practice to used the type 'SEGPTR' for segmented |
430 | pointers, instead of something like 'LPSTR' or 'char *'. As SEGPTR is | |
431 | defined as a DWORD, you'll get a compilation warning if you mistakenly | |
432 | use it as a regular 32-bit pointer. | |
dba420a7 | 433 | |
1285c2f9 | 434 | |
2d93d000 AJ |
435 | STRUCTURE PACKING |
436 | ================= | |
437 | ||
438 | Under Windows, data structures are tightly packed, i.e. there is no | |
439 | padding between structure members. On the other hand, by default gcc | |
440 | aligns structure members (e.g. WORDs are on a WORD boundary, etc.). | |
441 | This means that a structure like | |
442 | ||
443 | struct { BYTE x; WORD y; }; | |
444 | ||
445 | will take 3 bytes under Windows, but 4 with gcc, because gcc will add a | |
446 | dummy byte between x and y. To have the correct layout for structures | |
0a7aa169 KG |
447 | used by Windows code, you need to embed the struct within two special |
448 | #include's which will take care of the packing for you: | |
449 | ||
450 | #include "pshpack1.h" | |
19dc2087 | 451 | struct { BYTE x; WORD y; }; |
0a7aa169 KG |
452 | #include "poppack1.h" |
453 | ||
454 | For alignment on a 2-byte boundary, there is a "pshpack2.h", etc. | |
455 | ||
2d93d000 | 456 | |
1285c2f9 AJ |
457 | NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES |
458 | ============================================== | |
459 | ||
460 | In order to support both Win16 and Win32 APIs within the same source | |
692389d0 | 461 | code, the following convention must be used in naming all API |
1285c2f9 AJ |
462 | functions and types. If the Windows API uses the name 'xxx', the Wine |
463 | code must use: | |
464 | ||
9f69d893 | 465 | - 'xxx16' for the Win16 version, |
d0bc4c26 | 466 | - 'xxx' for the Win32 version when no strings are involved, |
9f69d893 AJ |
467 | - 'xxxA' for the Win32 version with ASCII strings, |
468 | - 'xxxW' for the Win32 version with Unicode strings. | |
1285c2f9 | 469 | |
9f69d893 AJ |
470 | If the function has both ASCII and Unicode version, you should then |
471 | use the macros WINELIB_NAME_AW(xxx) or DECL_WINELIB_TYPE_AW(xxx) | |
0768424b | 472 | (defined in include/windef.h) to define the correct 'xxx' function |
9f69d893 AJ |
473 | or type for Winelib. When compiling Wine itself, 'xxx' is _not_ |
474 | defined, meaning that code inside of Wine must always specify | |
475 | explicitly the ASCII or Unicode version. | |
1285c2f9 | 476 | |
9f69d893 AJ |
477 | If 'xxx' is the same in Win16 and Win32, you can simply use the same |
478 | name as Windows, i.e. just 'xxx'. If 'xxx' is Win16 only, you could | |
479 | use the name as is, but it's preferable to use 'xxx16' to make it | |
480 | clear it is a Win16 function. | |
1285c2f9 AJ |
481 | |
482 | Examples: | |
483 | ||
9f69d893 AJ |
484 | typedef struct { /* Win32 ASCII data structure */ } WNDCLASSA; |
485 | typedef struct { /* Win32 Unicode data structure */ } WNDCLASSW; | |
1285c2f9 AJ |
486 | typedef struct { /* Win16 data structure */ } WNDCLASS16; |
487 | DECL_WINELIB_TYPE_AW(WNDCLASS); | |
488 | ||
489 | ATOM RegisterClass16( WNDCLASS16 * ); | |
9f69d893 AJ |
490 | ATOM RegisterClassA( WNDCLASSA * ); |
491 | ATOM RegisterClassW( WNDCLASSW * ); | |
1285c2f9 AJ |
492 | #define RegisterClass WINELIB_NAME_AW(RegisterClass) |
493 | ||
494 | The Winelib user can then say: | |
495 | ||
1285c2f9 AJ |
496 | WNDCLASS wc = { ... }; |
497 | RegisterClass( &wc ); | |
498 | ||
499 | and this will use the correct declaration depending on the definition | |
9f69d893 | 500 | of the UNICODE symbol. |
1285c2f9 AJ |
501 | |
502 | ||
1285c2f9 AJ |
503 | DEBUG MESSAGES |
504 | ============== | |
aca05783 AJ |
505 | |
506 | To display a message only during debugging, you normally write something | |
507 | like this: | |
508 | ||
d95ce8ce DP |
509 | TRACE("abc..."); or |
510 | FIXME("abc..."); or | |
511 | WARN("abc..."); or | |
512 | ERR("abc..."); | |
54c2711f | 513 | |
7d2aefd8 | 514 | depending on the seriousness of the problem. (documentation/debugging.sgml |
d95ce8ce DP |
515 | explains when it is appropriate to use each of them). You need to declare |
516 | the debug channel name at the top of the file (after the includes) using | |
517 | the WINE_DEFAULT_DEBUG_CHANNEL macro, like so: | |
518 | ||
519 | WINE_DEFAULT_DEBUG_CHANNEL(win); | |
520 | ||
521 | If your debugging code is more complex than just printf, you can use | |
522 | the macros: | |
523 | ||
524 | TRACE_ON(xxx), WARN_ON(xxx), ERR_ON(xxx) and FIXME_ON(xxx) | |
525 | ||
526 | to test if the given channel is enabled. Thus, you can write: | |
527 | ||
528 | if (TRACE_ON(win)) DumpSomeStructure(&str); | |
54c2711f | 529 | |
234bc24d | 530 | Don't worry about the inefficiency of the test. If it is permanently |
54c2711f | 531 | disabled (that is TRACE_ON(win) is 0 at compile time), the compiler will |
234bc24d | 532 | eliminate the dead code. |
aca05783 | 533 | |
54c2711f AJ |
534 | For more info about debugging messages, read: |
535 | ||
7d2aefd8 | 536 | http://www.winehq.org/site/docs/wine-devel/debugging |
54c2711f | 537 | |
23946ad2 AJ |
538 | |
539 | MORE INFO | |
540 | ========= | |
541 | ||
33072e1f | 542 | 1. There is a FREE online version of the MSDN library (including |
344ed41d | 543 | documentation for the Win32 API) on http://msdn.microsoft.com/ |
4ebc8067 | 544 | or http://www.msdn.com/ |
23946ad2 | 545 | |
7be37f4f TW |
546 | 2. Windows apilist: http://www.mentalis.org/apilist/apilist.php |
547 | ||
548 | 3. http://www.sonic.net/~undoc/bookstore.html | |
549 | ||
550 | 4. In 1993 Dr. Dobbs Journal published a column called "Undocumented Corner". | |
64ed084e DP |
551 | |
552 | 5. www.geocities.com/SiliconValley/4942/ |