AtlThrow

Article
06/10/2016

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

Syntax

__declspec(noreturn) 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.

In Visual Studio 2015 Update 3 and later, this function is attributed __declspec(noreturn) to avoid spurious SAL warnings.

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). Attribute your function __declspec(noreturn) to avoid spurious SAL warnings.

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