デバッグとエラー報告に関するグローバル関数

[アーティクル]
04/03/2023

これらの関数によって、便利なデバッグ機能およびトレース機能が提供されます。

名前	説明
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);

パラメーター

error
変換するエラー値。

解説

マクロ HRESULT_FROM_WIN32 を使用して、Win32 エラーコードを HRESULT に変換します。

Note

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
[入力] エラーを報告するオブジェクトの CLSID。

lpszDesc
[入力] エラーを説明する文字列。 Unicode バージョンでは lpszDesc が LPCOLESTR 型であることを指定し、ANSI バージョンでは LPCSTR 型を指定します。

iid
[入力] エラーを定義するインターフェイスの IID。オペレーティングシステムによってエラーが定義されている場合は GUID_NULL。

hRes
[入力] 呼び出し元に返される HRESULT。

nID
[入力] エラー説明文字列が格納されているリソース識別子。この値は、0x0200 から 0xFFFF の範囲で指定する必要があります。デバッグビルドでは、nID で有効な文字列のインデックスが作成されない場合、ASSERT が発生します。リリースビルドでは、エラーの説明文字列が "不明なエラー" に設定されます。

dwHelpID
[入力] エラーのヘルプコンテキスト識別子。

lpszHelpFile
[入力] エラーを説明するヘルプファイルのパスと名前。

hInst
[入力] リソースへのハンドル。既定では、このパラメーターは __AtlBaseModuleModule::GetResourceInstance です。ここで、__AtlBaseModuleModule は CAtlBaseModule のグローバルインスタンス、またはそれから派生したクラスです。

戻り値

hRes パラメーターが 0 以外の場合、hRes の値を返します。 hRes が 0 の場合、AtlReportError の最初の 4 つのバージョンでは DISP_E_EXCEPTION を返します。最後の 2 つのバージョンは、マクロ 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);

パラメーター

人事
標準の HRESULT 値。

解説

この関数は、エラー条件が発生した場合に ATL および MFC コードによって使用されます。また、独自のコードから呼び出すこともできます。この関数の既定の実装は、シンボル _ATL_NO_EXCEPTIONS の定義と、プロジェクトの種類 (MFC または ATL) によって異なります。

どのような場合でも、この関数はデバッガーに対して HRESULT をトレースします。

Visual Studio 2015 Update 3 以降、この関数は、擬似 SAL の警告を回避するために __declspec(noreturn) の属性が付けられています。

_ATL_NO_EXCEPTIONS が MFC プロジェクトで定義されていない場合、この関数は HRESULT の値に基づいて CMemoryException または COleException をスローします。

ATL プロジェクトで _ATL_NO_EXCEPTIONS が定義されていない場合、関数は CAtlException をスローします。

_ATL_NO_EXCEPTIONS が定義されている場合、関数は、例外をスローする代わりにアサーションエラーを発生させます。

ATL プロジェクトでは、エラーが発生した場合に ATL が使用する、この関数の独自の実装を提供できます。これを行うには、AtlThrow と同じシグネチャを使用して独自の関数を定義し、関数の名前として #define で 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 の結果をトレースします。

_ATL_NO_EXCEPTIONS が MFC プロジェクトで定義されていない場合、この関数は GetLastError によって返された値に基づいて CMemoryException または COleException をスローします。

ATL プロジェクトで _ATL_NO_EXCEPTIONS が定義されていない場合、関数は CAtlException をスローします。

_ATL_NO_EXCEPTIONS が定義されている場合、関数は、例外をスローする代わりにアサーションエラーを発生させます。

要件

ヘッダー: atldef.h

次の方法で共有

デバッグとエラー報告に関するグローバル関数

AtlHresultFromLastError

解説

要件

AtlHresultFromWin32

パラメーター

解説

要件

AtlReportError

パラメーター

戻り値

解説

例

要件

AtlThrow

パラメーター

解説

例

要件

AtlThrowLastWin32

解説

要件

関連項目

フィードバック

その他のリソース