《Windows核心编程》のWindows返回值
当调用一个Windows函数时，它首先检验传递给它的各个参数的有效性，然后再设法执行任务。如果传递了一个无效参数，或者由于某种原因无法执行这项操作，那么操作系统就会返回一个值，指明该函数在某种程度上运行失败了。
下面说说Windows常见的返回值类型：
1） VOID：表明该函数运行不可能失败，Windows函数的返回值很少是VOID。
2） BOOL：如果函数运行失败，返回值是0，否则返回值是非0值。最好对返回值进行测试，以确定它是0还是非0，而不是测试返回值是否是TRUE。
3） HANDLE：如果函数运行失败，则返回值通常是NULL，否则返回值是某个HANDLE，用于标识你可以操作的一个对象。F.Y.I，有些函数失败时会返回一个句柄值INVALID_HANDLE_VALUE，它被定义为-1。函数的Platform SDK文档将会清楚地说明函数运行失败时返回值是NULL还是INVALID_HANDLE_VALUE。
4） PVOID：如果函数运行失败，返回值是NULL，否则返回PVOID，以标识数据块的内存地址。
5） LONG/DWORD：这是个难以处理的值。返回数量的函数通常返回LONG或DWORD，如果由于某种原因，函数无法对想要进行计数的对象进行计数，那么该函数通常返回0或-1（根据函数而定）。如果调用的函数返回值为LONG或DWORD，那么得阅读Platform SDK以确保能正确检测潜在的错误。
一个Windows函数返回的错误代码对了解函数运行失败的原因是很有用的。Microsoft编译了一个所有可能的错误代码的列表，并且为每个错误代码分配了一个32位的号码。若要确定这是个什么错误，可以调用GetLastError函数：
DWORD GetLastError();
该函数只返回线程的32位错误代码，我们需要将它转换成更便于理解的某种东西。在WinError.h头文件中包含了Microsoft定义的错误代码的列表。格式如下：
// DNS_INFO_NO_RECORDS 0x0000251d
//
// MessageId: DNS_INFO_NO_RECORDS
//
// MessageText:
//
// No records found for given DNS query.
//
#define DNS_INFO_NO_RECORDS 9501L //(0x0000251d的十进制值)
我们可以看到，每个错误有三种表示法：一个消息ID（这是我们可以在源代码中使用的一个宏，以便于与GetLastError的返回值进行比较）、消息文本（对错误的英文描述）和一个号码（应该避免直接使用该号码，而是使用消息ID）
当Windows函数运行失败时，应该立即调用GetLastError函数。因为如果调用另一个Windows函数，GetLastError的返回值很可能被改写。
如果在编写的应用程序中发现一个错误，可能需要向用户显示该错误的文本描述。Windows提供了一个函数，可以将错误代码转换成它的文本描述。该函数就是FormatMessage：
DWORD FormatMessage(
__in DWORD dwFlags, // source and processing options
__in_opt LPCVOID lpSource, // pointer to message source
__in DWORD dwMessageId, // requested message identifier
__in DWORD dwLanguageId, // language identifier for requested message
__out LPTSTR lpBuffer, // pointer to message buffer
__in DWORD nSize, // maximum size of message buffer
__in_opt va_list *Arguments // pointer to array of message inserts
);
FormatMessage函数的功能是非常丰富的，在创建向用户显示的字符串信息时，它是首选函数。原因之一是它很容易用多种语言进行操作，该函数能够检测出用户首选地语言，并返回相应的文本。
下面是FormatMessage的实例代码：
#include <windows.h>
#include <lmerr.h>
#include <tchar.h>
#define ERRMSGBUFFERSIZE 256
void fnDisplayError( DWORD dwErrorMsgId )
{
DWORD ret; // Temp space to hold a return value.
HINSTANCE hInst; // Instance handle for DLL.
HLOCAL pBuffer; // Buffer to hold the textual error description.
if ( HRESULT_FACILITY(dwErrorMsgId) == FACILITY_MSMQ )
{
// MSMQ errors only (see winerror.h for facility info).
// Load the MSMQ library containing the error message strings.
hInst = LoadLibrary( TEXT("MQUTIL.DLL") );
if(hInst != 0)
{
// hInst not NULL if the library was successfully loaded.
// Get the text string for a message definition
ret = FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER | // Function will handle memory allocation.
FORMAT_MESSAGE_FROM_HMODULE | // Using a module's message table.
FORMAT_MESSAGE_IGNORE_INSERTS,
hInst, // Handle to the DLL.
dwErrorMsgId, // Message identifier.
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language.
(LPTSTR)&pBuffer, // Buffer that will hold the text string.
ERRMSGBUFFERSIZE, // Allocate at least this many chars for pBuffer.
NULL // No insert values.
);
} // hInst not NULL if the library was successfully loaded.
} // MSMQ errors only.
else if ( dwErrorMsgId >= NERR_BASE && dwErrorMsgId <= MAX_NERR )
{
// Could be a network error.
// Load the library containing network messages.
hInst = LoadLibrary( TEXT("NETMSG.DLL") );
if(hInst != 0)
{
// Not NULL if successfully loaded.
// Get a text string for the message definition.
ret = FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER | // The function will allocate memory for the message.
FORMAT_MESSAGE_FROM_HMODULE | // Message definition is in a module.
FORMAT_MESSAGE_IGNORE_INSERTS, // No inserts used.
hInst, // Handle to the module containing the definition.
dwErrorMsgId, // Message identifier.
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language.
(LPTSTR)&pBuffer, // Buffer to hold the text string.
ERRMSGBUFFERSIZE, // Smallest size that will be allocated for pBuffer.
NULL // No inserts.
);
} // Not NULL if successfully loaded.
} // Could be a network error.
else
{
// Unknown message source.
// Get the message string from the system.
ret = FormatMessage(
FORMAT_MESSAGE_ALLOCATE_BUFFER | // The function will allocate space for pBuffer.
FORMAT_MESSAGE_FROM_SYSTEM | // System wide message.
FORMAT_MESSAGE_IGNORE_INSERTS, // No inserts.
NULL, // Message is not in a module.
dwErrorMsgId, // Message identifier.
MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language.
(LPTSTR)&pBuffer, // Buffer to hold the text string.
ERRMSGBUFFERSIZE, // The function will allocate at least this much for pBuffer.
NULL // No inserts.
);
}
// Display the string.
if( ret )
{
_tprintf( _TEXT("/tERRORMESSAGE: %s/n"), (LPTSTR)pBuffer );
}
else
{
_tprintf( _TEXT("/tERRORNUMBER: %d/n"), dwErrorMsgId );
}
// Free the buffer.
LocalFree( pBuffer );
}
我们如何利用该机制来定义自己函数返回的错误代码呢？若要指明函数运行失败，只需要设定线程的最后的错误代码，然后让我们的函数返回FALSE、INVALID_HANDLE_VALUE、NULL或返回任何合适的信息。设定线程的最后错误代码只需调用下面代码：
VOID SetLastError(DWORD dwErrCode);
可以将合适的任何32位号码传递给该函数，包括WinError.h中已经存在的代码，只要该代码能够正确指明想要报告的错误即可。我们也可以创建自己的错误代码。错误代码是一个32位的数字，格式如下表：
| 位 |
31~30 |
29 |
28 |
27~16 |
15~0 |
| 内容 含义 |
严重性 0=成功 1=供参考 2=警告 3=错误 |
0=Microsoft定义的代码
1=客户定义的代码 |
保留 必须是0 |
设备代码 由Microsoft定义 |
异常代码 由Microsoft或用户定义 |