FormatMessage函数使用详解

来源：互联网发布：c语言实例编写小游戏编辑：程序博客网时间：2024/05/02 01:29

FormatMessage函数

在《windows核心编程》中第一个示例便是它的使用。

这个函数我用了几次之后终于明白它的用法；

这个函数是用来格式化消息字符串，就是处理消息资源的。消息资源是由mc.exe编译的，详细请在msdn中搜索mc.exe。

先来看下它的函数原型

DWORD WINAPI FormatMessage(
FormatMessage的用法 - kulong0105 - kulong0105的博客

__in DWORD dwFlags,
FormatMessage的用法 - kulong0105 - kulong0105的博客

__in LPCVOID lpSource,
FormatMessage的用法 - kulong0105 - kulong0105的博客

__in DWORD dwMessageId,
FormatMessage的用法 - kulong0105 - kulong0105的博客

__in DWORD dwLanguageId,
FormatMessage的用法 - kulong0105 - kulong0105的博客

__out LPTSTR lpBuffer,
FormatMessage的用法 - kulong0105 - kulong0105的博客

__in DWORD nSize,
FormatMessage的用法 - kulong0105 - kulong0105的博客

__in va_list* Arguments
FormatMessage的用法 - kulong0105 - kulong0105的博客

);

在使用这个函数的时候要明确以下几点

你要处理的消息资源来自哪里，这一点尤为重要。

你的消息ID来自哪里.

以下是每个参数的详细介绍：

dwFlags :

格式化选项，对lpSource参数值有指导作用。

dwFlags的低位值指定了函数如何处理输出缓冲区处理行转换，也可以指定格式化输出字符串输出行的最大宽度。它的位标示符如下：

Value

Meaning

FORMAT_MESSAGE_ALLOCATE_BUFFER
0x00000100

lpBuffer参数是一个PVOID指针，nSize参数指定按TCHARs为单位的分配给输出消息缓冲区的最小值。当你不再使用这个缓冲区的时候（也就是不再使用lpBuffer的时候）需要用LocalFree将其释放

FORMAT_MESSAGE_ARGUMENT_ARRAY
0x00002000

Arguments参数不是一个va_list结构，但是它表示一个数组指针。这个标识符不能在64位整数值时使用，你如果要使用64位整数值，那么你必须使用va_list结构体

FORMAT_MESSAGE_FROM_HMODULE
0x00000800

lpSource参数是一个包含了消息表资源（Message-table resources）模块（dll）句柄。如果lpSource句柄为NULL，系统会自动搜索当前进程文件的消息资源。

这个标示符不可以和FORMAT_MESSAGE_FROM_STRING共用。

如果模块中没有资源表，这个函数执行失败并且返回ERROR_RESOURCE_TYPE_NOT_FOUND错误值。

FORMAT_MESSAGE_FROM_STRING
0x00000400

lpSource参数指向一个包含了消息定义的字符串.这个消息定义里面可能包含了插入序列（insert sequence），像消息表资源中包含消息文本一样.和这个标示符不和FORMAT_MESSAGE_FROM_HMODULE或者FORMAT_MESSAGE_FROM_SYSTEM一起使用.

FORMAT_MESSAGE_FROM_SYSTEM
0x00001000

函数将会搜索系统消息表资源来寻找所需消息资源。如果这个标示符同时定义了FORMAT_MESSAGE_FROM_HMODULE,那么如果函数在模块中没有搜索到所需消息的话将会在系统中搜索。这个标示符不能和FORMAT_MESSAGE_FROM_STRING一起使用.

当这个标示符设置的时候，可以使用GetLastError函数返回值来搜索这个错误码在系统定义错误中相应的消息文本。

FORMAT_MESSAGE_IGNORE_INSERTS
0x00000200

在消息定义中的插入序列将会被忽略，这个标示符在获取一个格式化好的消息十分有用，如果这个标示符设置好了，那么Arguments参数将被忽略。

开始在上面说了dwflags参数低位值作用，你可以使用以下值来设置低位值。

Value

Meaning

将不会有输出行宽度限制。

FORMAT_MESSAGE_MAX_WIDTH_MASK
0x000000FF

将会有限制输出行宽度，使用硬编码设定。

lpSource：

这个值是消息表资源来自哪里，这个值依靠dwFlags,详细请看FORMAT_MESSAGE_FROM_HMODULE和FORMAT_MESSAGE_FROM_STRING，如果这两个标示符都没设置，那么lpSource将会被忽略。

dwMessageId ：

所需格式化消息的标识符。当dwFlags设置了FORMAT_MESSAGE_FROM_STRING，这个参数将会被忽略。

dwLanguageId：

格式化消息语言标识符。

一般设置为： MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // default language

lpBuffer：

一个缓冲区指针来接受格式化后的消息。当dwFlags包括了FORMAT_MESSAGE_ALLOCATE_BUFFER标志符，这个函数将会使用LocalAlloc函数分配一块缓冲区，lpBuffer需要接受一个地址来使用这个缓冲区。（这里要注意传参一定要传地址）。

nSize：

如果FORMAT_MESSAGE_ALLOCATE_BUFFER没有设置，那么这个参数指定了输出缓冲区的消息长度的最大值，以TCHARs为单位。如果FORMAT_MESSAGE_ALLOCATE_BUFFER设置了，这个参数设置以TCHARs为单位的输出缓冲区的最小值。这个输出缓冲区不能大于64KB。

Arguments:

一个数组中的值在格式化消息中作为插入值，根据消息文本的格式里面的内容（详见mc.exe使用），可以知道%n[!format_specifier!]为这个参数的指定形式。

比如说在格式字符串中的%1为数组中的第一个值，%2为第二个值。n就代表数组第几个值。

那么[！format_specifier!]如何解释呢？这个格式化指定具体解释在 Format Specification Fields，也就是printf的格式形式安排。

在msdn中可以搜索Format Specification Fields: printf and wprintf Functions关键字进行查询详细的值。

下面通过实例深入分析

例一：

使用系统的消息资源来报错,这也是这个函数最有用的地方。

#include <windows.h>#include <strsafe.h>void ErrorExit(LPTSTR lpszFunction) {     // Retrieve the system error message for the last-error code    LPVOID lpMsgBuf;    LPVOID lpDisplayBuf;    DWORD dw = GetLastError();     FormatMessage(        FORMAT_MESSAGE_ALLOCATE_BUFFER |         FORMAT_MESSAGE_FROM_SYSTEM |        FORMAT_MESSAGE_IGNORE_INSERTS,        NULL,        dw,        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),        (LPTSTR) &lpMsgBuf,        0, NULL );    // Display the error message and exit the process    lpDisplayBuf = (LPVOID)LocalAlloc(LMEM_ZEROINIT,         (lstrlen((LPCTSTR)lpMsgBuf)+lstrlen((LPCTSTR)lpszFunction)+40)*sizeof(TCHAR));     StringCchPrintf((LPTSTR)lpDisplayBuf,         LocalSize(lpDisplayBuf),        TEXT("%s failed with error %d: %s"),         lpszFunction, dw, lpMsgBuf);     MessageBox(NULL, (LPCTSTR)lpDisplayBuf, TEXT("Error"), MB_OK);     LocalFree(lpMsgBuf);    LocalFree(lpDisplayBuf);    ExitProcess(dw); }void main(){    // Generate an error    if(!GetProcessId(NULL))        ErrorExit(TEXT("GetProcessId"));}

我们可以看到函数选项dwFlags分别为

FORMAT_MESSAGE_ALLOCATE_BUFFER由函数分配输出缓冲区，

FORMAT_MESSAGE_FROM_SYSTEM表示程序将会在系统消息表资源中搜索所需消息，

FORMAT_MESSAGE_IGNORE_INSERTS程序将会忽略搜索到消息中的插入序列。

lpSource值为NULL,因为并没有模块值和字符串直接传入所以为NULL，详细看以上各参数解析。

dwMessageId为dw，即GetLastError的返回值。就是消息资源的ID号。

dwLanguageId 设置为本地默认

lpBuffer 输出缓冲区这里注意& 为什么要&呢？因为 LPVOID lpMsgBuf只是一个指针对象，那么要必须要把它的地址传给lpBuffer参数。这个参数指向地址的所占内存的大小也就是FormatMessage函数执行成功后的返回值。说白了也就是为格式化消息分配一块足够存放的内存空间，然后将lpBuffer指针指向这个地方，此时lpBuffer指向的地方就是一块分配好内存空间的缓冲区，在接下来就供其它函数来使用这个lpBuffer指向的这个内存空间，也就是把格式化消息往这里填。

剩下两个参数可以上面参数的详解。

最后注意一点：由于lpBuffer这个参数的值是FormatMessage函数动态分配的缓冲区，所以在不使用的时候要LocalFree.

LocalAlloc函数是在堆中分配指定的字节数，原型如下：

HLOCAL LocalAlloc(  UINT uFlags,     // allocation attributes  SIZE_T uBytes    // number of bytes to allocate);

其中 uFlags 参数表示怎么分配内存，它的一个参数值 LMEM_ZEROINIT 表示初始化这块内存，并以零填充，它的其它参数请参照MSDN。

如果LocalAlloc 执行成功，则返回一个指向新分配内存对象的句柄。

StringCchPrintf函数表示接收一个待格式化的字符串和一个参数列表，返回一个格式化了的字符串。函数原型如下：

HRESULT StringCchPrintf(

LPTSTR

pszDest,

size_t

cchDest,

LPCTSTR

pszFormat,

……

）;

参数解析：

输出项，pszDest:[out] 指向一个接收格式化了的字符串的指针。这个格式化了的字符串是根据pszFormat 和它的参数创建，以NULL结尾。

ccDest [in], 目标缓冲区大小，这个值必须足够大，以至于能容纳最终格式化了的字符串+1个字符，因为要包括NULL结尾的空字符。最大值充许为STRSAFE_MAX_CCH。

pszFormat [in]指向一个包含打印类型格式字符串的指针，这个字符串必须以NULL结尾。

……

[in] 插入到pszFormat 中的参数。

具体解析 StringCchPrintf((LPTSTR)lpDisplayBuf, LocalSize(lpDisplayBuf), TEXT("%s failed with error %d: %s"), lpszFunction, dw, lpMsgBuf);

这里面：函数将格式化好的字符串输入到lsDisplayBuf指针指向的内存地址中，以后就可以通过lpDisplayBuf这个指针来使用这些内存中的内容了。

LocalSize(lpDisplayBuf)是计算lpDisplayBuf的大小的。TEXT("%s failed with error %d: %s")就是参数pszFormat TEXT(" ")中的内容就是要输入到lpDisplayBuf指向内存中的那个格式化的字符串，这个参数后面的lpszFunction, dw, lpMsgBuf 这三个参数则是 TEXT()中对应的三个参数。

LocalSize 返回局部内存对象所占用内存字节数，函数原型如下：

UINT LocalSize(  HLOCAL  hMem   // handle to local memory object);

例二：

格式化模块中的消息资源，这里加载的模块之中要有消息资源，如果FormatMessage函数中传递了FORMAT_MESSAGE_FROM_SYSTEM，如果消息模块中没有我们所需的资源，那么将会在系统中寻找；如果没有 FORMAT_MESSAGE_FROM_SYSTEM，而且消息模块中没有我们所需资源，函数调用失败。

#include <windows.h>#include <stdio.h>#include <lmerr.h>voidDisplayErrorText(    DWORD dwLastError    );#define RTN_OK 0#define RTN_USAGE 1#define RTN_ERROR 13int__cdeclmain(    int argc,    char *argv[]    ){    if(argc != 2) {        fprintf(stderr,"Usage: %s <error number>\n", argv[0]);        return RTN_USAGE;    }    DisplayErrorText( atoi(argv[1]) );    return RTN_OK;}voidDisplayErrorText(    DWORD dwLastError    ){    HMODULE hModule = NULL; // default to system source    LPSTR MessageBuffer;    DWORD dwBufferLength;    DWORD dwFormatFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER |        FORMAT_MESSAGE_IGNORE_INSERTS |        FORMAT_MESSAGE_FROM_SYSTEM ;    //    // If dwLastError is in the network range,     //  load the message source.    //    if(dwLastError >= NERR_BASE && dwLastError <= MAX_NERR) {        hModule = LoadLibraryEx(            TEXT("netmsg.dll"),            NULL,            LOAD_LIBRARY_AS_DATAFILE            );        if(hModule != NULL)            dwFormatFlags |= FORMAT_MESSAGE_FROM_HMODULE;    }    //    // Call FormatMessage() to allow for message     //  text to be acquired from the system     //  or from the supplied module handle.    //    if(dwBufferLength = FormatMessageA(        dwFormatFlags,        hModule, // module to get message from (NULL == system)        dwLastError,        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // default language        (LPSTR) &MessageBuffer,        0,        NULL        ))    {        DWORD dwBytesWritten;        //        // Output message string on stderr.        //        WriteFile(            GetStdHandle(STD_ERROR_HANDLE),            MessageBuffer,            dwBufferLength,            &dwBytesWritten,            NULL            );        //        // Free the buffer allocated by the system.        //        LocalFree(MessageBuffer);    }    //    // If we loaded a message source, unload it.    //    if(hModule != NULL)        FreeLibrary(hModule);}

之前两个例子都是经常使用的，那么FormatMessage之中还有个参数我们没有用过的，Arguments，那么我们在什么情况下使用呢？

我们前面已经详细解释了各个参数详细意义。我们先来看msdn两个有关使用这个值的例子：

#ifndef UNICODE#define UNICODE#endif#include <windows.h>#include <stdio.h>void main(void){    LPWSTR pMessage = L"%1!*.*s! %4 %5!*s!";    DWORD_PTR pArgs[] = { (DWORD_PTR)4, (DWORD_PTR)2, (DWORD_PTR)L"Bill",  // %1!*.*s! refers back to the first insertion string in pMessage         (DWORD_PTR)L"Bob",                                                // %4 refers back to the second insertion string in pMessage         (DWORD_PTR)6, (DWORD_PTR)L"Bill" };                               // %5!*s! refers back to the third insertion string in pMessage    const DWORD size = 100+1;    WCHAR buffer[size];    if (!FormatMessage(FORMAT_MESSAGE_FROM_STRING | FORMAT_MESSAGE_ARGUMENT_ARRAY,                       pMessage,                        0,                       0,                       buffer,                        size,                        (va_list*)pArgs))    {        wprintf(L"Format message failed with 0x%x\n", GetLastError());        return;    }    // Buffer contains "  Bi Bob   Bill".    wprintf(L"Formatted message: %s\n", buffer);}

根据msdn中对Arguments参数的解释，这里插入序列遵循%n[!format_specifier!]

这个格式，如果format_specifer不清楚可以查阅printf输出格式。

LPWSTR pMessage = L"%1!*.*s! %4 %5!*s!";

的意义如下：

%1!*.*s! 表示为 %1取数组第一个位置的字符串的值，

!*.*s! 就是[!format_specfier!]的内容，所以我们就想知道 *.*s含义，

根据printf输出格式我们可以知道第一个星号* 表示输出宽度，点号（.）表示下面一个星号是输出精度。

故我们可以看到数组pArgs前面3个值，4 ，2，Bill 。4为要格式的宽度，2为要格式的精度，Bill为要格式的字符串。

%4 取数组第四个值的字符串，它没有format_specifier 所以按默认输出宽度和精度。

%5!*s! 表示输出的是取数组第五个值的字符串，宽度为6。

msdn还提供了一个使用va_list类型的例子：

#ifndef UNICODE#define UNICODE#endif#include <windows.h>#include <stdio.h>LPWSTR GetFormattedMessage(LPWSTR pMessage, );void main(void){    LPWSTR pBuffer = NULL;    LPWSTR pMessage = L"%1!*.*s! %3 %4!*s!";    // The variable length arguments correspond directly to the format    // strings in pMessage.    pBuffer = GetFormattedMessage(pMessage, 4, 2, L"Bill", L"Bob", 6, L"Bill");    if (pBuffer)    {        // Buffer contains "  Bi Bob   Bill".        wprintf(L"Formatted message: %s\n", pBuffer);        LocalFree(pBuffer);    }    else    {        wprintf(L"Format message failed with 0x%x\n", GetLastError());    }}// Formats a message string using the specified message and variable// list of arguments.LPWSTR GetFormattedMessage(LPWSTR pMessage, ){    LPWSTR pBuffer = NULL;    va_list args = NULL;    va_start(args, pMessage);    FormatMessage(FORMAT_MESSAGE_FROM_STRING |                  FORMAT_MESSAGE_ALLOCATE_BUFFER,                  pMessage,                   0,                  0,                  (LPWSTR)&pBuffer,                   0,                   &args);    va_end(args);    return pBuffer;}

那么我们已经看完了所有的使用方法了，但是可能我们还会想Argument到底有什么用按照以上所述。

在消息资源的消息文本中我们可能会使用插入序列，让消息文本显示更加灵活。

比如我们在消息资源中的一个消息里面定义一个消息文本内容如下：

%1!*.*s! %4 %5!*s!

那么我们在调用消息模块的时候代码如下：

DWORD_PTR pArgs[] = { (DWORD_PTR)4, (DWORD_PTR)2, (DWORD_PTR)L"Bill",  // %1!*.*s! refers back to the first insertion string in pMessage             (DWORD_PTR)L"Bob",                                                // %4 refers back to the second insertion string in pMessage             (DWORD_PTR)6, (DWORD_PTR)L"Bill" };                               // %5!*s! refers back to the third insertion string in pMessage         if (hDll != NULL) {            fOk = FormatMessage(               FORMAT_MESSAGE_FROM_HMODULE | FORMAT_MESSAGE_ARGUMENT_ARRAY |               FORMAT_MESSAGE_ALLOCATE_BUFFER,               hDll, dwError, systemLocale,               (PTSTR) &hlocal, 0, (va_list*)pArgs);            FreeLibrary(hDll);         }      }

pArg数组为我们程序想插入的序列，这样消息模块可以让你的程序更加便捷的表达你所想输出的消息的意义！

参考：http://www.cppblog.com/koople/archive/2009/12/03/102367.aspx