NDK

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 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.
  • Sometimes, but rarely, you will find Native Types which are actually Win32 types, defined in Windows headers but not in DDK/IFS. In that case, you must add the definition to the special protected block (ex:#ifndef _WINBASE_H) so that it will be skipped by user-mode applications.

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).
  • However, if the function is inside ntdll, you must add it to "umfuncs.h"

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.

• The NDK also includes a file called "umfuncs.h" which exports to User-Mode or Native-Mode Applications undocumented functions which can only be accessed from ntdll.dll.

What is the formatting syntax in the NDK?

Types must be defined as follows:

typedef struct _TYPENAME
{
    PMEMBER_TYPE Member1;
    MEMBER_TYPE1 Member2;
    struct _TYPENAME *SelfMember;
    union
    {
        struct
        {
            UCHAR Member3:4;
            UCHAR Member4:4;
        };
        UCHAR Member5;
    }
    MEMVER_TYPE2 Member6;
} TYPENAME, *PTYPENAME;

Prototypes as follows:

RETURNTYPE
CALLING_CONVENTION
FunctionName(
    PARAM_TYPE Param1,
    PARAM_TYPE Param2
);

Similalry, function types:

typedef RETURNTYPE 
(CALLING_CONVENTION *PFUNCTION_TYPE(
    PARAM_TYPE Param1,
    PARAM_TYPE Param2
);

How do I use the NDK?

• User Mode Application requiring Native Types:

 #include <windows.h>      /* Declare Windows Headers like you normally would */
 #DEFINE NTOS_MODE_USER    /* Tell the NDK that you are User Mode */
 #include <ndk/ntndk.h>    /* Declare the NDK Headers */

• Native Mode Application:

 #DEFINE NTOS_MODE_USER    /* Tell the NDK that you are User Mode */
 #include <ndk/ntndk.h>    /* Declare the NDK Headers */

• Kernel Mode Driver:

 #include <ddk/ntddk.h>    /* Declare DDK Headers like you normally would */
 #include <ndk/ntndk.h>    /* Declare the NDK Headers */