- Add DDK alignment macros and move/rename the ones in the NDK for user-mode only...
[reactos.git] / reactos / include / ndk / readme.txt
1 Native Development Kit README
2 NDK 1.00
3 -----------------------------
4
5 0. PREABMLE
6
7 0.1 COPYRIGHT
8
9 The NDK is Copyright © 2005 Alex Ionescu.
10
11 0.2 CONTACT INFORMATION
12
13 The author, Alex Ionescu, may be reached through the following means:
14
15 Email: alex.ionescu@reactos.com
16 Mail: 2246, Duvernay. H3J 2Y3. Montreal, QC. CANADA.
17 Phone: (514)581-7156
18
19 1. LICENSE
20
21 1.1 OPEN SOURCE USAGE
22
23 Open Source Projects may choose to use one of either the two following licenses:
24
25 GNU GENERAL PUBLIC LICENSE Version 2, June 1991
26
27 OR
28
29 GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999
30
31 The choice is yours to make based on the license which is most compatible with your
32 software.
33
34 You MUST read GPL.TXT or LGPL.TXT after your decision. Violating your chosen license
35 voids your usage rights of the NDK and will lead to legal action on the part of the
36 author.
37
38 If your Open Source product does not use a license which is compatible with the ones
39 listed above, please contact the author to reach a mutual agreement to find a better
40 solution for your product. Alternatively, you may choose to use the Proprietary Usage
41 license displayed below in section 1.2
42
43 If you are unsure of whether or not your product qualifies as an Open Source product,
44 please contact the Free Software Foundation, or visit their website at www.fsf.org.
45
46
47 1.2 PROPRIETARY USAGE
48
49 Because it may be undesirable or impossible to adapt this software to your commercial
50 and/or proprietary product(s) and/or service(s) using a (L)GPL license, proprietary
51 products are free to use the following license:
52
53 NDK LICENSE Version 1, November 2005
54
55 You MUST read NDK.TXT for the full text of this license. Violating your chosen license
56 voids your usage rights of the NDK, constitutes a copyright violation, and will lead to
57 legal action on the part of the author.
58
59 If you are unsure of have any questions about the NDK License, please contact the
60 author for further clarification.
61
62 2. ORIGINS OF NDK MATERIAL, AND ADDING YOUR OWN
63
64 2.1 CONTRIBUTIONS AND SOURCES
65
66 The NDK could not exist without the various contributions made by a variety of people
67 and sources. The following public sources of information were lawfully used:
68
69 - GNU NTIFS.H, Revision 43
70 - W32API, Version 2.5
71 - Microsoft Driver Development Kit 2003 SP1
72 - Microsoft Driver Development Kit 2000
73 - Microsoft Driver Development Kit NT 4
74 - Microsoft Driver Development Kit WinME
75 - Microsoft Installable File Systems Kit 2003 SP1
76 - Microsoft Windows Debugger (WinDBG) 6.5.0003.7
77 - Microsoft Public Symbolic Data
78 - Microsoft Public Windows Binaries (strings)
79 - OSR Technical Articles
80 - Undocumented windows 2000 Secrets, a Programmer's Cookbook
81 - Windows NT/2000 Native API Reference
82 - Windows NT File System Internals
83 - Windows Internals I - II
84 - Windows Internals 4th Edition
85
86 If the information contained in these sources was copyrighted, the information was not
87 copied, but simply used as a basis for developing a compatible and identical definition.
88 No information protected by a patent or NDA was used. All information was publically
89 located through the Internet or purchased or licensed for lawful use.
90
91 Additionally, the following people contributed to the NDK:
92
93 - Eric Kohl
94 - Filip Navara
95 - Steven Edwards
96
97 2.2 BECOMING A CONTRIBUTOR
98
99 To contribute information to the NDK, simply contact the author with your new structure,
100 definition, enumeration, or prototype. Please make sure that your addition is:
101
102 1) Actually correct!
103 2) Present in Windows NT 5, 5.1, 5.2 and/or 6.0
104 3) Not already accessible through another public header in the DDK, IFS, WDK and/or PSDK.
105 4) From a publically verifiable source. The author needs to be able to search for your
106 addition in a public information location (book, Internet, etc) and locate this definition.
107 5) Not Reversed. Reversing a type is STRONGLY discouraged and a reversed type will more then likely
108 not be accepted, due to the fact that functionality and naming will be entirely guessed, and things
109 like unions are almost impossible to determine. It can also bring up possible legal ramifications
110 depending on your location. However, using a tool to dump the strings inside an executable
111 for the purpose of locating the actual name or definition of a structure (sometimes possible due
112 to ASSERTs or debugging strings) is considered 'fair use' and will be a likely candidate.
113
114 If your addition satsfies these points, then please submit it, and also include whether or not
115 you would like to be credited for it.
116
117 3. USAGE
118
119 3.1 ORGANIZATION
120
121 * The NDK is organized in a main folder (include/ndk) with arch-specific subfolders (ex: include/ndk/i386).
122 * The NDK is structured by NT Subsystem Component (ex: ex, ps, rtl, etc).
123 * The NDK can either be included on-demand (#include <ndk/xxxxx.h>) or globally (#include <ndk/ntndk.h>).
124 The former is recommended to reduce compile time.
125 * The NDK is structured by function and type. Every Subsystem Component has an associated "xxfuncs.h" and
126 "xxtypes.h" header, where "xx" is the Subsystem (ex: iofuncs.h, iotypes.h)
127 * The NDK has a special file called "umtypes.h" which exports to User-Mode or Native-Mode Applications the
128 basic NT types which are present in ntdef.h. This file cannot be included since it would conflict with
129 winnt.h and/or windef.h. Thus, umtypes.h provides the missing types. This file is automatically included
130 in a User-Mode NDK project.
131 * The NDK also includes a file called "umfuncs.h" which exports to User-Mode or Native-Mode Applications
132 undocumented functions which can only be accessed from ntdll.dll.
133 * The NDK has another special file called "ifssupp.h", which exports to Kernel-Mode drivers a few types which
134 are only documented in the IFS kit, and are part of some native definitions. It will be deprecated next year
135 with the release of the WDK.
136
137 3.2 USING IN YOUR PROJECT
138
139 * User Mode Application requiring Native Types:
140
141 #define WIN32_NO_STATUS /* Tell Windows headers you'll use ntstatus.s from NDK */
142 #include <windows.h> /* Declare Windows Headers like you normally would */
143 #include <ntndk.h> /* Declare the NDK Headers */
144
145 * Native Mode Application:
146
147 #include <windows.h> /* Declare Windows Headers for basic types. NEEDED UNTIL NDK 1.5 */
148 #include <ntndk.h> /* Declare the NDK Headers */
149
150 * Kernel Mode Driver:
151
152 #include <ntddk.h> /* Declare DDK Headers like you normally would */
153 #include <ntndk.h> /* Declare the NDK Headers */
154
155 * You may also include only the files you need (example for User-Mode application):
156
157 #define WIN32_NO_STATUS /* Tell Windows headers you'll use ntstatus.s from NDK */
158 #include <windows.h> /* Declare Windows Headers like you normally would */
159 #include <rtlfuncs.h> /* Declare the Rtl* Functions */
160
161 3.3 CAVEATS
162
163 * winternl.h: This header, part of the PSDK, was released by Microsoft as part of one of the governmen
164 lawsuits against it, and documents a certain (minimal) part of the Native API and/or types. Unforunately,
165 Microsoft decided to hack the Native Types and to define them incorrectly, replacing real members by "reserved"
166 ones. As such, you 'cannot include winternl.h in any project that uses the NDK. Note however, that the NDK fully
167 replaces it and retains compatibility with any project that used it.
168 * Native programs: Native programs must include "windows.h" until the next release of the NDK (1.5). The upcoming
169 version will automatically detect the lack of missing types and include them. Note however that you will still need
170 to have the PSDK installed.