PSYMBOL_REGISTERED_CALLBACK Rückruffunktion (dbghelp.h)

Artikel
08/23/2023

Eine anwendungsdefinierte Rückruffunktion, die mit der SymRegisterCallback64-Funktion verwendet wird. Sie wird vom Symbolhandler aufgerufen.

Der PSYMBOL_REGISTERED_CALLBACK64 Typ definiert einen Zeiger auf diese Rückruffunktion. SymRegisterCallbackProc64 ist ein Platzhalter für den anwendungsdefinierten Funktionsnamen.

Syntax

PSYMBOL_REGISTERED_CALLBACK PsymbolRegisteredCallback;

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

Parameter

[in] hProcess

Ein Handle für den Prozess, der ursprünglich an die SymInitialize-Funktion übergeben wurde.

[in] ActionCode

Der Rückrufcode. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
CBA_DEBUG_INFO 0x10000000	Ausführliche Informationen anzeigen. Der CallbackData-Parameter ist ein Zeiger auf eine Zeichenfolge.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL 0x00000007	Das Verzögerte Laden von Symbolen wurde gestartet. Um das Laden des Symbols abzubrechen, geben Sie TRUE zurück. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_DEFERRED_SYMBOL_LOAD64-Struktur .
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE 0x00000002	Die verzögerte Symbolladung wurde abgeschlossen. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_DEFERRED_SYMBOL_LOAD64-Struktur .
CBA_DEFERRED_SYMBOL_LOAD_FAILURE 0x00000003	Fehler beim Laden des verzögerten Symbols. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_DEFERRED_SYMBOL_LOAD64-Struktur . Der Symbolhandler versucht, die Symbole erneut zu laden, wenn die Rückruffunktion das FileName-Element dieser Struktur festlegt.
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL 0x00000020	Die verzögerte Symbolladung wurde teilweise abgeschlossen. Das Symbolladeprogramm kann den Bildheader weder aus der Bilddatei noch aus dem angegebenen Modul lesen. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_DEFERRED_SYMBOL_LOAD64-Struktur . Der Symbolhandler versucht, die Symbole erneut zu laden, wenn die Rückruffunktion das FileName-Element dieser Struktur festlegt. DbgHelp 5.1: Dieser Wert wird nicht unterstützt.
CBA_DEFERRED_SYMBOL_LOAD_START 0x00000001	Das Laden von verzögerten Symbolen wurde gestartet. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_DEFERRED_SYMBOL_LOAD64-Struktur .
CBA_DUPLICATE_SYMBOL 0x00000005	Es wurden doppelte Symbole gefunden. Dieser Grund wird nur im COFF- oder CodeView-Format verwendet. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_DUPLICATE_SYMBOL64-Struktur . Um anzugeben, welches Symbol verwendet werden soll, legen Sie das SelectedSymbol-Element dieser Struktur fest.
CBA_EVENT 0x00000010	Ausführliche Informationen anzeigen. Wenn Sie dieses Ereignis nicht behandeln, werden die Informationen erneut über das CBA_DEBUG_INFO-Ereignis weitergeleitet. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_CBA_EVENT Struktur.
CBA_READ_MEMORY 0x00000006	Das geladene Image wurde gelesen. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_CBA_READ_MEMORY-Struktur . Die Rückruffunktion sollte die vom Bytes-Member angegebene Anzahl von Bytes in den vom buf-Member angegebenen Puffer einlesen und den Bytesread-Member entsprechend aktualisieren.
CBA_SET_OPTIONS 0x00000008	Symboloptionen wurden aktualisiert. Um die aktuellen Optionen abzurufen, rufen Sie die SymGetOptions-Funktion auf. Der CallbackData-Parameter sollte ignoriert werden.
CBA_SRCSRV_EVENT 0x40000000	Ausführliche Informationen für den Quellserver anzeigen. Wenn Sie dieses Ereignis nicht behandeln, werden die Informationen erneut über das CBA_DEBUG_INFO-Ereignis weitergeleitet. Der CallbackData-Parameter ist ein Zeiger auf eine IMAGEHLP_CBA_EVENT Struktur. DbgHelp 6.6 und früher: Dieser Wert wird nicht unterstützt.
CBA_SRCSRV_INFO 0x20000000	Ausführliche Informationen für den Quellserver anzeigen. Der CallbackData-Parameter ist ein Zeiger auf eine Zeichenfolge. DbgHelp 6.6 und früher: Dieser Wert wird nicht unterstützt.
CBA_SYMBOLS_UNLOADED 0x00000004	Symbole wurden entladen. Der CallbackData-Parameter sollte ignoriert werden.

[in, optional] CallbackData

Daten für den Vorgang. Das Format dieser Daten hängt vom Wert des ActionCode-Parameters ab.

Wenn die Rückruffunktion bei SymRegisterCallbackW64 registriert wurde, handelt es sich bei den Daten um eine Unicode-Zeichenfolge oder Datenstruktur. Andernfalls verwenden die Daten das ANSI-Format.

[in, optional] UserContext

Benutzerdefinierter Wert, der in SymRegisterCallback64 oder NULL angegeben ist. In der Regel wird dieser Parameter von einer Anwendung verwendet, um einen Zeiger an eine Datenstruktur zu übergeben, mit der die Rückruffunktion einen Kontext einrichten kann.

Rückgabewert

Um anzugeben, dass der Code erfolgreich verarbeitet wurde, geben Sie TRUE zurück.

Um anzugeben, dass der Code nicht verarbeitet wird, geben Sie FALSE zurück. Wenn Ihr Code keinen bestimmten Code verarbeitet, sollten Sie auch FALSE zurückgeben. (Die Rückgabe von TRUE kann in diesem Fall unbeabsichtigte Folgen haben.)

Hinweise

Die aufrufende Anwendung wird über die registrierte Rückruffunktion aufgerufen, als Ergebnis eines weiteren Aufrufs einer der Symbolhandlerfunktionen. Die aufrufende Anwendung muss auf die möglichen Nebenwirkungen vorbereitet sein, die dies verursachen kann. Wenn die Anwendung nur über eine Rückruffunktion verfügt, die von mehreren Threads verwendet wird, ist möglicherweise Sorgfalt erforderlich, um einige Arten des Datenzugriffs im Kontext der Rückruffunktion zu synchronisieren.

Diese Rückruffunktion ersetzt die PSYMBOL_REGISTERED_CALLBACK Rückruffunktion. PSYMBOL_REGISTERED_CALLBACK wird in Dbghelp.h wie folgt definiert.

#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

Ein ausführliches Beispiel finden Sie unter Abrufen von Benachrichtigungen.