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 宏进行判断。