Skip to content

20171117.md

Latest commit

 

History

History
228 lines (103 loc) · 5.1 KB

20171117.md

File metadata and controls

228 lines (103 loc) · 5.1 KB

注册表编程很感兴趣

已下载boost

已下载notepad++

已下载ultraedit

已下载mingw

FormatMessage 函数

格式化一个字符串。这个函数需要一个消息定义作为输入。

这个消息定义可以来自传递给此函数的一个缓存。

这个消息定义也可以来自在已经加载的模块中的一个消息表资源。

或者调用者可以让这个函数为这个消息定义去搜索系统的消息表资源。

该函数在一个基于（一个消息标识符和一个语言标识符）的消息表资源中查找消息定义。

该函数将格式化后的消息文本到一个输出缓存中。

如果有要求，这个缓存可以处理任何嵌入的插入序列。

语法：

DWORD WINAPI FormatMessage
(
_In_      DWORD     dwFlags,
_In_opt_  LPCVOID   lpSource,
_In_      DWORD     dwMessageId,
_In_      DWORD     dwLanguageId,
_Out_     LPTSTR    lpBuffer,
_In_      DWORD     nSize,
_In_opt_  va_list   *Arguments
);

参数说明

  • dwFlags (in)

    格式化选项，用于表示如何解释lpSource参数。

    dwFlags的低位字节指定了函数是如何处理在输出缓存中的换行机制。

    dwFlags的低位字节也可以指定一个格式化输出行的最大宽度。

    这个参数可以为以下值中的一个或多个。

    FORMAT_MESSAGE_ALLOCATE_BUFFER (0x00000100)

    该函数分配了一个足够大的缓存来承载格式化后的消息，并且在lpBuffer参数

    指定的地址放置了一个指针来指向这块缓存。

    lpBuffer参数是一个指向LPTSTR的指针；

    你必须将该指针转为LPTSTR（例如（LPSTR）&lpBuffer）。

    nSize参数指定了为一个输出消息缓存分配的TCHAR的最小个数。

    当该lpBuffer指针不再使用时，调用者应该使用LocalFree函数去释放这个指针。

    如果格式化后的消息的长度超过128K字节，那么FormatMessage函数将会失败，

    然后如果你调用GetLastError，将会得到ERROR_MORE_DATA错误码。

    FORMAT_MESSAGE_FROM_SYSTEM 0x00001000

    该函数应该为该请求消息而搜索系统消息表资源。如果该标志与FORMAT_MESSAGE_FROM_HMODULE

    标志一起指定，如果消息没有在lpSource中指定的模块中找到，那么函数搜索系统消息表。

    该标志不能与FORMAT_MESSAGE_FROM_STRING一起指定。

    如果该标志被指定，一个应用程序可以将GetLastError函数的结果传递给该函数，

    去获取系统自定义的错误的消息文本。

    dwFlags的低字节可以指定格式化输出行的最大长度，下面是低自己可能的值

    0 表示输出行没有宽度限制。该函数把消息定义文本中的换行符存储到输出缓存中。

    FORMAT_MESSAGE_MAX_WIDTH_MASK 0x000000FF

    该函数忽略在消息定义文本的规则的换行符。该函数将消息定义文本中的硬编码换行符到输出缓存中。

    该函数不产生新的换行符。

  • lpSource (in optional)

    消息定义的位置。

    这个参数的类型取决于dwFlags参数的设置。

    当dwFlags不是FORMAT_MESSAGE_FROM_HMODULE或者FORMAT_MESSAGE_FROM_STRING中的一个的话，这个参数无效。

  • dwLanguageid (in)

    请求消息的语言表示服。如果dwFlags包含FORMAT_MESSAGE_FROM_STRING，那么这个参数无效。

    如果你赋值为0，那么将使用系统的默认语言。

  • lpBuffer (out)

    指向接收一个指定格式化后消息的以0结尾的字符串的指针。

    如果dwFlags包含FORMAT_MESSAGE_ALLOCATE_BUFFER，该函数使用LocalAlloc分配一个缓存，

    并且将该指针放置在一个指向在lpBuffer指定的地址的缓存。

    这个缓存不能超过64K字节

  • nSize (in)

    如果FORMAT_MESSAGE_ALLOCATE_BUFFER不指定，那么该参数表示用户分配的lpBuffer的大小。

    如果FORMAT_MESSAGE_ALLOCATE_BUFFER已指定，那么该参数表示系统至少分配的lpBuffer的大小。

  • Arguments (int, opt)

    暂不考虑该参数

返回值

如果该函数成功，返回值表示存储在输出缓存中的字节大小，这个大小去除了结尾的空字符。

如果该函数返回0，表示失败。调用GetLastError获取错误原因。

代码示例：

// 系统错误信息提示。
void TestErrorInfo(void)
{
    //进行出错。
    if (!CreateDirectory(_TEXT("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,
            _TEXT("%s 出错信息 (出错码=%d): %s"),
            _TEXT("CreateDirectory"), dw, lpMsgBuf);
        LocalFree(lpMsgBuf);
        //输出提示。
        OutputDebugString(szBuf);
    }
    
    // alternative
    // FILE * pFile = fopen("asdfadf", "rb");
    // char strFormat[1024] = {0};
    // int n = FormatMessage (FORMAT_MESSAGE_FROM_SYSTEM, 0, GetLastError(), 0, strFormat, 1024, 0);

}