PSYMBOL_REGISTERED_CALLBACK回呼函式 (dbghelp.h)

發行項
03/05/2024

搭配 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 可能會有非預期的結果。)

備註

呼叫端應用程式會透過已註冊的回呼函式呼叫，因為對其中一個符號處理程式函式進行另一個呼叫。呼叫端應用程式必須備妥，才能造成可能的副作用。如果應用程式只有一個由多個線程使用的回呼函式，則可能需要在回呼函式的內容中同步處理某些類型的數據存取。

此回呼函式會取代 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

如需更廣泛的範例，請參閱取得通知。