From ReactOS Wiki
Revision as of 18:03, 8 May 2005 by Alex Ionescu (talk | contribs) (How is the NDK organized?)
Jump to: navigation, search

Native Development Kit Guidelines

This document serves as a brief introduction to the NDK, what should go in it, what shouldn't, and how the information is organized at the file level, as well as how the syntax and formatting is done at the source level.

What is the NDK?

The NDK, or Native Development Kit, is the brainchild of Alex Ionescu, allowing Windows and ReactOS developers alike to have access to a wealth of undocumented kernel and native structures and function prototypes.

Without the NDK, Windows developers are forced to define their own "undoct.h" headers in which they copy/paste information found online, which may or may not be valid and updated. For native types, this is even harder, as sometimes the information is present in the DDK or IFS, but cannot be used in a user-mode application, nor can it be copy-pasted. The developer must re-write all the definitions he needs.

Without the NDK, ReactOS developers are forced to use a system of up to 3 kinds of duplicated headers (sometimes four) containing identical, similar, or worse, different information. Differences between these headers create compile-time problems, and fixing one header set without updating the other usually causes brekage in applications compiled with "W32API" headers versus applications compiled with "ddk" headers vesus applications compiled with "ntos" headers.

The NDK provides a unified header set for development of:

  • User mode applications which use native functions (include windows.h and the user-mode NDK)
  • Native applications (include the user-mode NDK)
  • Kernel-mode drivers which use undocumented kernel functions (include ddk and/or ifs and kernel-mode NDK)

What goes in the NDK?

Because the NDK is a triple-mode header set, care must be taken to avoid collisions. The following information should go in the NDK:

  • Kernel-Mode API Function Prototypes or Types which are undocumented in the DDK or IFS. Sorry, but if the information is documented in the IFS but not the DDK, you must include the IFS in your program (thankfully we provide free IFS Headers). For Types which vary according to version information, always include the most recent version. If older versions are needed, use a compile-time macro to read the build environment (target version) and choose the correct structure.
  • Native (RTL, DBG, PFX, NT/ZW) API Function Prototypes or Types which are undocumented in the DDK, IFS or Windows Headers.
    • If the API Prototype is documented in the DDK or IFS, add the definition to the special protected block (ex: #ifndef _NTDDK_H) so that it will be skipped by drivers.
      • However, if the Type is documented in the DDK or IFS, you must add the definition to umtypes.h. This special header allows the shared parts of the NDK to be used from User-Mode applications and defines things like UNICODE_STRING, the various NTSTATUS codes, IRP codes, and all other Native Types which are not in the DDK or IFS.

What should not go in the NDK?

  • Do not add documented information in the NDK unless it must be accessible from user-mode (which cannot include DDK or IFS), see above guidelines.
  • Do not add Native ReactOS Specific information anywhere else then rosfuncs.h. This header is not publically distributed and will probably be deprecated. It contains Native Types publically documented inside NT but which defer in ReactOS.
  • Do not add Private ReactOS function or types.
  • Do not add User-Mode undocumented functions (like shell32, etc).

How is the NDK organized?

  • The NDK is organized in a main folder (include/ndk) with arch-specific subfolders (ex: include/ndk/i386).
  • The NDK is structured by NT Subsystem Component (ex: ex, ps, rtl, etc).
  • The NDK can either be included on-demand (#include <ndk/xxxxx.h>) or globally (#include <ndk/ntndk.h>). The latter is recommended.
  • The NDK is structured by function and type. Every Subsystem Component has an associated "xxfuncs.h" and "xxtypes.h" header, where "xx" is the Subsystem (ex: iofuncs.h, iotypes.h)
  • The NDK has a special file called "umtypes.h" which exports to User-Mode or Native-Mode Applications the documented types in the DDK and/or IFS which are not normally exposed to them.

What is the formatting syntax in the NDK?

Todo. (There's a proposal at Coding_Style and a corresponding discussion Talk:Coding_Style

How do I use the NDK?