функция обратного вызова 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, данные являются строкой Или структурой данных в Юникоде. В противном случае данные используют формат 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

Более подробный пример см. в статье Получение уведомлений.

Требования

Требование	Значение
Целевая платформа	Windows
Header	dbghelp.h
Распространяемые компоненты	DbgHelp.dll 5.1 или более поздней версии