reactos/sdk/include/ndk/readme.txt

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