HRESULT宏的介紹

COM編程或涉及到使用COM組件的時候，常使用HRESULT作為函數的返回值，來表示函數執行的成功與否。HRESULT返回的成功與否，可用以下兩個宏來判斷：

1. SUCCEEDED
   

原型如下：

BOOL SUCCEEDED(  HRESULT hr
);

對應的定義（具體的實現）：#define SUCCEEDED(hr) (((HRESULT)(hr)) >= 0)

2. FAILED

原型如下：

BOOL FAILED(  HRESULT hr
);

對應的定義（具體的實現）：#define FAILED(hr) (((HRESULT)(hr)) < 0)

注意：

使用這兩個宏來對COM組件的返回值HRESULT進行判斷；

因為HRESULT值為返回狀態，失敗的情況下有很多種狀態，所以不能直接判斷

關于HRESULT

如果函數正常執行，則返回S_OK，同時真正的函數運行結果則通過參數指針返回。如果遇到了異常情況，則COM系統經過判斷，會返回相應的錯誤值。

HRESULT         值          含義
S_OK            0x00000000  成功
S_FALSE         0x00000001  函數成功執行完成，但返回時出現錯誤
E_INVALIDARG    0x80070057  參數有錯誤
E_OUTOFMEMORY   0x8007000E  內存申請錯誤
E_UNEXPECTED    0x8000FFFF  未知的異常
E_NOTIMPL       0x80004001  未實現功能
E_FAIL          0x80004005  沒有詳細說明的錯誤。一般需要取得 Rich Error 錯誤信息(注1)
E_POINTER       0x80004003  無效的指針
E_HANDLE        0x80070006  無效的句柄
E_ABORT         0x80004004  終止操作
E_ACCESSDENIED  0x80070005  訪問被拒絕
E_NOINTERFACE   0x80004002  不支持接口

HRESULT 其實是一個雙字節的值，其最高位(bit)如果是0表示成功，1表示錯誤。具體參見 MSDN 之"Structure of COM Error Codes"說明。我們在程序中如果需要判斷返回值，則可以使用比較運算符號；switch開關語句；也可以使用VC提供的宏：

     HRESULT hr = 調用組件函數;
      if( SUCCEEDED( hr ) ){...} // 如果成功
      ......
      if( FAILED( hr ) ){...} // 如果失敗
      ......

大多數COM 函數以及一些接口成員函數的返回值類型均為HRESULT 類型。HRESULT 類型的返回值反映了函數中的一些情況，其類型定義規范如下：

   31 30 29 28                    16 15                                0
  |-----|--|------------------------|-----------------------------------|

類別碼 (30-31) 反映函數調用結果：
                00 調用成功
                01 包含一些信息
                10 警告
                11 錯誤
自定義標記(29) 反映結果是否為自定義標識，1 為是，0 則不是；
操作碼 (16-28) 標識結果操作來源，在 Windows 平臺上，其定義如下：
                #define FACILITY_WINDOWS         8
                #define FACILITY_STORAGE         3
                #define FACILITY_RPC             1
                #define FACILITY_SSPI            9
                #define FACILITY_WIN32           7
                #define FACILITY_CONTROL         10
                #define FACILITY_NULL            0
                #define FACILITY_INTERNET        12
                #define FACILITY_ITF             4
                #define FACILITY_DISPATCH        2
                #define FACILITY_CERT            11
操作結果碼(0-15) 反映操作的狀態，WinError.h 定義了 Win32 函數所有可能返回結果。
                以下是一些經常用到的返回值和宏定義：
                S_OK            函數執行成功，其值為 0 (注意，其值與 TRUE 相反)
                S_FALSE         函數執行成功，其值為 1
                S_FAIL          函數執行失敗，失敗原因不確定
                E_OUTOFMEMORY   函數執行失敗，失敗原因為內存分配不成功
                E_NOTIMPL       函數執行失敗，成員函數沒有被實現
                E_NOTINTERFACE  函數執行失敗，組件沒有實現指定的接口

注意：不能簡單地把返回值與S_OK和S_FALSE比較，而要用SECCEEDED 和FAILED 宏進行判斷

FAILED和SUCCEEDED是windows中定義的宏函數，而S_OK只是一個特定的值。

#define SUCCEEDED(Status) ((HRESULT)(Status) >= 0)

#define FAILED(Status) ((HRESULT)(Status) <0)

成功的代碼有多個，失敗的代碼也有多個一個函數在各種情況下返回的狀態代碼通常將包含多個成功代碼及多個失敗代碼。

這就是我們為什么要使用SUCCEEDED及FAILED宏的原因。一般不能直接將HRESULT值同某個成功代碼（如S_OK）進行比較以決定某個函數是否成功。