偵錯和錯誤報告全域函式

發行項
07/05/2024

這些函式提供實用的偵錯和追蹤設施。

名稱	描述
AtlHresultFromLastError	`GetLastError`以 HRESULT 的形式傳回錯誤碼。
AtlHresultFromWin32	將 Win32 錯誤碼轉換成 HRESULT。
AtlReportError	設定 `IErrorInfo` 以提供錯誤詳細數據給用戶端。
AtlThrow	擲回 `CAtlException`。
AtlThrowLastWin32	呼叫此函式可依據 Windows 函式 `GetLastError` 的結果通知發生錯誤。

AtlHresultFromLastError

以 HRESULT 的形式，傳回呼叫執行緒的最後一個錯誤碼值。

HRESULT AtlHresultFromLastError();

備註

AtlHresultFromLastError 會呼叫 GetLastError 以取得最後一個錯誤，並在使用 HRESULT_FROM_WIN32 巨集將錯誤轉換成 HRESULT 之後傳回錯誤。

需求

標頭： atlcomcli.h

AtlHresultFromWin32

將 Win32 錯誤碼轉換成 HRESULT。

AtlHresultFromWin32(DWORD error);

參數

錯誤
要轉換的錯誤值。

備註

使用巨集HRESULT_FROM_WIN32，將 Win32 錯誤碼轉換成 HRESULT。

注意

不使用 HRESULT_FROM_WIN32(GetLastError())，請使用 AtlHresultFromLastError 函式。

需求

標頭： 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 式。在 AtlReportError C++ catch 處理程式中使用可能會導致 catch 處理程式C++例外狀況。

需求

標頭： atlcom.h

AtlThrow

呼叫此函式，根據 HRESULT 狀態代碼發出錯誤訊號。

__declspec(noreturn) inline void AtlThrow(HRESULT 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 來定義您自己的函式，並 #define AtlThrow 做為函式的名稱。這必須在包含 atlexcept.h 之前完成（這表示必須先完成，才能包含任何 ATL 標頭，因為 atlbase.h 包含 atlexcept.h）。屬性您的函 __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，則此函式會根據所傳回的值擲回 CMemoryException 或 COleException。GetLastError

如果未在 ATL 專案中定義_ATL_NO_EXCEPTIONS，函式會擲回 CAtlException。

如果已定義_ATL_NO_EXCEPTIONS，函式會造成判斷提示失敗，而不是擲回例外狀況。

需求

標頭： atldef.h

另請參閱

函式
 偵錯和錯誤報告巨集

共用方式為