反饋

FormatMessage

FormatMessage是一個Windows API函數。它的功能就是將GetLastError函數得到的錯誤信息（這個錯誤信息是數字代號）轉化成字符串信息的函數。

外文名: FormatMessage
含義: Windows API函數

功能: GetLastError的返回值換成字符串
可選參數: dwFlags

FormatMessage語法

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
                            );

^[1]

FormatMessage參數

dwFlags

標誌位，決定如何説明lpSource參數，dwFlags的低位指定如何處理換行功能在輸出緩衝區，也決定最大寬度的格式化輸出行。^[1]

可選參數：

標誌	標誌説明
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標誌而定。^[1]

dwMessageId

請求的消息的標識符。當dwFlags標誌為FORMAT_MESSAGE_FROM_STRING時會被忽略。^[1]

dwLanguageId

請求的消息的語言標識符。

LPTSTR lpBuffer

接收錯誤信息描述的緩衝區指針。

nSize

如果FORMAT_MESSAGE_ALLOCATE_BUFFER標誌沒有被指定，這個參數必須指定為輸出緩衝區的大小，如果指定值為0，這個參數指定為分配給輸出緩衝區的最小數。^[1]

Arguments

保存格式化信息中的插入值的一個數組。

FormatMessage返回值

如果函數調用成功，返回輸出緩衝區的大小，除最後一個空字符。如果失敗則返回0。^[1]

FormatMessage舉例

// 系統錯誤信息提示。
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): 拒絕訪問。

FormatMessage需求

客户端	需要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)的形式實現。

參考資料

1. FormatMessage ．msdn．2010-04-08[引用日期2012-010-8]

詞條統計

瀏覽次數：次
編輯次數：20次歷史版本
最近更新：双鱼雨后彩虹12 （2022-01-09）

1 語法
2 參數
3 返回值
4 舉例
5 需求