【Windows API】FormatMessageA 函数签名

FormatMessageA 函数签名详解

FormatMessageA 是 Windows API 中用于格式化错误消息的核心函数，以下是它的完整函数签名和参数说明：

函数签名

DWORD FormatMessageA(
  DWORD   dwFlags,
  LPCVOID lpSource,
  DWORD   dwMessageId,
  DWORD   dwLanguageId,
  LPSTR   lpBuffer,
  DWORD   nSize,
  va_list *Arguments
);

参数详解

dwFlags 常用标志

lpSource 的用法

根据 dwFlags 的不同：

• FROM_SYSTEM：应为 NULL
• FROM_HMODULE：包含消息表的模块句柄
• FROM_STRING：指向消息字符串的指针

返回值

• 成功：返回存储在输出缓冲区中的字符数（不包括终止null字符）
• 失败：返回0，可通过 GetLastError() 获取错误信息

典型用法示例

示例1：获取系统错误消息（自动分配缓冲区）

LPSTR messageBuffer = nullptr;
DWORD size = FormatMessageA(
    FORMAT_MESSAGE_ALLOCATE_BUFFER | 
    FORMAT_MESSAGE_FROM_SYSTEM |
    FORMAT_MESSAGE_IGNORE_INSERTS,
    nullptr,
    GetLastError(),
    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
    (LPSTR)&messageBuffer,  // 注意这里传递指针的地址
    0,
    nullptr);

if (size > 0) {
    printf("Error: %s\n", messageBuffer);
    LocalFree(messageBuffer);  // 必须释放分配的缓冲区
}

示例2：使用预分配缓冲区

char buffer[256];
DWORD size = FormatMessageA(
    FORMAT_MESSAGE_FROM_SYSTEM,
    nullptr,
    GetLastError(),
    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
    buffer,
    sizeof(buffer),
    nullptr);

if (size > 0) {
    printf("Error: %s\n", buffer);
}

注意事项

1. 缓冲区管理：

   • 使用 ALLOCATE_BUFFER 时必须调用 LocalFree() 释放内存
   • 预分配缓冲区时要确保足够大

2. 语言选择：

   • MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT) 表示默认系统语言
   • 可以指定特定语言如 MAKELANGID(LANG_CHINESE, SUBLANG_CHINESE_SIMPLIFIED)

3. 错误处理：

   • 某些错误码需要从特定DLL获取消息（如网络错误需要加载netmsg.dll）

4. Unicode版本：

   • FormatMessageW 是Unicode版本
   • 在ANSI和Unicode通用代码中常用宏 FormatMessage

5. 插入参数：

   • 如果消息包含 %1、%2 等占位符，需要通过Arguments参数提供替换值

这个函数是Windows错误处理的核心API，正确使用它可以生成用户友好的错误消息，极大改善应用程序的错误报告能力。