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.