Share via


AtlThrow

Call this function to signal an error based on a HRESULT status code.

inline void AtlThrow(
   HRESULT hr
);

Parameters

  • hr
    Standard HRESULT value.

Remarks

This function is used by ATL and MFC code in the event of an error condition. It can also be called from your own code. The default implementation of this function depends on the definition of the symbol _ATL_NO_EXCEPTIONS and on the type of project, MFC or ATL.

In all cases, this function traces the HRESULT to the debugger.

If _ATL_NO_EXCEPTIONS is not defined in an MFC project, this function throws a CMemoryException or a COleException based on the value of the HRESULT.

If _ATL_NO_EXCEPTIONS is not defined in an ATL project, the function throws a CAtlException.

If _ATL_NO_EXCEPTIONS is defined, the function causes an assertion failure instead of throwing an exception.

For ATL projects, it is possible to provide your own implementation of this function to be used by ATL in the event of a failure. To do this, define your own function with the same signature as AtlThrow and #define AtlThrow to be the name of your function. This must be done before including atlexcept.h (which means that it must be done prior to including any ATL headers since atlbase.h includes atlexcept.h).

Example

// Constructors and operators cannot return error codes, and
// so they are the place where exceptions are generally used.
class CMyClass
{
private:
   CComPtr<IBuddy> m_spBuddy;
public:
   CMyClass()
   {
      HRESULT hr = m_spBuddy.CoCreateInstance(CLSID_Buddy);
      if (FAILED(hr))
         AtlThrow(hr);
   }
   //   methods ..
};

Requirements

Header: atldef.h

See Also

Reference

CAtlException Class

ATLTRACE2

CMemoryException Class

COleException Class

AtlThrowLastWin32

Other Resources

Debugging and Error Reporting Global Functions