C++零食：HRESULT 與 Windows Error Codes 不是一回事

文章目錄

• SUCCEEDED
• HRESULT
• 常見HRESULT值
• Windows Error Code
• Windows Error Codes
• 常見的Windows Error Codes
• 參考資料

在用C++來開發Windows程式時，經常看到下面的判斷情況：

HRESULT hr = ::RegCreateKeyEx(hk, szKeyPath, 0, NULL, REG_OPTION_NON_VOLATILE, KEY_QUERY_VALUE, NULL, &hk, NULL);if (SUCCEEDED(hr)) {

在代碼中，使用SUCCEEDED宏來判斷函數RegCreateKeyEx()函數的傳回值。

有些程式員認為RegCreateKeyEx返回0的時候就是成功，而S_OK就是0，所以就習慣性的用SUCCEEDED宏來做判斷。

還有些人用下面的方法判斷，看起來更嚴謹一些：

HRESULT hr = ::RegCreateKeyEx(hk, szKeyPath, 0, NULL, REG_OPTION_NON_VOLATILE, KEY_QUERY_VALUE, NULL, &hk, NULL);if (S_OK == hr) {

確實，第2種更嚴謹一些，至少不會造成大問題，而第1中則完全是一個大Bug，這個bug在正常情況下是沒有問題的。但一旦有問題，你也發現不了。

錯在哪裡呢？聽我下面來介紹。

 

SUCCEEDED

先看下這個宏的定義（WinError.h)：

//// Generic test for success on any status value (non-negative numbers// indicate success).//#define SUCCEEDED(hr) ((HRESULT)(hr) >= 0)

從這裡可以看出，它就是把hr轉換成HRESULT類型，然後做了下是否大於0的判斷。注釋中也說明：但值為非負數時表示成功。

也就是說，只要HRESULT是大於等於0的值，它就認為是成功的。

 

HRESULT

再來看下HRESULT的定義(winnt.h)：

// Component Object Model defines, and macros#ifndef _HRESULT_DEFINED#define _HRESULT_DEFINEDtypedef LONG HRESULT;#endif // !_HRESULT_DEFINED

哦，原來HRESULT就是一個Long型的整數。

在MSDN中，可以查到更加詳細的資料：

如，HRESULT是一個4位元組的Long型，總共32位。其中：

第31位是s位，即符號位，因為HRESUlT格式規定所有成功都是正的整數，失敗的值都是負數

第30位是r位，是保留位，但n位（28位）沒有設定時，它必須是0；如果n位使用了，則和s位一起來標識NTSTATUS的值。

第29位是c位，表示Custom，即自訂位，如果是微軟定義的傳回值，則該位為0；如果是自訂的，則該位為1.

第28位是n位，表示NTSTATUS，值為0的話可以把NTSTATUS值對應為一個HRESULT值。

第27位是x位，保留位，必須為0.

第26位到第16位是Facility，用11位來表示錯誤來源，比如

FACILITY_WINDOWS 表示來自Windows子系統

第15位到第1位是Code位，用來儲存錯誤值。

 

從這裡可以看出，只有最後面的2個位元組是用來表示傳回值的其它的都是輔助資訊，它主要用於COM函數的傳回值。

 

常見HRESULT值

Name	Description	Value
S_OK	操作成功	0x00000000
S_FALSE	操作成功，但是有問題	0x00000001L
E_ABORT	操作中止	0x80004004
E_ACCESSDENIED	拒絕訪問	0x80070005
E_FAIL	未知錯誤	0x80004005

 

注意：除了S_OK外，還有一個S_FALSE，它也屬於成功。

所以，微軟為了方便大家使用，專門提供了SUCCEEDED宏和FAILED宏來方便大家做判斷。

到這裡，大家明白了吧：SUCCEEDED宏是用來判斷COM中的函數執行是否成功用的，失敗為負數，成功為0和正數。

 

Windows Error Code

前面的代碼中我們調用了一個Windows API：

:RegCreateKeyEx(hk, szKeyPath, 0, NULL, REG_OPTION_NON_VOLATILE, KEY_QUERY_VALUE, NULL, &hk, NULL);

這個API的聲明是：

LONG WINAPI RegCreateKeyEx(  __in        HKEY hKey,  __in        LPCTSTR lpSubKey,  __reserved  DWORD Reserved,  __in_opt    LPTSTR lpClass,  __in        DWORD dwOptions,  __in        REGSAM samDesired,  __in_opt    LPSECURITY_ATTRIBUTES lpSecurityAttributes,  __out       PHKEY phkResult,  __out_opt   LPDWORD lpdwDisposition);

從MSDN中知道，它成功時返回的是ERROR_SUCCESS，其它值則是失敗，其它值就是類似GetLastError的錯誤碼。這些錯誤碼就是Windows Error Code。

 

Windows Error Codes

微軟在WinError.h定義了大量的Windows Error Codes，這種錯誤碼範圍是0x0000~0xFFFF，即2個位元組，但沒限定死2個位元組，也可以用4個位元組來儲存。在Windows API中，大量的使用了這種錯誤碼。比如上面的註冊表API，它的傳回值就是這種錯誤碼。

這種錯誤碼還有個特點是微軟為這些錯誤碼定義了比較詳細的可閱讀的描述資訊，它可以通過FormatMessage函數來獲得，在中文環境下，顯示的是翻譯後的中文。

 

Windows Error Codes 除了ERROR_SUCCESS外，都是正數，也就是不能用SUCCEEDED宏來判斷，因為這個宏只判斷是不是非負數，對於它而言，所有的Windows Error Codes都是成功的。

 

常見的Windows Error Codes

Win32 error codes	Description
0x00000000 ERROR_SUCCESS	The operation completed successfully.
0x00000000 NERR_Success	The operation completed successfully.
0x00000001 ERROR_INVALID_FUNCTION	Incorrect function.
0x00000002 ERROR_FILE_NOT_FOUND	The system cannot find the file specified.
0x00000003 ERROR_PATH_NOT_FOUND	The system cannot find the path specified.
0x00000004 ERROR_TOO_MANY_OPEN_FILES	The system cannot open the file.
0x00000005 ERROR_ACCESS_DENIED	Access is denied.

 

所以前面的代碼中，混淆了HRESULT和Windows Error Code，特別是第一種代碼，當註冊表失敗時它也會判斷為成功，第2種因為兩個都是0，碰巧不會出問題，但是建議還是不要這麼混用。

 

總結

 

參考資料

[MS-ERREF]: Windows Error Codes

http://msdn.microsoft.com/en-us/library/cc231196.aspx

HRESULT

http://msdn.microsoft.com/en-us/library/cc231198.aspx

2.2 Win32 Error Codes

http://msdn.microsoft.com/en-us/library/cc231199(v=PROT.10).aspx

2.3 NTSTATUS

http://msdn.microsoft.com/en-us/library/cc231200(v=PROT.10).aspx

Common HRESULT Values

http://msdn.microsoft.com/en-us/library/aa378137(VS.85).aspx

RegCreateKeyEx Function

http://msdn.microsoft.com/en-us/library/ms724844(VS.85).aspx