PSYMBOL_REGISTERED_CALLBACK回调函数 (dbghelp.h)

项目
02/26/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

有关更广泛的示例，请阅读获取通知。