教你看懂C++類庫函式定義之一---HRESULT 巨集

LoveApp_Han發表於2013-09-13

一切從一個C++ 類庫標頭檔案開始，現在在做一個C++的專案，期間用到一個開源的介面庫DUILib(類似MFC)，這個東西還不錯能很容易的寫出漂亮的介面,比如QQ的介面，可以去下載下來研究研究，地址：http://code.google.com/p/duilib/

廢話不多說，我比較困擾的是UIWebBrowser.h這個標頭檔案，雖然是C++寫的，但裡面包含太多大學C++課本以外的東西，第一遍看下來跟看天書一樣，裡面有很多的不惑，接下來我們一個一個解開。

首先看一下這個函式定義：

virtual HERSULT STDMETHODCALLTYPE GetTypeInfoCount( __RPC__out UINT *pctinfo);

這一篇詳細介紹 HERSULT

在用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_DEFINED
typedef 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.