【WIN32之旅】WINDOWS错误处理与参考(三)

转载请说明原出处，谢谢~ http://blog.csdn.net/seven_1992/article/details/44487785

    在WINDOWS编程中，我们在所难免会与“错误”打交道，但令我们“找不着北”的是，我们不知道是什么错误（What's Error?），亦或者是系统给出了错误代码(Error Code)，而我们却郁闷着怎么没有详细的错误信息（Error Information），这样一个错误代码到底要表达什么意思（What's mean?）。 接下来要登场的就是几个与错误信息有关的系统API函数了，关于错误信息的处理与参考，下面就让我们来看看这几个函数吧。

一、 设置和获取错误代码

   当我们在代码运行的过程中，发生了错误，要获取或者设置错误信息，我们就要用到两个与此相关的函数 GetLastError()与SetLastError(),可以看出，这是一对兄弟函数(Sibling Function），函数的命名总是这样，Get函数与Set函数总是成对出现，其实在我们平时与代码打交道的日子里算是家常了，关于这两个函数我们接下来就先来了解一下吧。

1、GetLastError()函数：

DWORD WINAPI GetLastError(void); // 获取最后一次错误代码

    这是MSDN上函数的原型，返回值为DWORD(双字型)，函数调用约定为宏WINAPI(即__stdcall标准调用),输入参数为void(空参数型)，MSDN上对该函数的解释是：获取该调用线程的最后一次错误错代码，该错误代码是基于线程的，多线程中各自线程的错误代码是独立而不相互覆盖的（简而言之，错误代码是线程级别拥有的，你使用该函数获取到的错误代码是该线程的）。

2、SetLastError()函数：

void WINAPI SetLastError(_In_ DWORD dwErrCode);  // 设置错误代码

    顾名思义，这个函数的作用也就是设置最后一次出错代码（Last-error Code），其实理解了它的兄弟函数GetLastError()的，我想对于这个函数的理解和运用也就不是那么难了。（同样，该函数设置的错误代码也是线程级别的）

    对于SetLastError()函数，同样有着一个扩展函数（Extension Function）：

void WINAPI SetLastErrorEx(
  _In_  DWORD dwErrCode,
  _In_  DWORD dwType
);

    MSDN目前给出的解释是：目前，由于第二个参数暂时被忽略，该函数等同于SetLastError()。

PS. 关于错误代码（Error Code），MSDN上还有这样一段注释：

    错误代码是一个32位值，最高位也就是第31位是最重要的一位。第29位是专门用来给应用程序定义错误的（非系统错误该位必须设置），如果你要给应用程序定义错误，请设置此位为1，以表明该错误代码是由应用程序定义的。你需要保证你定义的错误代码不与系统定义的错误代码相冲突。

    

二、 格式化错误信息

    当然我们会说，GetLastError()与SetLastError()两个函数也就是设置和获取错误代码，而既然是代码，我怎么知道这代码要表达的是什么意思？没关系，接下来要登场的就是我们的FormatMessage()函数：

    DWORD WINAPI FormatMessage(     // 返回值DWORD是消息格式化后的长度
    _In_      DWORD dwFlags,        // 格式化选项标志，以及说明如何解释lpSource
    _In_opt_  LPCVOID lpSource,     // 格式化消息串的源（由dwFlags选项决定）
    _In_      DWORD dwMessageId,    // 消息标识ID（如果dwFlags包含了FORMAT_MESSAGE_FROM_STRING该参数将被忽略）
    _In_      DWORD dwLanguageId,   // 语言标识ID（如果dwFlags包含了FORMAT_MESSAGE_FROM_STRING该参数将被忽略）
    _Out_     LPTSTR lpBuffer,      // 缓冲区指针
    _In_      DWORD nSize,          // 分配给消息串缓冲区的最小长度（最大长度为128K，超过将使用GetLastError()将返回ERROR_MORE_DATA）
    _In_opt_  va_list *Arguments    // 用于格式化消息串的变长参数表
    );

    关于FormatMessage()函数，MSDN对其的解释是:

    格式化输出一个消息串。该函数输出的消息串由一个消息定义指明，该消息串可以来自于传入的缓冲区指针所指向的格式化字符串（即lpSource为一个格式化字符串指针，参数来自于可变参数表Arguments），也可以来自于已加载资源模块中的消息表（即lpSource为一个模块的句柄），或是来自于系统资源中已定义的消息表（此时lpSource为NULL空），而这都取决于格式化选项。该函数基于消息标识（dwMessageId）和语言标识（dwLanguageId）在消息资源表(Message Tabel Resource)中查找对应的消息定义，该函数会将格式化的消息传拷贝到一个输出缓冲区中（该输出缓冲区的指针由lpBuffer指针传出）。

   关于dwFlags参数的标识（从上面的解释可以看出它的指导作用）：

值	含义
FORMAT_MESSAGE_ALLOCATE_BUFFER 0x00000100	函数会分配足够的空间给格式化消息串（nSize参数指定分配的输出缓冲区的最小长度），并通过lpBuffer指向该地址（必须转化为LPTSTR ，即(LPTSTR)&lpBuffer，用完后必须使用LocalFree函数释放分配的空间）
FORMAT_MESSAGE_ARGUMENT_ARRAY 0x00002000	格式化消息串的Arguments参数不是指向va_list结构体，而是一个指向保存参数的数组指针（如果参数中含有64位整型，则必须使用va_list结构体传递参数）
FORMAT_MESSAGE_FROM_HMODULE 0x00000800	格式化消息串来自于一个已加载的模块，当lpSource为NULL时则为当前进程模块句柄（该标志不能与FORMAT_MESSAGE_FROM_STRING标志同时使用）
FORMAT_MESSAGE_FROM_STRING 0x00000400	格式化消息串来自于一个格式化字符串（该标志不能与 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 0x00000200	格式化消息串中的插入序列会被忽略并直接传递到输出缓冲区（这个参数对于消息后置格式化是十分有用的，如果该标志设置则参数表Arguments将被忽略）

    dwFlags参数可以是以上参数之一或者是它们的组合（使用或|运算符），dwFlags的低位值指定了函数如何处理输出缓冲区处理行转换，也可以指定格式化输出字符串输出行的最大宽度，关于地位值的设置，我们可以使用以下标识来进行：

Value	Meaning
0	表示无输出最大宽度限制。
FORMAT_MESSAGE_MAX_WIDTH_MASK 0x000000FF	表示有最大输出宽度限制（使用硬编码设置）。

    关于Arguments参数（从上面的解释可以知道其是插入值的传入口）：

   Arguments有两种类型，由FORMAT_MESSAGE_ARGUMENT_ARRAY决定，带有此标识标识其为数组，则格式化字符串中使用%n作为插入符(即%n代表数组中第n个参数)，若未指定此标志，则使用类似prinf()中的格式化插入符（如%d,%s，%c等）插入。

既然说到了FormatMessage()函数，接下来就列出几个使用列子给大家：

例子一（关于Arguments参数数组、宽度与精度的使用示例）：

#ifndef UNICODE
#define UNICODE
#endif

#include 
#include 

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

    // 字符串缓存包含了字符串"  Bi Bob   Bill".
    wprintf(L"Formatted message: %s\n", buffer);
}

例子二（关于Arguments变长参数表的使用示例）：

#ifndef UNICODE
#define UNICODE
#endif

#include 
#include 

LPWSTR GetFormattedMessage(LPWSTR pMessage, ...);

void main(void)
{
    LPWSTR pBuffer = NULL;
    LPWSTR pMessage = L"%1!*.*s! %3 %4!*s!";

    // 变长参数直接对应的到格式化字符串pMessage中相应格式插入符位置
    pBuffer = GetFormattedMessage(pMessage, 4, 2, L"Bill", L"Bob", 6, L"Bill");
    if (pBuffer)
    {
        // 字符串缓存包含了字串"  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;
}

例子三（关于格式化系统错误信息的使用示例）：

TCHAR* GetLastErrorText(DWORD nErrorCode)
{
    TCHAR* pMsgBuff;
    // 使用FormatMessage()获取WINDOWS系统标准的错误信息
    FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
                  NULL,
                  nErrorCode,
                  MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
                  (LPTSTR)&pMsgBuff,
                  0,
                  NULL);
    // 返回格式化好的错误信息字符串
    if (!pMsgBuff)
        return("未知错误!");
    else
        return(pMsgBuff);
    // 注意：当不再使用pMsgBuff时使用LocalFree()释放掉系统分配的内存
}

    PS.我们使用一个函数要清楚地了解它的定义（包括每一个符号代表的含义），这样我们才能更好地理解和运用它，而这最好的途径也就是查阅MSDN，因为语言间的含义还是有细微的差别的，而我建议最好能从英文的角度理解好它，这样不仅有助于更好地理解它，也能帮助我们提升英文水平，不是吗？

 

 

上一篇，《WINDOWS错误处理与参考（二)》...

下一篇，我将继续补充《WINDOWS错误处理与参考（四)》...

欢迎评论和转载，转载请注明文章出处，我对此表示最真诚的敬意！