调试和错误报告全局函数

项目
08/03/2024

这些函数提供有用的调试和跟踪工具。

名称	描述
AtlHresultFromLastError	以 HRESULT 的形式返回 `GetLastError` 错误代码。
AtlHresultFromWin32	将 Win32 错误代码转换为 HRESULT。
AtlReportError	设置 `IErrorInfo` 可向客户端提供错误详细信息。
AtlThrow	引发 `CAtlException`。
AtlThrowLastWin32	调用此函数可根据 Windows 函数 `GetLastError` 的结果发出错误。

AtlHresultFromLastError

以 HRESULT 的形式返回调用线程的上一个错误代码值。

HRESULT AtlHresultFromLastError();

备注

AtlHresultFromLastError 调用 GetLastError 以获取最新错误，并在使用 HRESULT_FROM_WIN32 宏将其转换为 HRESULT 后返回该错误。

要求

Header: atlcomcli.h

AtlHresultFromWin32

将 Win32 错误代码转换为 HRESULT。

AtlHresultFromWin32(DWORD error);

参数

error
要转换的错误值。

注解

使用宏 HRESULT_FROM_WIN32 将 Win32 错误代码转换为 HRESULT。

注意

不使用 HRESULT_FROM_WIN32(GetLastError())，而是使用函数 AtlHresultFromLastError。

要求

Header: atlcomcli.h

AtlReportError

设置 IErrorInfo 接口可向对象的客户端提供错误信息。

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCOLESTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCOLESTR lpszDesc,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCSTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    LPCSTR lpszDesc,
    DWORD dwHelpID,
    LPCSTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    UINT nID,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

HRESULT WINAPI AtlReportError(
    const CLSID& clsid,
    UINT nID,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

参数

clsid
[in] 报告错误的对象的 CLSID。

lpszDesc
[in] 描述错误的字符串。 Unicode 版本指定 lpszDesc 的类型为 LPCOLESTR；ANSI 版本指定的类型为 LPCSTR。

iid
[in] 定义错误的接口的 IID；如果错误由操作系统定义，则为 GUID_NULL。

hRes
[in] 你希望其返回到调用方的 HRESULT。

nID
[in] 存储错误说明字符串的资源标识符。此值应在 0x0200 到 0xFFFF 之间（含）。在调试版本中，如果 nID 未为有效字符串编制索引，则会导致 ASSERT。在发布版本中，错误说明字符串将设置为“未知错误。”

dwHelpID
[in] 错误的帮助上下文标识符。

lpszHelpFile
[in] 描述错误的帮助文件的路径和名称。

hInst
[in] 资源的句柄。默认情况下，此参数是 __AtlBaseModuleModule::GetResourceInstance，其中 __AtlBaseModuleModule 是 CAtlBaseModule 的全局实例或派生自它的类。

返回值

如果 hRes 参数不为零，则返回 hRes 的值。如果 hRes 为零，则 AtlReportError 的前四个版本会返回 DISP_E_EXCEPTION。最后两个版本返回巨集MAKE_HRESULT（1，FACILITY_ITF）nID的结果。

注解

字符串 lpszDesc 用作错误的文本说明。当客户端收到你从 AtlReportError 中返回的 hRes 时，客户端可以访问 IErrorInfo 结构以获取有关错误的详细信息。

示例

STDMETHODIMP CMyControl::MyErrorProneMethod()
{
   BOOL bSucceeded = ErrorProneFunc();
   if (bSucceeded)
      return S_OK;
   else
      // hRes is set to DISP_E_EXCEPTION
      return AtlReportError(GetObjectCLSID(), L"My error message");
}

注意

请勿在 C++ catch 处理程序中使用 AtlReportError。这些函数的某些重写在内部使用 ATL 字符串转换宏，反过来，这些宏又在内部使用 _alloca 函数。在 C++ catch 处理程序中使用 AtlReportError 可能会导致 C++ catch 处理程序中出现异常。

要求

标头：atlcom.h

AtlThrow

调用此函数可根据 HRESULT 状态代码发出错误。

__declspec(noreturn) inline void AtlThrow(HRESULT hr);

参数

hr
标准 HRESULT 值。

注解

ATL 和 MFC 代码在出现错误条件时使用此函数。也可以从你自己的代码调用它。此函数的默认实现取决于符号 _ATL_NO_EXCEPTIONS 的定义以及项目、MFC 或 ATL 的类型。

在所有情况下，此函数跟踪调试器的 HRESULT。

在 Visual Studio 2015 Update 3 及更高版本中，此函数属性为 __declspec(noreturn)，以避免出现虚假的 SAL 警告。

如果未在 MFC 项目中定义 _ATL_NO_EXCEPTIONS，此函数会根据 HRESULT 的值引发 CMemoryException 或 COleException 。

如果未在 ATL 项目中定义 _ATL_NO_EXCEPTIONS，此函数会引发 CAtlException。

如果定义了 _ATL_NO_EXCEPTIONS，此函数会导致断言失败，而不是引发异常。

对于 ATL 项目，可以提供你自己的此功能的实现，供 ATL 在发生故障时使用。为此，请使用与 AtlThrow 相同的签名定义自己的函数，并#将 AtlThrow 定义为你的函数名称。必须在包括 atlexcept.h 之前完成此操作（这意味着必须自 atlbase.h 包括 atlexcept.h 以来，在包括任何 ATL 标头之前完成此操作）。为函数 __declspec(noreturn) 设置属性，以避免虚假的 SAL 警告。

示例

// 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 ..
};

要求

标头：atldef.h

AtlThrowLastWin32

调用此函数可根据 Windows 函数 GetLastError 的结果发出错误。

inline void AtlThrowLastWin32();

备注

此函数将跟踪调试器的 GetLastError 结果。

如果未在 MFC 项目中定义 _ATL_NO_EXCEPTIONS，此函数会根据 GetLastError 返回的值引发 CMemoryException 或 COleException。