PSYMBOL_REGISTERED_CALLBACK função de retorno de chamada (dbghelp.h)

Artigo
08/23/2023

Uma função de retorno de chamada definida pelo aplicativo usada com a função SymRegisterCallback64 . Ele é chamado pelo manipulador de símbolos.

O tipo PSYMBOL_REGISTERED_CALLBACK64 define um ponteiro para essa função de retorno de chamada. SymRegisterCallbackProc64 é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

PSYMBOL_REGISTERED_CALLBACK PsymbolRegisteredCallback;

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

Parâmetros

[in] hProcess

Um identificador para o processo que foi originalmente passado para a função SymInitialize .

[in] ActionCode

O código de retorno de chamada. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
CBA_DEBUG_INFO 0x10000000	Exibir informações detalhadas. O parâmetro CallbackData é um ponteiro para uma cadeia de caracteres.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL 0x00000007	O carregamento de símbolo adiado foi iniciado. Para cancelar a carga do símbolo, retorne TRUE. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE 0x00000002	A carga de símbolo adiada foi concluída. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_FAILURE 0x00000003	Falha na carga de símbolo adiada. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . O manipulador de símbolos tentará carregar os símbolos novamente se a função de retorno de chamada definir o membro FileName dessa estrutura.
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL 0x00000020	A carga de símbolo adiada foi parcialmente concluída. O carregador de símbolo não consegue ler o cabeçalho da imagem do arquivo de imagem ou do módulo especificado. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . O manipulador de símbolos tentará carregar os símbolos novamente se a função de retorno de chamada definir o membro FileName dessa estrutura. DbgHelp 5.1: Não há suporte para esse valor.
CBA_DEFERRED_SYMBOL_LOAD_START 0x00000001	A carga de símbolo adiada foi iniciada. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DUPLICATE_SYMBOL 0x00000005	Símbolos duplicados foram encontrados. Esse motivo é usado apenas no formato COFF ou CodeView. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_DUPLICATE_SYMBOL64 . Para especificar qual símbolo usar, defina o membro SelectedSymbol dessa estrutura.
CBA_EVENT 0x00000010	Exibir informações detalhadas. Se você não manipular esse evento, as informações serão ressentidas por meio do evento CBA_DEBUG_INFO. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_CBA_EVENT .
CBA_READ_MEMORY 0x00000006	A imagem carregada foi lida. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_CBA_READ_MEMORY . A função de retorno de chamada deve ler o número de bytes especificado pelo membro bytes no buffer especificado pelo membro buf e atualizar o membro bytesread adequadamente.
CBA_SET_OPTIONS 0x00000008	As opções de símbolo foram atualizadas. Para recuperar as opções atuais, chame a função SymGetOptions . O parâmetro CallbackData deve ser ignorado.
CBA_SRCSRV_EVENT 0x40000000	Exibir informações detalhadas para o servidor de origem. Se você não manipular esse evento, as informações serão ressentidas por meio do evento CBA_DEBUG_INFO. O parâmetro CallbackData é um ponteiro para uma estrutura IMAGEHLP_CBA_EVENT . DbgHelp 6.6 e anteriores: Não há suporte para esse valor.
CBA_SRCSRV_INFO 0x20000000	Exibir informações detalhadas para o servidor de origem. O parâmetro CallbackData é um ponteiro para uma cadeia de caracteres. DbgHelp 6.6 e anteriores: Não há suporte para esse valor.
CBA_SYMBOLS_UNLOADED 0x00000004	Os símbolos foram descarregados. O parâmetro CallbackData deve ser ignorado.

[in, optional] CallbackData

Dados da operação. O formato desses dados depende do valor do parâmetro ActionCode .

Se a função de retorno de chamada tiver sido registrada com SymRegisterCallbackW64, os dados serão uma cadeia de caracteres Unicode ou uma estrutura de dados. Caso contrário, os dados usarão o formato ANSI.

[in, optional] UserContext

Valor definido pelo usuário especificado em SymRegisterCallback64 ou NULL. Normalmente, esse parâmetro é usado por um aplicativo para passar um ponteiro para uma estrutura de dados que permite que a função de retorno de chamada estabeleça algum contexto.

Retornar valor

Para indicar o êxito na manipulação do código, retorne TRUE.

Para indicar falha ao lidar com o código, retorne FALSE. Se o código não manipular um código específico, você também deverá retornar FALSE. (Retornar TRUE neste caso pode ter consequências não intencionais.)

Comentários

O aplicativo de chamada é chamado por meio da função de retorno de chamada registrada como resultado de outra chamada para uma das funções do manipulador de símbolos. O aplicativo de chamada deve estar preparado para os possíveis efeitos colaterais que isso pode causar. Se o aplicativo tiver apenas uma função de retorno de chamada que está sendo usada por vários threads, talvez seja necessário ter cuidado para sincronizar alguns tipos de acesso a dados enquanto estiver no contexto da função de retorno de chamada.

Essa função de retorno de chamada substitui a função de retorno de chamada PSYMBOL_REGISTERED_CALLBACK. PSYMBOL_REGISTERED_CALLBACK é definido da seguinte maneira em 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

Para obter um exemplo mais abrangente, leia Obtendo notificações.