FormatMessage函数的用法
FormatMessage函数
原文：http://www.cppblog.com/koople/archive/2009/12/03/102367.aspx
在《windows核心编程》中第一个示例便是它的使用。
这个函数我用了几次之后终于明白它的用法；
这个函数是用来格式化消息字符串，就是处理消息资源的。消息资源是由mc.exe编译的，详细请在msdn中搜索mc.exe。
先来看下它的函数原型
DWORD WINAPI FormatMessage(
__in DWORD dwFlags,
__in LPCVOID lpSource,
__in DWORD dwMessageId,
__in DWORD dwLanguageId,
__out LPTSTR lpBuffer,
__in DWORD nSize,
__in va_list* Arguments
);
在使用这个函数的时候要明确以下几点
你要处理的消息资源来自哪里，这一点尤为重要。
你的消息ID来自哪里.
以下是每个参数的详细介绍：
dwFlags :
格式化选项，对lpSource参数值有指导作用。
dwFlags的低位值指定了函数如何处理输出缓冲区处理行转换，也可以指定格式化输出字符串输出行的最大宽度。它的位标示符如下：
| Value |
Meaning |
| FORMAT_MESSAGE_ALLOCATE_BUFFER |
lpBuffer参数是一个PVOID指针，nSize参数指定按TCHARs为单位的分配给输出消息缓冲区的最小值。当你不适用这个缓冲区的时候也就是lpBuffer的时候需要用LocalFree将其释放
|
| FORMAT_MESSAGE_ARGUMENT_ARRAY |
Arguments参数不是一个va_list结构，但是它表示一个数组指针。这个标识符不能在64位整数值时使用，你如果要使用64位整数值，那么你必须使用va_list结构体
|
| FORMAT_MESSAGE_FROM_HMODULE |
lpSource参数是一个包含了消息表资源（Message-table resources）模块（dll）句柄。如果lpSource句柄为NULL，系统会自动搜索当前进程文件的消息资源。 这个标示符不可以和FORMAT_MESSAGE_FROM_STRING共用。 如果模块中没有资源表，这个函数执行失败并且返回ERROR_RESOURCE_TYPE_NOT_FOUND错误值。
|
| FORMAT_MESSAGE_FROM_STRING |
lpSource参数指向一个包含了消息定义的字符串.这个消息定义里面可能包含了插入序列（insert sequence），像消息表资源中包含消息文本一样.和这个标示符不和FORMAT_MESSAGE_FROM_HMODULE或者FORMAT_MESSAGE_FROM_SYSTEM一起使用.
|
| FORMAT_MESSAGE_FROM_SYSTEM |
函数将会搜索系统消息表资源来寻找所需消息资源。如果这个标示符同时定义了FORMAT_MESSAGE_FROM_HMODULE,那么如果函数在模块中没有搜索到所需消息的话将会在系统中搜索。这个标示符不能和FORMAT_MESSAGE_FROM_STRING一起使用. 当这个标示符设置的时候，可以使用GetLastError函数返回值来搜索这个错误码在系统定义错误中相应的消息文本。
|
| FORMAT_MESSAGE_IGNORE_INSERTS |
在消息定义中的插入序列将会被忽略，这个标示符在获取一个格式化好的消息十分有用，如果这个标示符设置好了，那么Arguments参数将被忽略。
|
开始在上面说了dwflags参数低位值作用，你可以使用以下值来设置低位值。
| Value |
Meaning |
| 0 |
将不会有输出行宽度限制。
|
| FORMAT_MESSAGE_MAX_WIDTH_MASK |
将会有限制输出行宽度，使用硬编码设定。
|
lpSource：
这个值是消息表资源来自哪里，这个值依靠dwFlags,详细请看FORMAT_MESSAGE_FROM_HMODULE和FORMAT_MESSAGE_FROM_STRING，如果这两个标示符都没设置，那么lpSource将会被忽略。
dwMessageId ：
所需格式化消息的标识符。当dwFlags设置了FORMAT_MESSAGE_FROM_STRING，这个参数将会被忽略。
dwLanguageId：
格式化消息语言标识符。
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关键字进行查询详细的值。
看完以上详细参数的解释其实我自己还没太明白如何用。msdn中的几个例子可以让人豁然开朗。
例一：
使用系统的消息资源来报错,这也是这个函数最有用的地方。
- #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"));
- }
#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参数。
剩下两个参数可以上面参数的详解。
最后注意一点：由于lpBuffer这个参数的值是FormatMessage函数动态分配的缓冲区，所以在不使用的时候要LocalFree.
例二：
格式化模块中的消息资源，这里加载的模块之中要有消息资源，如果FormatMessage函数中传递了FORMAT_MESSAGE_FROM_SYSTEM，如果消息模块中没有我们所需的资源，那么将会在系统中寻找；如果没有 FORMAT_MESSAGE_FROM_SYSTEM，而且消息模块中没有我们所需资源，函数调用失败。
- #include <windows.h>
- #include <stdio.h>
- #include <lmerr.h>
- void
- DisplayErrorText(
- DWORD dwLastError
- );
- #define RTN_OK 0
- #define RTN_USAGE 1
- #define RTN_ERROR 13
- int
- __cdecl
- main(
- 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;
- }
- void
- DisplayErrorText(
- 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);
- }
#include <windows.h>
#include <stdio.h>
#include <lmerr.h>
void
DisplayErrorText(
DWORD dwLastError
);
#define RTN_OK 0
#define RTN_USAGE 1
#define RTN_ERROR 13
int
__cdecl
main(
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;
}
void
DisplayErrorText(
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);
- }
#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;
- }
#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);
- }
- }
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);
}
}
原文：http://www.cppblog.com/koople/archive/2009/12/03/102367.aspx