COm __HRESULT 函数返回值

每个人在做程序设计的时候，都有他们各自的哲学思想。拿函数返回值来说，就有好多种形式。
　

函数	返回值	返回值信息
double sin(double)	浮点数值	计算正玄值
BOOL DeleteFile(LPCTSTR)	布尔值	文件删除是否成功。如失败，需要GetLastError()才能取得失败原因
void * malloc(size_t)	内存指针	内存申请，如果失败，返回空指针 NULL
LONG RegDeleteKey(HKEY,LPCTSTR)	整数	删除注册表项。0表示成功，非0失败，同时这个值就反映了失败的原因
UINT DragQueryFile(HDROP,UINT,LPTSTR,UINT)	整数	取得拖放文件信息。以不同的参数调用，则返回不同的含义： 一会儿表示文件个数，一会儿表示文件名长度，一会儿表示字符长度
......  ......	...	......  ......

　　如此纷繁复杂的返回值，如此含义多变的返回值，使得大家在学习和使用的过程中，增加了额外的困难。好了，COM 的设计规范终于对他们进行了统一。组件API及接口指针中，除了IUnknown::AddRef()和IUnknown::Release()两个函数外，其它所有的函数，都以 HRESULT 作为返回值。大家想象一个组件的接口函数比如叫Add()，完成2个整数的加法运算，在C语言中，我们可以如下定义：

      long Add( long n1, long n2 )
      {
          return n1 + n2;
      }

　　还记得刚才我们说的原则吗？COM 组件是运行在分布式环境中的。也就是说，这个函数可能运行在“地球另一边”的计算机上，既然运行在那么遥远的地方，就有可能出现服务器关机、网络掉线、运行超时、对方不在服务区......等异常。于是，这个加法函数，除了需要返回运算结果以外，还应该返回一个值------函数是否被正常执行了。

      HRESULT Add( long n1, long n2, long *pSum )
      {
          *pSum = n1 + n2;
          return S_OK;
      }

　　如果函数正常执行，则返回 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 的结构

　　HRESULT 其实是一个双字节的值，其最高位(bit)如果是0表示成功，1表示错误。具体参见 MSDN 之"Structure of COM Error Codes"说明。我们在程序中如果需要判断返回值，则可以使用比较运算符号；switch开关语句；也可以使用VC提供的宏：

      HRESULT hr = 调用组件函数;
      if( SUCCEEDED( hr ) ){...} // 如果成功
      ......
      if( FAILED( hr ) ){...} // 如果失败
      ......