Section 1: API Layers Overview

The Big Picture: Ordering Food at a Restaurant

When you eat at a restaurant, you do not walk into the kitchen and cook. You tell the waiter what you want. The waiter writes an order slip in a fixed format. The slip goes to the kitchen window, where a cook reads it. The cook uses the stoves and fridges to make your meal. The plate then travels back to your table the same way.

A program on Windows works like the customer. It wants to open a file, draw a window or ask for memory. It is not allowed to touch the disk, the screen or the memory chips directly. It must ask Windows to do the work. The way it asks is called an API.

CUSTOMER          WAITER            KITCHEN WINDOW      COOK + STOVES
(your program) -> (Win32 API)  ->   (Native API)   ->   (the kernel)
 "a burger,        writes the       passes the slip     makes the food
  please"          order slip       through the wall    and sends it back

This chapter follows one request from the program all the way down and back up. Chapter 22 explained DLLs, the files that hold this code. This chapter explains which functions live in them and how they call each other.

1.1 What an API Is

What it is: An API (Application Programming Interface) is a menu of functions that one piece of software offers to another. Each function has a name, a list of inputs and a result. The caller does not need to know how the function works inside. It only needs to know the name, the inputs and the promise.

Think of a vending machine. You press B4 and money goes in. A snack comes out. You never open the machine to see the springs.

A Windows API is simply the set of functions Windows offers to programs. Windows has thousands of them. They cover files, memory, windows on screen, networking, security and more.

Why not just let programs touch the hardware? If every program could write to the disk or screen directly, one buggy program could wipe another program's data or crash the PC. The API is the only door, and Windows stands at that door and checks every request.

1.2 The Layer Stack, Top to Bottom

What it is: Windows does not have one API. It has layers. Each layer calls the layer below it. The one at the top is the nearest to your program. The one at the bottom is the nearest to the hardware.

┌────────────────────────────────────────────────────────┐
│  1. YOUR APPLICATION                                   │
│     C/C++ runtime, .NET, Python, Java, browser ...     │
├────────────────────────────────────────────────────────┤
│  2. WIN32 API  (documented)                            │
│     kernel32 / kernelbase, user32, gdi32, advapi32     │
├────────────────────────────────────────────────────────┤
│  3. NATIVE API  (little documented)                    │
│     ntdll.dll: NtCreateFile, NtAllocateVirtualMemory   │
├────────────────────────────────────────────────────────┤
│  4. SYSTEM CALL INSTRUCTION  ("syscall" on x64)        │
└────────────────────────────────────────────────────────┘
══════════ BORDER: user mode (ring 3) above, kernel mode (ring 0) below ══════════
┌────────────────────────────────────────────────────────┐
│  5. KERNEL  (ntoskrnl.exe)                             │
│     system service dispatch, then Executive managers   │
├────────────────────────────────────────────────────────┤
│  6. DRIVERS  (file system, disk, graphics, network)    │
├────────────────────────────────────────────────────────┤
│  7. HARDWARE  (SSD, GPU, network card)                 │
└────────────────────────────────────────────────────────┘

The double line is the most important line in this chapter. Above it, code runs in user mode and is closely limited. Below it, code runs in kernel mode and can do almost anything. The only way across is the system call, which is the topic of Section 4.

1.3 What Each Layer Does

What a "runtime" is: a runtime is a ready-made library that comes with a programming language. When a C program calls fopen, the C runtime (a helper library) turns it into the Windows call CreateFileW. So your favourite language is already one layer above Win32.

Python:   open("notes.txt")
            │ (Python's own code, written in C)
            ▼
C runtime:  _wfopen / fopen
            │
            ▼
Win32:      CreateFileW

1.4 The Border: User Mode and Kernel Mode

What it is: The CPU can run in different privilege levels, sometimes called rings (see Chapter 2). Windows uses just two of them:

Chapter 7 explains the reasons in detail. The short version is protection. A crash in a program in ring 3 closes that program. A crash in ring 0 can take down the whole PC (the Blue Screen).

Every layer in the top half of the stack (application, Win32, Native API) is ordinary user-mode code. Even ntdll.dll, which sounds deep inside Windows, is just a DLL loaded into your program's memory. Look at Task Manager's Details tab, or run this in PowerShell:

Get-Process -Id $PID | Select-Object -ExpandProperty Modules | Where-Object ModuleName -like "ntdll*"

You will see ntdll.dll inside your PowerShell process. That proves it lives in user mode.

1.5 Where the DLLs Fit

What it is: Each user-mode layer in the stack is a DLL (Chapter 22). That is how Windows shares one copy of the code with every program.

You can list some of them for any running program:

tasklist /m kernel32.dll

This lists processes that have kernel32.dll loaded. Nearly every program is on the list. (The exact output depends on your PC.)

Where they live: C:\Windows\System32. Check yourself:

dir C:\Windows\System32\ntdll.dll

A twist for 32-bit programs. A 64-bit Windows can also run old 32-bit programs. Those use a separate set of DLL files in C:\Windows\SysWOW64. The idea of the layers is the same.

1.6 Why Windows Uses Layers

What it is: Layers are a design choice. Each one hides the mess below it. This gives Windows four big benefits.

1. Safety. Programs can only reach the kernel through a narrow, guarded door.
2. Compatibility. The top layer (Win32) stays steady for decades, while the layers underneath change. A program from many years ago can still run on Windows 11, because Microsoft keeps the Win32 promise even when the inside is rebuilt.
3. Simplicity for programmers. A programmer calls one friendly function instead of writing dozens of low-level steps.
4. Many languages, one system. C, C#, Python, Rust and Java all end up calling the same Win32 functions.

 C++ ─────┐
 C# ──────┤
 Python ──┼──►  Win32 API  ──►  Native API  ──►  Kernel
 Rust ────┤
 Java ────┘

The price of layers is a tiny bit of extra work for each call. Computers do this so fast that, for ordinary programs, you will never notice.

1.7 Following One Request Down the Layers

Here is a plain-English trace of a program saving a note. Section 5 gives the full, exact version.

You will recognise handles from Chapter 9. The program never gets the "real" file. It gets a ticket that Windows understands.

Summary