Windows native api reference

Windows Boot Program And Native API Kit

Note: All of this information is from 2007 and may long be outdated

A Windows boot program is a piece of software which executes while Windows is booting. Information about how to write such a program is very incomplete. For a university project I collected several pieces of information on this topic I’d like to share.

An example of a boot program is autocheck the tool which checks the hard disk for errors right at the start of Windows — remember this blue screen just before the logon box appears?

To write such a program you can only use the NT Native API. The native api consists of all the functions the kernel «exports» to user mode programs. Windows applications normally use the API of the Win32 subsystem (kernel32.dll, user32.dll, gdi32.dll. ) which itself uses the native API to speak to the kernel. At the time a boot program is executing no subsystem is available so one has to fall back to the Native API.

How to build the sample boot program (worked in 2007. )

• Clone the latest sources
• Install the Windows DDK
• Start the Windows DDK Command Line Environment
• cd to the sources
• use build-interactive.bat or simply build -wg to build the boot program

More Information & Links

• Sysinternals’ Inside Native Applications
• Gary Nebbett’s Windows NT/2000 Native API Reference (affiliate link)
• Sven Schreiber’s Undocumented Windows 2000 Secrets, w. CD-ROM: A Programmer’s Cookbook (affiliate link) or the PDF Version
• NTInternals’ [Undocumented NT Functions for Microsoft Windows NT/2000] (http://undocumented.ntinternals.net/)
• Microsoft Windows Internals Windows® Internals, Fifth Edition (PRO-Developer) (affiliate link)
• A thread on OSR’s forum
• Syscall Table and comparison of different Windows versions
• Petter Nordahl’s site about the Offline Nt Password & Registry Editor with some interesting information regarding the structure of the SAM
• Bruce Ediger’s comment about Windows NT, Secret APIs and the Consequences
• Native shell — a command prompt for native mode

Windows Native API

Windows has many ways to access system functions. The normal programmer would just use the methods exported by the dynamic link libraries kernel32.dll, user32.dll and others. They belong to a user-mode API called Win32. Windows was designed to have many of those user-mode APIs called »’Subsystems»’. There were or are Win32, POSIX and Os/2 subsystems. Every subsystem is an API and a runtime environment an application can use to access the system functions of the OS.

But how do these subsystems access the kernel?

The answer is: through ntdll. Ntdll is a native dynamic link library providing direct links to kernel mode functions. A program which only uses this API is called a native program and a flag in the executable header marks that fact (see the MS linker’s /SUBSYSTEM parameter). The subsystems themselves are native programs, of course.

Boot programs and the native API

Boot programs always have to use the native API and link against ntdll. That is because of the fact that other subsystems are just not available at the time a boot program gets executed. A corrollar: boot programs can’t use the normal runtime library because it references Win32 APIs for various tasks. Therefore ntdll.dll exports several common runtime functions boot programs and other native programs can use.

The registry at boot-time

At the time a boot program is executed the registry is not yet initialized. Machine/system and machine/hardware are loaded because they need to be loaded for Windows to find the drivers. The SAM at machine\SAM and the machine\software are not yet loaded. If you have to read values from this keys you have to plug the keys into the registry ( NtLoadKey ) from the corresponding file. Don’t forget to unload the keys ( NtUnloadKey ) afterwards because Windows fails with a bluescreen afterwards if it finds hives mapped when it does not expect them to be.

Writing to Registry at boot-time

Writing to Registry is even more difficult: The Registry is read-only at boot-time. The causes for this are not known to me but I guess it’s because of security issues and they wanted to stop some faulty driver to wreak havoc in the registry even before Windows has booted.

There is a variable in the Windows Configuration Manager which controls if the Registry can be flushed to disk. It is called CmpNoWrite . You may use the kernel debugger to lookup the value.

So the registry is not writeable at boot-time.

What are the solutions for this problem?

• Unset the flag using the Kernel Debugger. This works but this is not a very automatic solution. It is not portable as well since CmpNoWrite is at another position in the kernel everytime the kernel is built.
• Unset the flag in the boot program from user-mode using a hack. (see function showNoWrite ). The same issues regarding portability apply.
• Use NtInitializeRegistry to initialize the registry like smss.exe would do it after executing the boot program. That call loads the software and SAM hives and marks the Registry as writable. You don’t even have to flush the registry to disk since the changes are persistent nevertheless after booting. That is because the registry can only be initialized once. If you call NtInitializeRegistry , the regular call from smss.exe will fail but Windows will start anyway. It is unclear if that works all the time, during our testing it seemed to work always. A side note: I found this fact about how to make the registry writable in a usenet post from 1997 but it still works.

C++ exceptions in native programs

This native api program/library uses C++-features like classes in many places. This seems to work without problems so far. It would be appropriate to use C++ exceptions as well. This will not work, however. At least not without some serious effort. C++ exceptions are working through subtle mechanisms of Windows, the C++ compiler and the runtime library all together.

To use exception handling one has to enable the specific options in the compiler. You can use this lines in your SOURCES to enable it:

If we don’t link a runtime library linking will error with unresolved externals like __CxxFrameHandler and others.

Since we cannot use Win32 dlls in a native program we cannot link against the standard runtime library (msvcrt). So the right choice seems to be the use of the staticly linkable runtime library libc. This does not work either. Even libc contains uncountable references to functions defined in kernel32 and user32. We cannot link to them, of course.

So your choices are:

• reimplement C++ exception handling on top of the native (API) features provided by Windows and the compiler
• use structured exception handling as documented by Microsoft, this will not work in functions relying on automatic object deconstruction
• don’t use exceptions at all (that was my choice)

Get started with desktop Windows apps that use the Win32 API

The Win32 API (also called the Windows API) is the original platform for native C/C++ Windows applications that require direct access to Windows and hardware. It provides a first-class development experience without depending on a managed runtime environment like .NET and WinRT (for UWP apps for Windows 10). This makes the Win32 API the platform of choice for applications that need the highest level of performance and direct access to system hardware.

This documentation covers how to create desktop Windows apps with the Win32 API. The Win32 API is one of several app platforms you can use to build desktop Windows apps. For more info about other app platforms, see Choose your platform.

Get set up

Follow these instructions and start creating desktop apps for Windows 10 that use the Win32 API.

Download or update Visual Studio 2019. If you don’t already have Visual Studio 2019, you can install the free Microsoft Visual Studio Community 2019. When you install Visual Studio, make sure to select the Desktop development with C++ option. For download links, see our Downloads page.

When you install Visual Studio, you can optionally select the .NET desktop development and Universal Windows Platform development options for access to other project types and app platforms for building desktop Windows apps.

If you want to build your desktop app into an MSIX package and test or debug the packaged app on your development computer, you’ll need to enable Developer Mode on your computer.

For scripts you can use to set up your development computer and install other features or packages, check out this GitHub project.

Learn how to create desktop apps using the Win32 API

If you’re new to building desktop apps using the Win32 API, the following tutorials and articles will help get you started.

Topic	Description
Create your first C++ Win32 app	This tutorial teaches you how to write a Windows program in C++ using Win32 and COM APIs.
Create your first app using DirectX	This basic tutorial will get you started with DirectX app development.
Programming Guide for 64-bit Windows	Describes programming for 64-bit versions of the Windows operating system.
Using the Windows Headers	Provides an overview of some of the conventions used in the Windows header files.

You can also browse the desktop app samples.

Modernize your desktop apps for Windows 10

If you have an existing desktop Win32 app, there are many features in the Universal Windows Platform (UWP) that you can use to deliver the best possible experience on Windows 10. For example, starting in Windows 10, version 1903, you can host UWP XAML controls in your desktop Win32 app using a feature called XAML Islands.

Most of these UWP features are available as modular components that you can adopt in your desktop app at your own pace without having to rewrite your entire application. You can enhance your existing desktop app by choosing which parts of Windows 10 and UWP to adopt.

C++/WinRT

Optionally, you can configure your development computer to use C++/WinRT. C++/WinRT is an entirely standard modern C++17 language projection enables you to easily consume Windows Runtime APIs Windows Runtime (WinRT) APIs from your C++ Win32 desktop application. C++/WinRT is implemented as a header-file-based library.

To configure your project for C++/WinRT:

• For new projects, you can install the C++/WinRT Visual Studio Extension (VSIX) and use one of the C++/WinRT project templates included in that extension.
• For existing Windows desktop application projects, you can install the Microsoft.Windows.CppWinRT NuGet package in the project.

For more details about these options, see this article.

What’s new for Win32 APIs in Windows 10

To learn about new Win32 APIs that have been introduced in Windows 10, see what’s new.

Get started with Win32 features and technologies

Win32 APIs exist for many features and technologies in Windows 10, including core user interface and windowing APIs, audio and graphics, and networking. For guidance and code samples about using these APIs, see our features and technologies index.

Справочные материалы по API машинного обучения Windows Windows Machine Learning API reference

API-интерфейсы WinML разделены на три типа, которые описаны ниже. The WinML APIs are divided roughly into three areas, which are listed below.

Имя Name	Описание Description
Основные интерфейсы API Core APIs	Основные API-интерфейсы WinML, используемые для загрузки, привязки и оценки моделей. The main WinML APIs that are used to load, bind, and evaluate models. Размещены в пространстве имен Windows.AI.MachineLearning. Located in the Windows.AI.MachineLearning namespace.
Пользовательские операторы Custom operators	API-интерфейсы, обрабатывающие пользовательские операторы в WinML. APIs that handle custom operators in WinML. Размещены в MLOperatorAuthor.h. Located in MLOperatorAuthor.h.
Собственные API-интерфейсы Native APIs	Собственные API-интерфейсы WinML, которые позволяют взаимодействовать с Direct3D. Native WinML APIs that let you interact with Direct3D. Размещены в windows.ai.machinelearning.native.h. Located in windows.ai.machinelearning.native.h.

Используйте следующие ресурсы для получения справки по машинному обучению в Windows: Use the following resources for help with Windows ML:

• Чтобы задать технические вопросы о машинном обучении в Windows или ответить на них, используйте тег windows-machine-learning в Stack Overflow. To ask or answer technical questions about Windows ML, please use the windows-machine-learning tag on Stack Overflow.
• Сообщить об ошибке можно в нашем репозитории GitHub. To report a bug, please file an issue on our GitHub.
• Чтобы отправить запрос на добавление функции, перейдите на сайт Windows Developer Feedback. To request a feature, please head over to Windows Developer Feedback.

Windows Native API: When and why use Zw vs Nt prefixed api calls?

In Native API Microsoft exports two versions of each api call, one prefixed with Zw and one with Nt, for eg. ZwCreateThread and NtCreateThread.

My question is what is the difference between those two versions of the calls and when and why one should use Zw or Nt exclusively? To my understanding Zw version ensures that the caller resides in kernel mode, whereas Nt doesn’t.

I am also wondering about the specific meaning for Zw and Nt prefixes/abbreviations? One can guess Nt probably refers to NT(New Technology) Windows family or Native(probably not)? As for Zw, does it stand for something?

2 Answers 2

Update:

Aside from Larry Osterman’s answer (which you should definitely read), there’s another thing I should mention:

Since the NtXxx variants perform checks as though the call is coming from user-mode, this means that any buffers passed to the NtXxs function must reside in user-mode address spaces, not kernel-mode. So if you call a function like NtCreateFile in your driver and pass it pointers to kernel-mode buffers, you will get back a STATUS_ACCESS_VIOLATION because of this.

A kernel-mode driver calls the Zw version of a native system services routine to inform the routine that the parameters come from a trusted, kernel-mode source. In this case, the routine assumes that it can safely use the parameters without first validating them. However, if the parameters might be from either a user-mode source or a kernel-mode source, the driver instead calls the Nt version of the routine, which determines, based on the history of the calling thread, whether the parameters originated in user mode or kernel mode.

Native system services routines make additional assumptions about the parameters that they receive. If a routine receives a pointer to a buffer that was allocated by a kernel-mode driver, the routine assumes that the buffer was allocated in system memory, not in user-mode memory. If the routine receives a handle that was opened by a user-mode application, the routine looks for the handle in the user-mode handle table, not in the kernel-mode handle table.

Also, Zw doesn’t stand for anything. See What Does the Zw Prefix Mean?:

The Windows native system services routines have names that begin with the prefixes Nt and Zw. The Nt prefix is an abbreviation of Windows NT, but the Zw prefix has no meaning. Zw was selected partly to avoid potential naming conflicts with other APIs, and partly to avoid using any potentially useful two-letter prefixes that might be needed in the future.