Windows API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Application calls CreateFile()
       │
       ▼
kernel32.dll!CreateFileW()
       │
       ├─ Parameter validation
       ├─ Unicode conversion if needed
       │
       ▼
ntdll.dll!NtCreateFile()
       │
       ├─ System call number lookup
       ├─ Transition to kernel mode (syscall instruction)
       │
       ▼
ntoskrnl.exe!NtCreateFile()
       │
       ├─ Security checks
       ├─ Object manager operations
       ├─ File system driver dispatch
       │
       ▼
Return to user mode with result

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// 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;
#endif

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// The UNICODE preprocessor symbol controls function resolution
// In Windows headers, you'll find:
 
#ifdef UNICODE
    #define CreateFile  CreateFileW
    #define MessageBox  MessageBoxW
    #define GetModuleFileName GetModuleFileNameW
#else
    #define CreateFile  CreateFileA
    #define MessageBox  MessageBoxA
    #define GetModuleFileName GetModuleFileNameA
#endif
 
// Modern Windows development should always use Unicode
// Define UNICODE and _UNICODE before including Windows headers,
// or set them in your project configuration
 
#define UNICODE
#define _UNICODE
#include <windows.h>
 
// Now all generic names resolve to Unicode versions:
// CreateFile → CreateFileW
// MessageBox → MessageBoxW
 
// Best practice: Use explicit W versions for clarity
HANDLE hFile = CreateFileW(
    L"C:\\data\\file.txt",  // Unicode string literal
    GENERIC_READ,
    0,
    NULL,
    OPEN_EXISTING,
    FILE_ATTRIBUTE_NORMAL,
    NULL
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

#include <windows.h>
#include <stdio.h>
 
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);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

// 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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// 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>
 
// 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 <shellapi.h>     // Shell functions (ShellExecute, etc.)
#include <shlobj.h>       // Shell object interfaces
#include <tlhelp32.h>     // Tool help (process/thread enumeration)
#include <psapi.h>        // Process status API
#include <winsock2.h>     // Networking (MUST be before windows.h!)
#include <ws2tcpip.h>     // Modern socket functions
#include <dbghelp.h>      // Debug help library
#include <winternl.h>     // Some (few) internal functions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// Conditional compilation based on target version
#if _WIN32_WINNT >= 0x0602  // Windows 8+
    // Use new memory functions
    DiscardVirtualMemory(address, size);
#else
    // Fall back to older approach
    VirtualAlloc(address, size, MEM_RESET, PAGE_READWRITE);
#endif
 
// Runtime version checking (for features that may not exist)
typedef BOOL (WINAPI *PFN_SetProcessDpiAwarenessContext)(DPI_AWARENESS_CONTEXT);
 
BOOL SetDpiAwareness() {
    HMODULE hUser32 = GetModuleHandleW(L"user32.dll");
    if (!hUser32) return FALSE;
    
    // Try to get the newest function first
    PFN_SetProcessDpiAwarenessContext pSetContext = 
        (PFN_SetProcessDpiAwarenessContext)GetProcAddress(
            hUser32, 
            "SetProcessDpiAwarenessContext"
        );
    
    if (pSetContext) {
        // Windows 10 1703+
        return pSetContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);
    }
    
    // Fall back to older DPI awareness API...
    return SetProcessDPIAware();  // Windows Vista+
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

/*
 * 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 <windows.h>
#include <stdio.h>
#include <strsafe.h>  // 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 <filepath>
", argv[0]);
        return 1;
    }
    
    DWORD bytesProcessed;
    if (ProcessFile(argv[1], &bytesProcessed)) {
        wprintf(L"Successfully processed %lu bytes
", bytesProcessed);
        return 0;
    }
    
    return 1;
}