Copy w32api from trunk
[reactos.git] / reactos / w32api / README.w32api
1 Free headers and libraries for the Win32 API
2
3 Originally written by Anders Norlander
4 Last known and not working email: <anorland@hem2.passagen.se>
5
6 Now maintained by MinGW Developers
7 Send bug reports and questions to MinGW-users@lists.sourceforge.net
8 URL: http://www.mingw.org
9
10 * License 2.0
11
12 You are free to use, modify and copy this package as long as this
13 README.w32api file is included unmodified with any distribution, source or
14 binary, of this package. No restrictions are imposed on any package or
15 product using or incorporating this package. You are free to license your
16 package as you see fit.
17
18 You may not restrict others freedoms as set forth in the above paragraph.
19 You may distribute this library as part of another package or as a
20 modified package if and only if you do *not* restrict others freedoms as
21 set forth in the above paragraph as it concerns this package. You do have
22 the right to restrict uses of any package using this package.
23
24 This package is distributed in the hope that it will be useful, but
25 WITHOUT ANY WARRANTY; without even the implied warranty of
26 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
27
28 * What is it?
29
30 This is a free set of headers and import libraries for the Win32
31 API. The library differs from the GNU Windows32 library in that I
32 have tried to use a file structure that mirrors Microsoft's. I
33 don't like having *all* definitions in one single header as in the
34 GNU Windows32 library, I want a clean separation between different
35 parts of the API.
36
37 Daniel Guerrero Miralles contributed the DirectX 6.1 import
38 libraries and DirectX GUID definitions.
39
40 See the files NOTES and TODO for what needs to be done.
41
42 * Size does matter
43
44 Since the WIN32 API is severely bloated (as most MS products seem to
45 be) the headers are designed to be as compact as possible, while
46 still being readable, in order to minimize parsing time.
47
48 The convention is to omit parameter names for function prototypes,
49 no excessive white space. Struct/union members are indented with tab
50 characters to make them readable. Comment only when necessary.
51
52 If you are contributing a patch please follow the above mentioned
53 convention. Make sure your editor does not convert tabs to spaces.
54
55 * What do I need to use it?
56
57 The library is intended for use with egcs 1.1 or later but it is
58 possible to use with some other tools as well (although it is not
59 very useful). LCC-Win32, MSVC and Borland C++ 5.01 or higher may
60 work as well. The import libraries are for GNU tools only.
61
62 The library requires egcs 1.1 or later, since the `#pragma pack'
63 feature is used. Mumit Khan provides egcs patches and binaries for
64 win32 at `http://www.xraylith.wisc.edu/~khan/software/gnu-win32/'.
65
66 If you are going to use C++ COM objects, you will need a version of
67 egcs that recognizes the `comobject' attribute and then define
68 HAVE_COMOBJECT when compiling your program. Antonio Mendes de
69 Oliveira Neto has a prebuilt version at
70 `http://li.facens.br/EGCS-WIN32/english/index.html'. Note that this
71 is very experimental. If you want to use COM objects in C++ but with
72 C interfaces you must define CINTERFACE.
73
74 Objective-C programs cannot use COM functionality because of
75 conflicts between the interface define and the Objective-C
76 @interface directive. There is also a conflict between the windows
77 Obj-C BOOL types. To avoid this conflict you should use WINBOOL in
78 all places where you would use BOOL in a C/C++ windows program. If
79 you include any windows headers *after* `windows.h' you must use the
80 method outlined below:
81
82 /* non-windows includes */
83 #include <objc/objc.h>
84 ...
85 /* windows specific headers */
86 #include <windows.h>
87 #define BOOL WINBOOL
88 #include <commctrl.h>
89 ...
90 #undef BOOL
91 ...
92 /* include other headers */
93