69:T419,Every application running on Windows—from the simplest calculator to the most complex enterprise software—communicates with the operating system through a unified interface known as the **Windows API**. Originally called Win32 when introduced with Windows NT and later extended to Win64 for 64-bit systems, this API represents one of the most extensive and influential programming interfaces in computing history. Understanding the Windows API is fundamental for any systems programmer working on the Windows platform. Unlike higher-level frameworks that abstract away operating system details, the Windows API exposes the raw capabilities of the operating system, providing direct access to process management, memory allocation, file operations, window management, and hundreds of other system services. This page provides a comprehensive exploration of the Win32/Win64 API—its historical evolution, architectural foundations, programming model, and its role as the fundamental bridge between user-mode applications and the Windows kernel.6a:T4ca,**The Windows API Subsystem:** Windows is designed as a subsystem architecture where the Windows API is just one of potentially many environment subsystems. The Windows subsystem (csrss.exe - Client/Server Runtime Subsystem) manages Windows applications, handling: - Console window management - Process and thread creation notifications - Shutdown coordination - Hard error handling Historically, Windows NT supported multiple subsystems including POSIX (later replaced by Windows Subsystem for Linux) and OS/2. The Windows subsystem has always been the primary environment, with the others implemented as thin layers over the core Native API. **Kernel32 and KernelBase:** In Windows 7 and later, Microsoft refactored kernel32.dll to split functionality between kernel32.dll and kernelbase.dll. Many functions that appear to be in kernel32.dll are actually forwarded to kernelbase.dll: ``` kernel32.dll!CreateFileW → kernelbase.dll!CreateFileW ``` This refactoring supports MinWin, Microsoft's effort to create a minimal Windows core for embedded and IoT scenarios. Applications shouldn't need to care about this split—they continue linking against kernel32.lib, and the loader resolves the correct implementations.6b:T61c,// Fixed-size types typedef unsigned char BYTE; // 8-bit unsigned typedef unsigned short WORD; // 16-bit unsigned typedef unsigned long DWORD; // 32-bit unsigned typedef unsigned __int64 QWORD; // 64-bit unsigned // Platform-dependent types (size varies with 32/64-bit) typedef __int3264 INT_PTR; // Signed pointer-sized typedef unsigned __int3264 UINT_PTR; // Unsigned pointer-sized typedef __int3264 LONG_PTR; // Signed pointer-sized (long) typedef unsigned __int3264 ULONG_PTR; // Unsigned pointer-sized typedef ULONG_PTR SIZE_T; // Size type (like size_t) typedef LONG_PTR SSIZE_T; // Signed size type // Boolean type typedef int BOOL; // TRUE or FALSE #define TRUE 1 #define FALSE 0 // Handle types (all are pointer-sized, but opaque) typedef void* HANDLE; typedef HANDLE HFILE; typedef HANDLE HMODULE; typedef HANDLE HINSTANCE; typedef HANDLE HWND; typedef HANDLE HDC; // String types typedef char* LPSTR; // Mutable ANSI string typedef const char* LPCSTR; // Immutable ANSI string typedef wchar_t* LPWSTR; // Mutable Unicode string typedef const wchar_t* LPCWSTR; // Immutable Unicode string // Generic text macros (resolve based on UNICODE define) #ifdef UNICODE typedef LPWSTR LPTSTR; typedef LPCWSTR LPCTSTR; #else typedef LPSTR LPTSTR; typedef LPCSTR LPCTSTR; #endif6c:T6e4,#include #include void DemonstrateErrorHandling() { // Attempt to open a file that doesn't exist HANDLE hFile = CreateFileW( L"C: onexistent\\file.txt", GENERIC_READ, 0, NULL, OPEN_EXISTING, // Fail if file doesn't exist FILE_ATTRIBUTE_NORMAL, NULL ); // Check for failure - INVALID_HANDLE_VALUE for file operations if (hFile == INVALID_HANDLE_VALUE) { // Get the error code - MUST be called immediately after failure DWORD error = GetLastError(); // ERROR_FILE_NOT_FOUND (2) or ERROR_PATH_NOT_FOUND (3) switch (error) { case ERROR_FILE_NOT_FOUND: printf("Error: File not found "); break; case ERROR_PATH_NOT_FOUND: printf("Error: Path not found "); break; case ERROR_ACCESS_DENIED: printf("Error: Access denied "); break; default: printf("Error: Unknown error %lu ", error); } // Get a human-readable error message LPWSTR messageBuffer = NULL; FormatMessageW( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, error, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPWSTR)&messageBuffer, 0, NULL ); if (messageBuffer) { wprintf(L"System message: %s ", messageBuffer); LocalFree(messageBuffer); } return; } // Success - remember to close the handle CloseHandle(hFile); }6d:T6ad,// Pattern 1: HANDLE-returning functions HANDLE hFile = CreateFile(...); if (hFile == INVALID_HANDLE_VALUE) { // Note: NOT checking for NULL! DWORD error = GetLastError(); // Handle error... } HANDLE hMutex = CreateMutex(...); if (hMutex == NULL) { // Mutex returns NULL on failure DWORD error = GetLastError(); // Handle error... } // Pattern 2: BOOL-returning functions BOOL success = ReadFile(hFile, buffer, bufferSize, &bytesRead, NULL); if (!success) { DWORD error = GetLastError(); // Handle error... } // Pattern 3: HRESULT-returning functions (COM-style) HRESULT hr = CoInitializeEx(NULL, COINIT_MULTITHREADED); if (FAILED(hr)) { // Use FAILED() macro, not direct comparison // HRESULT contains error info - no GetLastError() needed // Use HRESULT_CODE() to extract error code } // Pattern 4: Memory allocation LPVOID pMemory = VirtualAlloc(NULL, size, MEM_COMMIT | MEM_RESERVE, PAGE_READWRITE); if (pMemory == NULL) { DWORD error = GetLastError(); // Handle OOM or allocation failure... } // Wrapper function for consistent error handling typedef struct { BOOL success; DWORD errorCode; WCHAR errorMessage[256]; } WinApiResult; WinApiResult WrapApiCall(BOOL apiResult) { WinApiResult result = {0}; result.success = apiResult; if (!apiResult) { result.errorCode = GetLastError(); FormatMessageW( FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, result.errorCode, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), result.errorMessage, ARRAYSIZE(result.errorMessage), NULL ); } return result; }6e:T58b,// Basic Windows application setup // The order of definitions matters! // Target Windows version (Windows 10, version 1903+) #define WINVER 0x0A00 #define _WIN32_WINNT 0x0A00 // Use Unicode (always recommended) #define UNICODE #define _UNICODE // Exclude rarely-used components for faster compilation #define WIN32_LEAN_AND_MEAN // Exclude MFC, OLE, and RPC #define NOMINMAX // Don't define min/max macros (conflict with C++ std) #define STRICT // Enable strict type checking #include // windows.h pulls in many sub-headers: // - windef.h - Basic type definitions (DWORD, WORD, BOOL, etc.) // - winbase.h - Kernel32 function declarations // - winuser.h - User32 function declarations // - wingdi.h - GDI function declarations // - winnt.h - NT-specific types and constants // - winerror.h - Error code definitions // Additional headers for specific functionality (not included by default): #include // Shell functions (ShellExecute, etc.) #include // Shell object interfaces #include // Tool help (process/thread enumeration) #include // Process status API #include // Networking (MUST be before windows.h!) #include // Modern socket functions #include // Debug help library #include // Some (few) internal functions6f:Tca0,/* * Windows API Example: File Processor * Demonstrates proper Win32 patterns for file I/O */ #define WINVER 0x0A00 #define _WIN32_WINNT 0x0A00 #define UNICODE #define _UNICODE #define WIN32_LEAN_AND_MEAN #define STRICT #include #include #include // Safe string functions // Helper: Print detailed error message void PrintError(LPCWSTR context) { DWORD error = GetLastError(); LPWSTR message = NULL; FormatMessageW( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, error, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPWSTR)&message, 0, NULL ); fwprintf(stderr, L"Error in %s: %s (code: %lu) ", context, message ? message : L"Unknown", error); if (message) LocalFree(message); } // Process a file: read content in chunks BOOL ProcessFile(LPCWSTR filePath, PDWORD pBytesProcessed) { HANDLE hFile = INVALID_HANDLE_VALUE; BYTE* buffer = NULL; BOOL result = FALSE; DWORD totalBytesRead = 0; const DWORD BUFFER_SIZE = 64 * 1024; // 64KB chunks // Validate parameters if (!filePath || !pBytesProcessed) { SetLastError(ERROR_INVALID_PARAMETER); return FALSE; } *pBytesProcessed = 0; // Open file for reading with optimal flags hFile = CreateFileW( filePath, GENERIC_READ, FILE_SHARE_READ, // Allow other readers NULL, // Default security OPEN_EXISTING, // File must exist FILE_FLAG_SEQUENTIAL_SCAN, // Hint for read-ahead NULL // No template ); if (hFile == INVALID_HANDLE_VALUE) { PrintError(L"CreateFile"); goto cleanup; } // Allocate read buffer buffer = (BYTE*)HeapAlloc( GetProcessHeap(), 0, // No special flags BUFFER_SIZE ); if (!buffer) { SetLastError(ERROR_NOT_ENOUGH_MEMORY); PrintError(L"HeapAlloc"); goto cleanup; } // Read file in chunks DWORD bytesRead; while (TRUE) { if (!ReadFile(hFile, buffer, BUFFER_SIZE, &bytesRead, NULL)) { PrintError(L"ReadFile"); goto cleanup; } if (bytesRead == 0) { // End of file break; } totalBytesRead += bytesRead; // Process the chunk here... // (In real code, you'd do something with the data) } *pBytesProcessed = totalBytesRead; result = TRUE; cleanup: // ALWAYS clean up resources if (buffer) { HeapFree(GetProcessHeap(), 0, buffer); } if (hFile != INVALID_HANDLE_VALUE) { CloseHandle(hFile); } return result; } int wmain(int argc, wchar_t* argv[]) { if (argc != 2) { wprintf(L"Usage: %s ", argv[0]); return 1; } DWORD bytesProcessed; if (ProcessFile(argv[1], &bytesProcessed)) { wprintf(L"Successfully processed %lu bytes ", bytesProcessed); return 0; } return 1; }62:{"json":{"id":"seed_1b9c793ff7d0cdd1fef68a100ba7476e","slug":"windows-api","category":"Operating Systems","topic":"Windows API","title":"Windows API","description":"Master the Windows Application Programming Interface (Win32/Win64), understanding how applications interact with the Windows operating system through handles, system calls, registry operations, and comparing the Windows approach with POSIX standards.","difficulty":"INTERMEDIATE","estimatedMinutes":90,"pages":[{"id":"seed_9a15aa27153496f5a007607123a9a889","title":"Win32/Win64 API","order":0,"content":[{"id":"opening-hook","title":"The Windows Application Programming Interface","content":[{"data":{"content":"$69"},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"By the end of this page, you will understand the architecture and design philosophy of the Windows API, how it evolved from 16-bit Windows to modern 64-bit systems, the programming model it employs, and how it serves as the foundation upon which all Windows application development is built.","variant":"info"},"type":"callout"}]},{"id":"historical-evolution","title":"Historical Evolution of the Windows API","content":[{"data":{"content":"To truly understand the Windows API, we must trace its evolution from the earliest days of Windows through to the modern Win64 implementation. This history explains many of the API's design decisions, naming conventions, and architectural patterns that might otherwise seem arbitrary.\n\n**The Era of Win16 (1985-1995):**\n\nThe original Windows API, retroactively called Win16, was introduced with Windows 1.0 in 1985. This 16-bit API was designed for Intel 8086/8088 processors with severely limited memory and no hardware memory protection. Key characteristics included:\n\n- **Segmented memory model**: Memory was divided into 64KB segments, requiring near and far pointers\n- **Cooperative multitasking**: Applications had to explicitly yield control to other programs\n- **No memory protection**: A misbehaving application could crash the entire system\n- **Limited address space**: Total addressable memory was typically 1MB or less"},"type":"text"},{"data":{"icon":"Info","title":"The Legacy of Win16","content":"Many conventions from Win16 persist in modern Windows API, including the prefixes like 'lp' (long pointer) and 'h' (handle), Hungarian notation for variable names, and certain function naming patterns. Understanding this history helps explain why the API looks the way it does today.","variant":"note"},"type":"callout"},{"data":{"content":"**The Revolution of Win32 (1993-2003):**\n\nWith Windows NT 3.1 in 1993 and Windows 95 in 1995, Microsoft introduced the Win32 API—a fundamental reimagining of how applications interact with Windows. This 32-bit API brought transformative changes:\n\n- **Flat memory model**: A unified 4GB address space replaced the segmented model\n- **Preemptive multitasking**: The OS could interrupt processes, ensuring fair CPU allocation\n- **Memory protection**: Each process received its own protected address space\n- **True multithreading**: First-class support for concurrent execution within processes\n- **Unicode support**: Native 16-bit Unicode character handling\n\nWin32 was designed with portability in mind. While initially targeting x86 processors, the API was implemented on MIPS, Alpha, and PowerPC architectures (though these ports were eventually discontinued)."},"type":"text"},{"data":{"rows":[["Pointer size","16-bit (near) / 32-bit (far)","32-bit","64-bit"],["Address space","1MB (with segments)","4GB per process","16TB+ per process"],["Memory model","Segmented","Flat","Flat"],["Multitasking","Cooperative","Preemptive","Preemptive"],["Memory protection","None","Full","Full + modern mitigations"],["Thread support","Minimal","Full","Full + advanced features"],["Unicode","Limited","Native (W functions)","Native (W functions)"]],"caption":"Evolution of Windows API Capabilities","headers":["Feature","Win16","Win32","Win64"]},"type":"table"},{"data":{"content":"**The Transition to Win64 (2003-Present):**\n\nAs 64-bit processors became mainstream, Microsoft extended the Windows API to support 64-bit addressing while maintaining exceptional backward compatibility. Win64 was introduced with Windows XP Professional x64 Edition and Windows Server 2003 x64.\n\nThe key principle behind Win64 was **source compatibility**: applications written for Win32 could be recompiled for Win64 with minimal or no source code changes, provided they followed best practices. This was achieved through:\n\n- **Polymorphic types**: Types like `SIZE_T`, `LONG_PTR`, and `UINT_PTR` automatically adjust size based on platform\n- **Windows-on-Windows 64-bit (WoW64)**: A compatibility layer allowing 32-bit applications to run on 64-bit Windows\n- **Consistent API surface**: The same function names and semantics, with appropriate size adjustments"},"type":"text"},{"data":{"icon":"Lightbulb","title":"Modern Windows API Development","content":"Today, when developers refer to the 'Windows API,' they typically mean the combined Win32/Win64 interface. Modern best practice is to use polymorphic types and write code that compiles correctly for both 32-bit and 64-bit targets. The Windows SDK provides header files that automatically select appropriate types based on the compilation target.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":1},{"id":"architectural-overview","title":"Architectural Overview","content":[{"data":{"content":"The Windows API is not a monolithic entity but rather a carefully structured collection of libraries, each providing access to different aspects of the operating system. Understanding this architecture is essential for effective Windows programming.\n\n**The Three-Layer Model:**\n\nThe Windows API can be conceptualized as operating across three distinct layers:\n\n1. **User-Mode DLLs**: Libraries like kernel32.dll, user32.dll, and gdi32.dll that applications link against directly\n2. **Native API (ntdll.dll)**: A lower-level interface that the user-mode DLLs call internally\n3. **Kernel Mode**: The actual Windows kernel services that perform the requested operations\n\nWhen an application calls a Windows API function like `CreateFile`, the call flows through these layers:"},"type":"text"},{"data":{"fileName":"Windows API Call Flow","languages":[{"code":"Application calls CreateFile()\n │\n ▼\nkernel32.dll!CreateFileW()\n │\n ├─ Parameter validation\n ├─ Unicode conversion if needed\n │\n ▼\nntdll.dll!NtCreateFile()\n │\n ├─ System call number lookup\n ├─ Transition to kernel mode (syscall instruction)\n │\n ▼\nntoskrnl.exe!NtCreateFile()\n │\n ├─ Security checks\n ├─ Object manager operations\n ├─ File system driver dispatch\n │\n ▼\nReturn to user mode with result","label":"Pseudocode","value":"pseudo"}],"showLineNumbers":true},"type":"code"},{"data":{"content":"**Core Windows API Libraries:**\n\nThe Windows API functionality is distributed across numerous DLLs. The most fundamental include:"},"type":"text"},{"data":{"rows":[["kernel32.dll","Core OS services","CreateProcess, CreateFile, VirtualAlloc, CreateThread"],["user32.dll","Window management, UI","CreateWindow, GetMessage, SendMessage, MessageBox"],["gdi32.dll","Graphics Device Interface","CreateDC, BitBlt, TextOut, SelectObject"],["advapi32.dll","Security, registry, services","RegOpenKey, OpenProcessToken, CreateService"],["ntdll.dll","Native API (internal)","NtCreateFile, NtQuerySystemInformation, RtlInitUnicodeString"],["ws2_32.dll","Network sockets (Winsock)","socket, connect, send, recv, WSAStartup"],["ole32.dll","COM infrastructure","CoInitialize, CoCreateInstance, CoTaskMemAlloc"]],"caption":"Primary Windows API Libraries","headers":["Library","Purpose","Key Functions"]},"type":"table"},{"data":{"icon":"AlertCircle","title":"Native API vs Documented API","content":"The Native API (ntdll.dll) is largely undocumented and not guaranteed to remain stable between Windows versions. Production applications should use the documented Win32/Win64 API functions. The Native API is primarily intended for internal use by Windows components and driver developers.","variant":"warning"},"type":"callout"},{"data":{"content":"$6a"},"type":"text"}],"titleType":"number","titleNumber":2},{"id":"programming-model","title":"Programming Model and Conventions","content":[{"data":{"content":"The Windows API employs distinctive programming conventions that differ significantly from C standard library or POSIX patterns. Understanding these conventions is crucial for reading and writing Windows code effectively.\n\n**Hungarian Notation:**\n\nThe Windows API heavily uses Hungarian notation, a naming convention where variable names include prefixes indicating their type. While controversial in modern programming, understanding Hungarian notation is essential for working with Windows code:"},"type":"text"},{"data":{"rows":[["sz","Null-terminated string (ANSI)","szFileName"],["wsz","Wide (Unicode) null-terminated string","wszFileName"],["p","Pointer","pBuffer"],["lp","Long pointer (legacy, now same as p)","lpBuffer"],["h","Handle","hFile, hProcess"],["dw","DWORD (32-bit unsigned)","dwSize, dwFlags"],["n","Integer","nCount"],["b","Boolean (BOOL)","bSuccess"],["c","Character or count","cchBuffer (character count)"],["cb","Count of bytes","cbBuffer"],["w","Word (16-bit unsigned)","wVersion"],["f","Flags or float","fOptions"]],"caption":"Common Hungarian Notation Prefixes in Windows API","headers":["Prefix","Meaning","Example"]},"type":"table"},{"data":{"content":"**Fundamental Data Types:**\n\nThe Windows API defines its own type system, both for clarity and for platform abstraction. These types are defined in Windows header files and should be used in preference to raw C types:"},"type":"text"},{"data":{"fileName":"windows_types.h","languages":[{"code":"$6b","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"icon":"Lightbulb","title":"Use Polymorphic Types","content":"When writing code that should work on both 32-bit and 64-bit Windows, always use polymorphic types like SIZE_T, INT_PTR, and ULONG_PTR for values that might hold pointers or sizes. Never assume a pointer fits in a DWORD—this was a common source of bugs during the 32-to-64-bit transition.","variant":"tip"},"type":"callout"},{"data":{"content":"**Function Naming Conventions:**\n\nWindows API functions follow consistent naming patterns:\n\n1. **Verb-Object pattern**: Functions typically start with a verb describing the action, followed by the object being acted upon:\n - `CreateFile`, `CloseHandle`, `ReadFile`, `WriteFile`\n - `CreateProcess`, `TerminateProcess`, `OpenProcess`\n - `AllocateVirtualMemory`, `FreeVirtualMemory`\n\n2. **ANSI and Unicode suffixes**: Many functions have two versions:\n - `CreateFileA` - ANSI version (8-bit characters)\n - `CreateFileW` - Wide/Unicode version (16-bit characters)\n - `CreateFile` - Macro that resolves to A or W based on UNICODE define\n\n3. **Ex suffixes**: Extended versions with additional functionality:\n - `CreateFile` → `CreateFileEx` (rarely used)\n - `CreateProcess` → `CreateProcessAsUser` / `CreateProcessWithLogon`\n\n4. **2 suffixes**: Updated versions, often for security improvements:\n - `InitializeCriticalSection` → `InitializeCriticalSectionAndSpinCount`"},"type":"text"},{"data":{"fileName":"function_versions.c","languages":[{"code":"// The UNICODE preprocessor symbol controls function resolution\n// In Windows headers, you'll find:\n\n#ifdef UNICODE\n #define CreateFile CreateFileW\n #define MessageBox MessageBoxW\n #define GetModuleFileName GetModuleFileNameW\n#else\n #define CreateFile CreateFileA\n #define MessageBox MessageBoxA\n #define GetModuleFileName GetModuleFileNameA\n#endif\n\n// Modern Windows development should always use Unicode\n// Define UNICODE and _UNICODE before including Windows headers,\n// or set them in your project configuration\n\n#define UNICODE\n#define _UNICODE\n#include \n\n// Now all generic names resolve to Unicode versions:\n// CreateFile → CreateFileW\n// MessageBox → MessageBoxW\n\n// Best practice: Use explicit W versions for clarity\nHANDLE hFile = CreateFileW(\n L\"C:\\\\data\\\\file.txt\", // Unicode string literal\n GENERIC_READ,\n 0,\n NULL,\n OPEN_EXISTING,\n FILE_ATTRIBUTE_NORMAL,\n NULL\n);","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":3},{"id":"error-handling","title":"Error Handling in the Windows API","content":[{"data":{"content":"Error handling in the Windows API differs fundamentally from POSIX conventions. While POSIX functions typically return -1 on error and set `errno`, Windows functions use a combination of return values and a thread-local error code.\n\n**The Basic Pattern:**\n\nMost Windows API functions signal failure through their return value and provide detailed error information via `GetLastError()`:"},"type":"text"},{"data":{"fileName":"error_handling.c","languages":[{"code":"$6c","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"icon":"AlertCircle","title":"GetLastError() Must Be Called Immediately","content":"The error code from GetLastError() is stored in thread-local storage and can be overwritten by any subsequent Windows API call, even successful ones. Always capture the error code immediately after detecting a failure, before calling any other Windows API functions.","variant":"warning"},"type":"callout"},{"data":{"content":"**Return Value Conventions:**\n\nDifferent categories of Windows API functions use different conventions for signaling success and failure:"},"type":"text"},{"data":{"rows":[["HANDLE","Valid handle value","`NULL` or `INVALID_HANDLE_VALUE`","CreateFile, CreateProcess, CreateThread"],["BOOL","`TRUE` (non-zero)","`FALSE` (zero)","ReadFile, WriteFile, CloseHandle"],["LONG / DWORD","Varies by function","Varies, often 0 or -1","GetWindowLong, RegQueryValue"],["PVOID (pointer)","Non-NULL pointer","`NULL`","VirtualAlloc, MapViewOfFile"],["HRESULT","`S_OK` (0) or success codes","Negative values","COM functions, DirectX, newer APIs"]],"caption":"Windows API Return Value Conventions","headers":["Return Type","Success Value","Failure Value","Examples"]},"type":"table"},{"data":{"fileName":"error_patterns.c","languages":[{"code":"$6d","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"icon":"Info","title":"INVALID_HANDLE_VALUE vs NULL","content":"File operations return INVALID_HANDLE_VALUE (defined as (HANDLE)-1 or 0xFFFFFFFF/0xFFFFFFFFFFFFFFFF) on failure, not NULL. However, many other handle-returning functions return NULL on failure. Always check the documentation for each function to know which failure value to expect.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":4},{"id":"windows-headers","title":"The Windows Header Files","content":[{"data":{"content":"Accessing the Windows API requires including the appropriate header files. The structure of Windows headers is both comprehensive and complex, having evolved over three decades of Windows development.\n\n**The windows.h Master Header:**\n\nMost Windows programs include ``, which acts as an umbrella header that includes most of the fundamental Windows API declarations:"},"type":"text"},{"data":{"fileName":"windows_headers.c","languages":[{"code":"$6e","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"icon":"AlertCircle","title":"Header Order Matters","content":"If you use Winsock2, you must include BEFORE . The original Winsock header is included by windows.h, and the two are incompatible. This is a common source of confusing compilation errors.","variant":"warning"},"type":"callout"},{"data":{"content":"**Targeting Windows Versions:**\n\nWindows headers use preprocessor symbols to enable or disable functions based on the targeted Windows version. This allows you to write code that uses newer features while remaining aware of compatibility constraints:"},"type":"text"},{"data":{"rows":[["Windows Vista","0x0600","Transactional NTFS, UAC APIs"],["Windows 7","0x0601","Touch input, DirectWrite"],["Windows 8","0x0602","App containers, WinRT interop"],["Windows 8.1","0x0603","Per-monitor DPI awareness"],["Windows 10 (1507)","0x0A00","Universal CRT"],["Windows 10 (1903+)","0x0A00 + manifest","Package identity APIs"],["Windows 11","0x0A00","Same as Windows 10 (binary compatible)"]],"caption":"Windows Version Targeting Macros","headers":["Version","WINVER / _WIN32_WINNT","Key Features Added"]},"type":"table"},{"data":{"fileName":"version_checking.c","languages":[{"code":"// Conditional compilation based on target version\n#if _WIN32_WINNT >= 0x0602 // Windows 8+\n // Use new memory functions\n DiscardVirtualMemory(address, size);\n#else\n // Fall back to older approach\n VirtualAlloc(address, size, MEM_RESET, PAGE_READWRITE);\n#endif\n\n// Runtime version checking (for features that may not exist)\ntypedef BOOL (WINAPI *PFN_SetProcessDpiAwarenessContext)(DPI_AWARENESS_CONTEXT);\n\nBOOL SetDpiAwareness() {\n HMODULE hUser32 = GetModuleHandleW(L\"user32.dll\");\n if (!hUser32) return FALSE;\n \n // Try to get the newest function first\n PFN_SetProcessDpiAwarenessContext pSetContext = \n (PFN_SetProcessDpiAwarenessContext)GetProcAddress(\n hUser32, \n \"SetProcessDpiAwarenessContext\"\n );\n \n if (pSetContext) {\n // Windows 10 1703+\n return pSetContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);\n }\n \n // Fall back to older DPI awareness API...\n return SetProcessDPIAware(); // Windows Vista+\n}","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"content":"**Windows SDK Organization:**\n\nThe Windows SDK contains thousands of header files organized by functionality:\n\n```\nWindows Kits/\n└── 10/\n └── Include/\n ├── 10.0.xxxxx.0/\n │ ├── shared/ # Headers shared with drivers\n │ ├── um/ # User-mode headers (most Win32 API)\n │ ├── ucrt/ # Universal C Runtime headers\n │ ├── winrt/ # Windows Runtime (UWP) headers\n │ └── cppwinrt/ # C++/WinRT projections\n └── lib/\n └── 10.0.xxxxx.0/\n ├── um/x86/ # 32-bit import libraries\n └── um/x64/ # 64-bit import libraries\n```\n\nThe SDK is versioned by build number (e.g., 10.0.22621.0), and Visual Studio typically selects the appropriate version automatically."},"type":"text"}],"titleType":"number","titleNumber":5},{"id":"complete-example","title":"A Complete Windows API Example","content":[{"data":{"content":"To solidify understanding of the Windows API programming model, let's examine a complete, production-quality example that demonstrates proper Windows API usage patterns—including error handling, resource cleanup, and adherence to conventions:"},"type":"text"},{"data":{"fileName":"file_processor.c","languages":[{"code":"$6f","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"icon":"CheckCircle","title":"Key Patterns in This Example","content":"This example demonstrates several critical patterns: (1) Proper resource cleanup using goto cleanup pattern, (2) Immediate capture of error codes, (3) Parameter validation, (4) Use of appropriate buffer sizes, (5) Handle validity checks using correct sentinel values, and (6) Using wmain for Unicode-aware entry point.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":6},{"id":"summary","title":"Summary: The Foundation of Windows Programming","content":[{"data":{"content":"The Windows API (Win32/Win64) represents the fundamental interface between user-mode applications and the Windows operating system. Understanding its architecture, conventions, and programming model is essential for anyone doing serious Windows development."},"type":"text"},{"data":{"type":"ordered","items":["**Historical evolution shapes current design**: The API evolved from Win16 to Win32 to Win64, and understanding this history explains many conventions","**Three-layer architecture**: Applications call user-mode DLLs, which call the Native API, which transitions to kernel mode","**Hungarian notation and Windows types**: The API uses its own type system and naming conventions that differ from standard C","**Unique error handling model**: GetLastError() provides thread-local error codes that must be captured immediately after failures","**Unicode is modern standard**: Always use the W-suffix functions and Unicode strings in new development","**Proper resource management is essential**: Windows handles must be explicitly closed using CloseHandle() or appropriate functions","**Header configuration matters**: Proper definition of version macros and feature flags affects what API is available"],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's Next:**\n\nWith this foundation in the Windows API's design and conventions, we'll next explore how applications actually invoke Windows system calls—the mechanism by which user-mode code requests kernel services. Understanding this layer completes the picture of how applications interact with the Windows operating system."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now understand the Windows API's architecture, history, programming model, and conventions. This knowledge provides the foundation for all subsequent Windows system programming topics, including system calls, handles, registry operations, and comparison with other platforms.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":7}],"isLocked":false},{"id":"seed_6d01d071ec7a2bdab1cd2cce91bb530a","title":"Windows System Calls","order":1,"content":null,"isLocked":true},{"id":"seed_3a4e180aeaa6e6fa29e83ce1b57cd9d8","title":"Handle-Based Access","order":2,"content":null,"isLocked":true},{"id":"seed_1b92a391b697dcfaca1c4f77b13abf55","title":"Registry Operations","order":3,"content":null,"isLocked":true},{"id":"seed_7ed27e5df8d1ec7a1e9a1c2ebea4cd6e","title":"Comparison with POSIX","order":4,"content":null,"isLocked":true}]}}