FormatMessage函数格式化消息字符串。该函数需要一个消息定义作为输入。消息定义可以来自传递到函数中的缓冲区。它可以来自已加载模块中的消息表资源。或者呼叫者可以要求该函数在系统的消息表资源中搜索消息定义。该函数基于消息标识符和语言标识符在消息表资源中查找消息定义。该函数将格式化的消息文本复制到输出缓冲区，如果请求，则处理任何嵌入的插入序列。
DWORD FormatMessage（
| DWORD 【dwFlags中】, | //源和处理选项 |
| LPCVOID 【// pointer to message source】, | //指向消息源的指针 |
| DWORD 【dwMessageId】, | //请求的消息标识符en |
| DWORD 【dwLanguageId】, | //所请求消息的语言标识符 |
| LPTSTR 【lpBuffer】, | //指向消息缓冲区的指针 |
| DWORD 【服务提供商】, | //消息缓冲区的最大大小 |
| va_list的 【*参数】 | //消息插入数组的地址 |
| ); |
参数
【dwFlags中】
包含一组位标志，用于指定格式化过程的各个方面以及如何解释【// pointer to message source】参数。【dwFlags中】的低位字节指定函数如何处理输出缓冲区中的换行符。低位字节也可以指定格式化输出行的最大宽度。
您可以指定以下位标志的组合：
| 值 | 含义 | ||||
| FORMAT_MESSAGE_ALLOCATE_BUFFER | |||||
| 指定【lpBuffer】参数是指向PVOID指针的指针，并且【服务提供商】参数指定要为输出消息缓冲区分配的最小字节数（ANSI版本）或字符（Unicode版本）。该函数分配一个足够大的缓冲区以容纳格式化的消息，并将指针指向由【lpBuffer】指定的地址分配的缓冲区。当不再需要时，调用者应使用LocalFree函数来释放缓冲区。 | |||||
| FORMAT_MESSAGE_IGNORE_INSERTS | |||||
| 指定消息定义中的插入序列将被忽略，并将其传递给输出缓冲区。此标志对于获取稍后格式化的消息很有用。如果设置此标志，则【参数】参数将被忽略。 | |||||
| FORMAT_MESSAGE_FROM_STRING | |||||
| 指定【// pointer to message source】是一个指向空终止消息定义的指针。消息定义可以包含插入序列，就像消息表资源中的消息文本一样。不能与FORMAT_MESSAGE_FROM_HMODULE或FORMAT_MESSAGE_FROM_SYSTEM一起使用。 | |||||
| FORMAT_MESSAGE_FROM_HMODULE | |||||
| 指定【// pointer to message source】是一个包含要搜索的消息表资源的模块句柄。如果此【// pointer to message source】句柄为NULL，则将搜索当前进程的应用程序映像文件。不能与FORMAT_MESSAGE_FROM_STRING一起使用。 | |||||
| FORMAT_MESSAGE_FROM_SYSTEM | |||||
| 指定该函数应在系统消息表资源中搜索所请求的消息。如果使用FORMAT_MESSAGE_FROM_HMODULE指定了该标志，则如果在【// pointer to message source】指定的模块中找不到该消息，该函数将搜索系统消息表。不能与FORMAT_MESSAGE_FROM_STRING一起使用。 如果指定了此标志，应用程序可以传递GetLastError函数的结果来检索系统定义错误的消息文本。 | |||||
| FORMAT_MESSAGE_ARGUMENT_ARRAY | |||||
| 指定GetLastError一个va_list的结构的【不】参数，而只是一个指向表示参数的32位值数组的指针。 | |||||
【dwFlags中】的低位字节可以指定格式化输出行的最大宽度。使用FORMAT_MESSAGE_MAX_WIDTH_MASK常量和按位布尔运算来设置和检索此最大宽度值。
下表显示了FormatMessage如何解释低位字节的值。
| 值 | 含义 |
| 0 | 没有输出行宽限制。该函数将消息定义文本中的换行符存储到输出缓冲区中。 |
| 非FORMAT_MESSAGE_MAX_WIDTH_MASK以外的非零值 | 非零值是输出行中的最大字符数。该函数忽略消息定义文本中的常规换行符。该函数不会分割一个由空格划分的字符串。该函数将消息定义文本中的硬编码换行符存储到输出缓冲区中。硬编码换行符用％n转义序列编码。 |
| FORMAT_MESSAGE_MAX_WIDTH_MASK | 该函数忽略消息定义文本中的常规换行符。该函数将消息定义文本中的硬编码换行符存储到输出缓冲区中。该函数不会生成新的换行符。 |
【// pointer to message source】
指定消息定义的位置。此参数的类型取决于【dwFlags中】参数中的设置。
| 【dwFlags中】设置 | 参数类型 |
| FORMAT_MESSAGE_FROM_HMODULE | 【// pointer to message source】是包含要搜索的消息表的模块的hModule。 |
| FORMAT_MESSAGE_FROM_STRING | 【// pointer to message source】是一个LPTSTR，指向未格式化的消息文本。它将被扫描进行插入并相应格式化。 |
如果【dwFlags中】中没有设置这些标志，则忽略【// pointer to message source】.
【dwMessageId】
指定所请求消息的32位消息标识符。如果【dwFlags中】包含FORMAT_MESSAGE_FROM_STRING，则忽略此参数。
【dwLanguageId】
指定所请求消息的32位语言标识符。如果【dwFlags中】包含FORMAT_MESSAGE_FROM_STRING，则忽略此参数。
如果您在此参数中传递特定LANGID，则FormatMessage将仅返回该LANGID的消息。如果该函数无法找到该LANGID的消息，则返回ERROR_RESOURCE_LANG_NOT_FOUND。如果您传入零，FormatMessage按以下顺序寻找LANGID的邮件：
语言中立
2.Thread LANGID，基于线程的区域设置值
3.根据用户的默认语言环境值，使用默认LANGID
4.系统默认LANGID，基于系统默认的语言环境值
5.US英文
如果FormatMessage没有找到任何上述LANGID的消息，它将返回任何存在的语言消息字符串。如果即使失败，它返回ERROR_RESOURCE_LANG_NOT_FOUND。
【lpBuffer】
指向格式化（和空终止）消息的缓冲区。如果【dwFlags中】包含FORMAT_MESSAGE_ALLOCATE_BUFFER，则该函数将使用LocalAlloc函数分配缓冲区，并将缓冲区的地址放置在【lpBuffer】中指定的地址。
【服务提供商】
如果未设置FORMAT_MESSAGE_ALLOCATE_BUFFER标志，则此参数指定可存储在输出缓冲区中的最大字节数（ANSI版本）或字符（Unicode版本）。如果设置了FORMAT_MESSAGE_ALLOCATE_BUFFER，则此参数指定要为输出缓冲区分配的最小字节数或字符数。
【参数】
指向用作格式化消息中的插入值的32位值数组。格式字符串中的％1表示【参数】数组中的第一个值; ％2表示第二个参数;等等。
每个32位值的解释取决于与消息定义中的插入相关联的格式信息。默认值是将每个值作为指向空终止字符串的指针。
默认情况下，【参数】参数的类型为va_list的*，它是一种语言和实现特定的数据类型，用于描述可变数量的参数。如果没有类型为va_list的*的指针，则指定FORMAT_MESSAGE_ARGUMENT_ARRAY标志，并将指针传递给32位值的数组;那些值被输入到格式化为插入值的消息中。每个插入必须在数组中具有相应的元素。
返回值
如果函数成功，则返回值是存储在输出缓冲区中的字节数（ANSI版本）或字符（Unicode版本），不包括终止空字符。
如果函数失败，返回值为零。要获取扩展错误信息，请调用GetLastError.
备注
FormatMessage功能可用于获取GetLastError返回的系统错误代码的错误消息字符串，如以下示例代码所示。
LPVOID lpMsgBuf;
FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM,
NULL,
GetLastError(),
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), //默认语言
（LPTSTR）& lpMsgBuf，
0,
NULL
);
//显示字符串。
MessageBox（NULL，lpMsgBuf，“GetLastError”，MB_OK | MB_ICONINFORMATION）;
//释放缓冲区
LocalFree( lpMsgBuf );
在消息文本中，支持动态格式化消息的几个转义序列。这些转义序列及其含义如下表所示。所有转义序列以百分比字符（％）开头。
| 逃脱序列 | 含义 |
| %0 | 终止消息文本行，不带尾随换行符。此转义序列可用于构建长行或终止消息本身，而不带尾随的换行符。它对于提示信息很有用。 |
| %【n】!【printf格式的字符串】! | 标识插入。【n】的值可以在1到99之间。的printf格式的字符串（必须用感叹号括起来）是可选的，如果未指定，则默认为!s!. |
| 的printf格式字符串可以包含精度或宽度分量的*说明符。如果*指定为一个组件，则FormatMessage函数使用插入％【n】 +1;如果为两个组件指定了*，它使用％【n】?? +2。 | |
| 不支持浮点的printf格式说明符__ e，E，f和g __。解决方法是使用的sprintf函数将浮点数格式化为临时缓冲区，然后将该缓冲区用作插入字符串。 |
百分比字符后面的任何其他非字符字符在输出消息中格式化，而不包含百分比字符。以下是一些例子：
| 格式化字符串 | 产生的结果 |
| %% | 格式化的消息文本中单个百分比登录。 |
| %n | 当格式化字符串出现在行的末尾时，硬线路断开。当FormatMessage提供常规换行符，以便邮件适合某个宽度时，此格式字符串很有用。 |
| %【空间】 | 格式化消息文本中的空格。此格式字符串可用于确保消息文本行中相应数量的尾随空格。 |
| %. | 格式化消息文本中的单个时间段。此格式字符串可用于在行的开始处包含单个句点，而不终止消息文本定义。 |
| %! | 格式化消息文本中的一个感叹号。此格式字符串可用于在插入后立即包含感叹号，而不会将其错误地标识为的printf格式字符串的开头。 |
也可以看看
