FormatMessage函數
在《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 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：
格式化消息語言辨別符。
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"));
}
我們可以看到函數選項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);
}
之前兩個例子都是經常使用的，那麼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);
}
}
原文：http://www.cppblog.com/koople/archive/2009/12/03/102367.aspx
![淺談---測試Native Windows Command與Native PowerShell Command哪個效率高[圖]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)