Шпаргалка по Windows API: основные функции Win32, команды и сценарии

Windows API (Win32) — это фундамент, на котором строятся все приложения для Windows. Если вы пишете код, который взаимодействует с системой на низком уровне, вам нужен быстрый доступ к ключевым функциям: работа с файлами, процессами, памятью и реестром. Эта статья — не общий обзор, а компактный справочник с конкретными сигнатурами, примерами и типичными сценариями использования. Здесь нет лишней теории — только то, что пригодится в ежедневной разработке.

Базовые понятия, которые нужно знать перед стартом

Прежде чем переходить к функциям, разберём четыре важных механизма, без которых невозможно правильно работать с Win32.

Дескрипторы (HANDLE) и их закрытие

Большинство функций Win32, открывающих ресурсы (файлы, процессы, ключи реестра), возвращают значение типа HANDLE — это целочисленный дескриптор (непрозрачный идентификатор), который ядро использует для ссылки на объект. Он не является указателем на память и не должен интерпретироваться как адрес. Дескриптор нужно обязательно закрывать с помощью CloseHandle (или специализированной функции, например RegCloseKey), иначе произойдёт утечка ресурсов. Каждый открытый дескриптор потребляет память и может привести к нестабильности системы при долгой работе.

INVALID_HANDLE_VALUE

При ошибке функция CreateFile возвращает не NULL, а специальное значение INVALID_HANDLE_VALUE (определено как (HANDLE)-1). Это важно помнить: проверяйте именно на это значение, а не на NULL.

Коды ошибок и GetLastError

Каждая функция Win32 возвращает своё специальное значение ошибки: это может быть FALSE (0) для функций с типом BOOL, NULL для функций, возвращающих указатели (например, VirtualAlloc, OpenProcess), INVALID_HANDLE_VALUE для CreateFile, или код, отличный от ERROR_SUCCESS для функций реестра. Чтобы получить детальную причину, сразу после неудачного вызова используйте GetLastError(). Код ошибки можно сопоставить с константами из winerror.h (например, ERROR_FILE_NOT_FOUND).

Версии функций: A и W

Многие строковые функции существуют в двух вариантах: с суффиксом A (ANSI, однобайтовая кодировка) и W (широкие символы, UTF-16). В современных проектах рекомендуется использовать W-версии, так как Windows внутренне работает с UTF-16. При использовании A-версий происходит преобразование в кодовую страницу системы (например, Windows-1251), что может исказить нелатинские символы. Убедитесь, что в проекте определены макросы UNICODE и _UNICODE, чтобы по умолчанию вызывались широкие версии.

Ключевые функции Win32: сводная таблица

Ниже приведены наиболее востребованные функции, сгруппированные по категориям. Для каждой указаны: назначение, основные параметры, возвращаемое значение и типичный сценарий использования.

Работа с файлами и каталогами

Управление процессами

Управление памятью

Работа с реестром

Примитивы синхронизации

Практические примеры кода

Чтение файла с обработкой ошибок

#include <windows.h>
#include <stdio.h>

int main() {
    HANDLE hFile = CreateFileW(
        L"example.txt",
        GENERIC_READ,
        FILE_SHARE_READ,
        NULL,
        OPEN_EXISTING,
        FILE_ATTRIBUTE_NORMAL,
        NULL
    );

    if (hFile == INVALID_HANDLE_VALUE) {
        DWORD err = GetLastError();
        printf("Не удалось открыть файл, ошибка: %lu\n", err);
        return 1;
    }

    char buffer[1024];
    DWORD bytesRead;
    if (!ReadFile(hFile, buffer, sizeof(buffer) - 1, &bytesRead, NULL)) {
        DWORD err = GetLastError();
        printf("Ошибка чтения: %lu\n", err);
        CloseHandle(hFile);
        return 1;
    }

    buffer[bytesRead] = '\0';
    printf("Содержимое: %s\n", buffer);

    CloseHandle(hFile);
    return 0;
}

Запуск процесса (калькулятор) и ожидание его завершения

STARTUPINFOW si = { sizeof(si) };
PROCESS_INFORMATION pi;
if (CreateProcessW(
        L"C:\\Windows\\System32\\calc.exe",
        NULL, NULL, NULL, FALSE,
        0, NULL, NULL, &si, &pi)) {
    WaitForSingleObject(pi.hProcess, INFINITE);
    CloseHandle(pi.hProcess);
    CloseHandle(pi.hThread);
} else {
    printf("Ошибка запуска: %lu\n", GetLastError());
}

Чтение значения из реестра

HKEY hKey;
LONG result = RegOpenKeyExW(
    HKEY_LOCAL_MACHINE,
    L"SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion",
    0, KEY_READ, &hKey);

if (result == ERROR_SUCCESS) {
    WCHAR buffer[256];
    // Внимание: размер буфера передаётся в байтах, а не в символах.
    // Для WCHAR-массива sizeof(buffer) даёт общий размер в байтах,
    // что корректно для RegQueryValueExW.
    DWORD bufferSize = sizeof(buffer);
    DWORD type;
    if (RegQueryValueExW(hKey, L"ProductName", NULL, &type,
                         (LPBYTE)buffer, &bufferSize) == ERROR_SUCCESS) {
        wprintf(L"Имя продукта: %s\n", buffer);
    }
    RegCloseKey(hKey);
} else {
    printf("Не удалось открыть ключ, код: %ld\n", result);
}

Частые ошибки и как их избежать (кратко)

• Забыли закрыть дескриптор — всегда используйте CloseHandle или RegCloseKey в паре с открытием.
• Проверка на NULL вместо INVALID_HANDLE_VALUE — для CreateFile проверяйте именно на INVALID_HANDLE_VALUE.
• Игнорирование кодов ошибок — вызывайте GetLastError() сразу после неудачного вызова.
• Смешивание ANSI и Unicode — используйте W-версии функций и определите UNICODE.
• Неправильный размер буфера — всегда передавайте актуальный размер и проверяйте, сколько байт записано.

Часто задаваемые вопросы (FAQ)

Заключение

Этот справочник покрывает основные функции Win32, которые понадобятся в большинстве прикладных задач. Освоив чтение файлов, запуск процессов, работу с реестром и базовую синхронизацию, вы сможете создавать надёжные системные утилиты и тонко настраивать поведение приложений. Для углублённого изучения обращайтесь к официальной документации Microsoft Learn — там вы найдёте полные списки параметров и дополнительные примеры.

Если вы тестируете Win32-приложения, которые требуют изолированного окружения, удобно использовать выделенный сервер — например, VPS от Serverspace. На нём можно развернуть чистую Windows, проводить эксперименты с дескрипторами и памятью, не боясь нарушить стабильность основной рабочей станции.