读书笔记摘抄新闻资讯FormatMessage
FormatMessage是一个Windows API函式。它的功能就是将GetLastError函式得到的错误信息（这个错误信息是数字代号）转化成字元串信息的函式。
基本介绍
- 外文名：FormatMessage
- 含义：Windows API函式
- 功能：GetLastError的返回值换成字元串
- 可选参数：dwFlags
语法
DWORD WINAPI FormatMessage ( DWORD dwFlags, // source and processing options LPCVOID lpSource, // message source DWORD dwMessageId, // message identifier DWORD dwLanguageId, // language identifier LPTSTR lpBuffer, // message buffer DWORD nSize, // maximum size of message buffer va_list *Arguments // array of message inserts );
参数
dwFlags
标誌位，决定如何说明lpSource参数，dwFlags的低位指定如何处理换行功能在输出缓冲区，也决定最大宽度的格式化输出行。
可选参数：
| 标誌 | 标誌说明 |
|---|---|
FORMAT_MESSAGE_ALLOCATE_BUFFER | 函式会分配一个足够大的缓冲区保存格式化讯息，并且通过lpBuffer指向该 地址。当不再使用lpBuffer数据时，需调用LocalFree释放记忆体。 |
FORMAT_MESSAGE_ARGUMENT_ARRAY | Arguments参数不是指向va_list结构体，是一个指向保存参数的数组指针。 |
FORMAT_MESSAGE_FROM_HMODULE | 指定lpSource参数是要去搜寻的一个包含讯息表的模组句柄。如果 lpSource 是NULL，会搜寻当前进程的主模组，这个标誌不能与FORMAT_MESSAGE_FROM_STRING 同时使用。 |
FORMAT_MESSAGE_FROM_STRING | lpSource参数是一个指向以NULL结尾的字元串，字元串包含一个讯息定义， 这个讯息定义可以包含插入序列。此标誌不能与FORMAT_MESSAGE_FROM_HMODULE 、 FORMAT_MESSAGE_FROM_SYSTEM同时使用 |
FORMAT_MESSAGE_FROM_SYSTEM 0x00001000 | 函式会从系统信息列表中搜寻所请求的信息。如果使用 FORMAT_MESSAGE_FROM_HMODULE，函式会先在lpSource指定 的模组中搜寻请求的讯息，如果搜寻不到再去搜寻系统讯息表资源。此 标誌不能与FORMAT_MESSAGE_FROM_STRING同时使用。 |
FORMAT_MESSAGE_IGNORE_INSERTS | 指定讯息定义中的插入序列将被忽略，并将其直接传递给输出缓冲区。 此标誌对于获取稍后格式化的讯息很有用。 如果设定了此标誌，则忽略Arguments参数。 |
lpSource
根据dwFlags标誌而定。
dwMessageId
请求的讯息的标识符。当dwFlags标誌为FORMAT_MESSAGE_FROM_STRING时会被忽略。
dwLanguageId
请求的讯息的语言标识符。
LPTSTR lpBuffer
接收错误信息描述的缓冲区指针。
nSize
如果FORMAT_MESSAGE_ALLOCATE_BUFFER标誌没有被指定，这个参数必须指定为输出缓冲区的大小，如果指定值为0，这个参数指定为分配给输出缓冲区的最小数。
Arguments
保存格式化信息中的插入值的一个数组。
返回值
如果函式调用成功，返回输出缓冲区的大小，除最后一个空字元。如果失败则返回0。
举例
// 系统错误信息提示。void TestErrorInfo(void){ //进行出错。 if (!CreateDirectory(_T("c:\\"),0)) { TCHAR szBuf[128]; LPVOID lpMsgBuf; DWORD dw = GetLastError(); FormatMessage ( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM, NULL, dw, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPTSTR) &lpMsgBuf, 0, NULL ); wsprintf(szBuf, _T("%s 出错信息 (出错码=%d): %s"), _T("CreateDirectory"), dw, lpMsgBuf); LocalFree(lpMsgBuf); //输出提示。 OutputDebugString(szBuf); }}调用后输出下面的提示信息：
CreateDirectory 出错信息 (出错码=5): 拒绝访问。
需求
| 客户端 | 需要Windows XP、Windows 2000 Professional、Windows NT Workstation、Windows Me、Windows 98或Windows 95。 |
|---|---|
| 伺服器 | 需要Windows Server 2003、Windows 2000 Server或Windows NT Server。 |
| 头档案 | 在Winbase.h中声明，包含于Windows.h。 |
| 库档案 | Kernel32.lib。 |
| DLL | 需要Kernel32.dll。 |
| Unicode | 以FormatMessageW (Unicode)和FormatMessageA (ANSI)的形式实现。 |