PSYMBOL_REGISTERED_CALLBACK コールバック関数 (dbghelp.h)

[アーティクル]
08/23/2023

SymRegisterCallback64 関数で使用されるアプリケーション定義のコールバック関数。これはシンボルハンドラーによって呼び出されます。

PSYMBOL_REGISTERED_CALLBACK64型は、このコールバック関数へのポインターを定義します。 SymRegisterCallbackProc64 は、アプリケーション定義関数名のプレースホルダーです。

構文

PSYMBOL_REGISTERED_CALLBACK PsymbolRegisteredCallback;

BOOL PsymbolRegisteredCallback(
  [in]           HANDLE hProcess,
  [in]           ULONG ActionCode,
  [in, optional] PVOID CallbackData,
  [in, optional] PVOID UserContext
)
{...}

パラメーター

[in] hProcess

SymInitialize 関数に最初に渡されたプロセスへのハンドル。

[in] ActionCode

コールバックコード。このパラメーターには、次の値のいずれかを指定できます。

値	意味
CBA_DEBUG_INFO 0x10000000	詳細な情報を表示します。 CallbackData パラメーターは、文字列へのポインターです。
CBA_DEFERRED_SYMBOL_LOAD_CANCEL 0x00000007	遅延シンボルの読み込みが開始されました。シンボルの読み込みを取り消すには、 TRUE を返します。 CallbackData パラメーターは、IMAGEHLP_DEFERRED_SYMBOL_LOAD64構造体へのポインターです。
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE 0x00000002	遅延シンボルの読み込みが完了しました。 CallbackData パラメーターは、IMAGEHLP_DEFERRED_SYMBOL_LOAD64構造体へのポインターです。
CBA_DEFERRED_SYMBOL_LOAD_FAILURE 0x00000003	遅延シンボルの読み込みに失敗しました。 CallbackData パラメーターは、IMAGEHLP_DEFERRED_SYMBOL_LOAD64構造体へのポインターです。コールバック関数によってこの構造体の FileName メンバーが設定された場合、シンボルハンドラーはシンボルの読み込みを再試行します。
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL 0x00000020	遅延シンボルの読み込みが部分的に完了しました。シンボルローダーは、イメージファイルまたは指定したモジュールからイメージヘッダーを読み取ることができません。 CallbackData パラメーターは、IMAGEHLP_DEFERRED_SYMBOL_LOAD64構造体へのポインターです。コールバック関数によってこの構造体の FileName メンバーが設定された場合、シンボルハンドラーはシンボルの読み込みを再試行します。 DbgHelp 5.1: この値はサポートされていません。
CBA_DEFERRED_SYMBOL_LOAD_START 0x00000001	シンボルの遅延読み込みが開始されました。 CallbackData パラメーターは、IMAGEHLP_DEFERRED_SYMBOL_LOAD64構造体へのポインターです。
CBA_DUPLICATE_SYMBOL 0x00000005	重複するシンボルが見つかりました。この理由は、COFF または CodeView 形式でのみ使用されます。 CallbackData パラメーターは、IMAGEHLP_DUPLICATE_SYMBOL64構造体へのポインターです。使用するシンボルを指定するには、この構造体の SelectedSymbol メンバーを設定します。
CBA_EVENT 0x00000010	詳細な情報を表示します。このイベントを処理しない場合、情報は CBA_DEBUG_INFO イベントを通じて再送信されます。 CallbackData パラメーターは、IMAGEHLP_CBA_EVENT構造体へのポインターです。
CBA_READ_MEMORY 0x00000006	読み込まれたイメージが読み取られます。 CallbackData パラメーターは、IMAGEHLP_CBA_READ_MEMORY構造体へのポインターです。コールバック関数は、バイトメンバーによって指定されたバイト数を buf メンバーによって指定されたバッファーに読み取り、それに応じて bytesread メンバーを更新する必要があります。
CBA_SET_OPTIONS 0x00000008	シンボルオプションが更新されました。現在のオプションを取得するには、 SymGetOptions 関数を呼び出します。 CallbackData パラメーターは無視する必要があります。
CBA_SRCSRV_EVENT 0x40000000	ソースサーバーの詳細な情報を表示します。このイベントを処理しない場合、情報は CBA_DEBUG_INFO イベントを通じて再送信されます。 CallbackData パラメーターは、IMAGEHLP_CBA_EVENT構造体へのポインターです。 DbgHelp 6.6 以前: この値はサポートされていません。
CBA_SRCSRV_INFO 0x20000000	ソースサーバーの詳細な情報を表示します。 CallbackData パラメーターは、文字列へのポインターです。 DbgHelp 6.6 以前: この値はサポートされていません。
CBA_SYMBOLS_UNLOADED 0x00000004	シンボルがアンロードされました。 CallbackData パラメーターは無視する必要があります。

[in, optional] CallbackData

操作のデータ。このデータの形式は 、ActionCode パラメーターの値によって異なります。

コールバック関数が SymRegisterCallbackW64 に登録されている場合、データは Unicode 文字列またはデータ構造です。それ以外の場合、データは ANSI 形式を使用します。

[in, optional] UserContext

SymRegisterCallback64 または NULL で指定されたユーザー定義値。通常、このパラメーターは、コールバック関数がコンテキストを確立できるようにするデータ構造へのポインターを渡すためにアプリケーションによって使用されます。

戻り値

コードの処理が成功したことを示すには、 TRUE を返します。

コードの処理に失敗したことを示すには、 FALSE を返します。コードが特定のコードを処理しない場合は、 FALSE も返す必要があります。 (この場合 に TRUE を 返した場合、意図しない結果が生じる可能性があります)。

注釈

呼び出し元のアプリケーションは、シンボルハンドラー関数の 1 つに対する別の呼び出しの結果として、登録済みのコールバック関数を介して呼び出されます。呼び出し元のアプリケーションは、これが引き起こす可能性のある副作用に備える必要があります。アプリケーションに複数のスレッドで使用されているコールバック関数が 1 つだけある場合は、コールバック関数のコンテキストで一部の種類のデータアクセスを同期するために注意が必要な場合があります。

このコールバック関数は、 PSYMBOL_REGISTERED_CALLBACK コールバック関数よりも優先されます。 PSYMBOL_REGISTERED_CALLBACK は、Dbghelp.h で次のように定義されます。

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define PSYMBOL_REGISTERED_CALLBACK PSYMBOL_REGISTERED_CALLBACK64
#else
typedef BOOL
(CALLBACK *PSYMBOL_REGISTERED_CALLBACK)(
    __in HANDLE hProcess,
    __in ULONG ActionCode,
    __in_opt PVOID CallbackData,
    __in_opt PVOID UserContext
    );
#endif

より広範な例については、「通知の取得」を参照してください。