PSYMBOL_REGISTERED_CALLBACK funzione di callback (dbghelp.h)

Articolo
08/23/2023

Funzione di callback definita dall'applicazione usata con la funzione SymRegisterCallback64 . Viene chiamato dal gestore dei simboli.

Il tipo PSYMBOL_REGISTERED_CALLBACK64 definisce un puntatore a questa funzione di callback. SymRegisterCallbackProc64 è un segnaposto per il nome della funzione definita dall'applicazione.

Sintassi

PSYMBOL_REGISTERED_CALLBACK PsymbolRegisteredCallback;

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

Parametri

[in] hProcess

Handle per il processo passato originariamente alla funzione SymInitialize .

[in] ActionCode

Codice di callback. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
CBA_DEBUG_INFO 0x10000000	Visualizzare informazioni dettagliate. Il parametro CallbackData è un puntatore a una stringa.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL 0x00000007	Il caricamento posticipato dei simboli è stato avviato. Per annullare il caricamento dei simboli, restituire TRUE. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE 0x00000002	Caricamento dei simboli posticipato completato. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_FAILURE 0x00000003	Caricamento dei simboli posticipato non riuscito. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . Il gestore dei simboli tenterà di caricare nuovamente i simboli se la funzione di callback imposta il membro FileName di questa struttura.
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL 0x00000020	Il caricamento posticipato dei simboli è stato completato parzialmente. Il caricatore di simboli non è in grado di leggere l'intestazione dell'immagine dal file di immagine o dal modulo specificato. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . Il gestore dei simboli tenterà di caricare nuovamente i simboli se la funzione di callback imposta il membro FileName di questa struttura. DbgHelp 5.1: Questo valore non è supportato.
CBA_DEFERRED_SYMBOL_LOAD_START 0x00000001	Caricamento dei simboli posticipato avviato. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DUPLICATE_SYMBOL 0x00000005	Sono stati trovati simboli duplicati. Questo motivo viene usato solo in formato COFF o CodeView. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_DUPLICATE_SYMBOL64 . Per specificare il simbolo da utilizzare, impostare il membro SelectedSymbol di questa struttura.
CBA_EVENT 0x00000010	Visualizzare informazioni dettagliate. Se questo evento non viene gestito, le informazioni vengono reinviete tramite l'evento CBA_DEBUG_INFO. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_CBA_EVENT .
CBA_READ_MEMORY 0x00000006	L'immagine caricata è stata letta. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_CBA_READ_MEMORY . La funzione di callback deve leggere il numero di byte specificato dal membro byte nel buffer specificato dal membro buf e aggiornare di conseguenza il membro byteread .
CBA_SET_OPTIONS 0x00000008	Le opzioni dei simboli sono state aggiornate. Per recuperare le opzioni correnti, chiamare la funzione SymGetOptions . Il parametro CallbackData deve essere ignorato.
CBA_SRCSRV_EVENT 0x40000000	Visualizzare informazioni dettagliate per il server di origine. Se questo evento non viene gestito, le informazioni vengono reinviete tramite l'evento CBA_DEBUG_INFO. Il parametro CallbackData è un puntatore a una struttura IMAGEHLP_CBA_EVENT . DbgHelp 6.6 e versioni precedenti: Questo valore non è supportato.
CBA_SRCSRV_INFO 0x20000000	Visualizzare informazioni dettagliate per il server di origine. Il parametro CallbackData è un puntatore a una stringa. DbgHelp 6.6 e versioni precedenti: Questo valore non è supportato.
CBA_SYMBOLS_UNLOADED 0x00000004	I simboli sono stati scaricati. Il parametro CallbackData deve essere ignorato.

[in, optional] CallbackData

Dati per l'operazione. Il formato di questi dati dipende dal valore del parametro ActionCode .

Se la funzione di callback è stata registrata con SymRegisterCallbackW64, i dati sono una stringa Unicode o una struttura di dati. In caso contrario, i dati usano il formato ANSI.

[in, optional] UserContext

Valore definito dall'utente specificato in SymRegisterCallback64 o NULL. In genere, questo parametro viene usato da un'applicazione per passare un puntatore a una struttura di dati che consente alla funzione di callback di stabilire un contesto.

Valore restituito

Per indicare l'esito positivo della gestione del codice, restituire TRUE.

Per indicare l'errore di gestione del codice, restituire FALSE. Se il codice non gestisce un codice specifico, è necessario restituire ANCHE FALSE. La restituzione di TRUE in questo caso potrebbe avere conseguenze impreviste.

Commenti

L'applicazione chiamante viene chiamata tramite la funzione di callback registrata come risultato di un'altra chiamata a una delle funzioni del gestore dei simboli. L'applicazione chiamante deve essere preparata per i possibili effetti collaterali che ciò può causare. Se l'applicazione ha una sola funzione di callback usata da più thread, potrebbe essere necessario sincronizzare alcuni tipi di accesso ai dati nel contesto della funzione di callback.

Questa funzione di callback sostituisce la funzione di callback PSYMBOL_REGISTERED_CALLBACK . PSYMBOL_REGISTERED_CALLBACK è definito come segue in 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

Per un esempio più dettagliato, vedere Getting Notifications (Recupero di notifiche).