PSYMBOL_REGISTERED_CALLBACK fonction de rappel (dbghelp.h)

Article
08/23/2023

Fonction de rappel définie par l’application utilisée avec la fonction SymRegisterCallback64 . Il est appelé par le gestionnaire de symboles.

Le type PSYMBOL_REGISTERED_CALLBACK64 définit un pointeur vers cette fonction de rappel. SymRegisterCallbackProc64 est un espace réservé pour le nom de fonction défini par l’application.

Syntaxe

PSYMBOL_REGISTERED_CALLBACK PsymbolRegisteredCallback;

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

Paramètres

[in] hProcess

Handle du processus qui a été passé à l’origine à la fonction SymInitialize .

[in] ActionCode

Code de rappel. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
CBA_DEBUG_INFO 0x10000000	Affichez des informations détaillées. Le paramètre CallbackData est un pointeur vers une chaîne.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL 0x00000007	Le chargement différé des symboles a commencé. Pour annuler le chargement de symboles, retournez TRUE. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE 0x00000002	Le chargement différé des symboles est terminé. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_FAILURE 0x00000003	Échec du chargement différé des symboles. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . Le gestionnaire de symboles tente de charger à nouveau les symboles si la fonction de rappel définit le membre FileName de cette structure.
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL 0x00000020	Le chargement différé des symboles est partiellement terminé. Le chargeur de symboles ne peut pas lire l’en-tête d’image à partir du fichier image ou du module spécifié. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . Le gestionnaire de symboles tente de charger à nouveau les symboles si la fonction de rappel définit le membre FileName de cette structure. DbgHelp 5.1 : Cette valeur n’est pas prise en charge.
CBA_DEFERRED_SYMBOL_LOAD_START 0x00000001	Le chargement différé des symboles a démarré. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DUPLICATE_SYMBOL 0x00000005	Des symboles en double ont été trouvés. Cette raison est utilisée uniquement au format COFF ou CodeView. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_DUPLICATE_SYMBOL64 . Pour spécifier le symbole à utiliser, définissez le membre SelectedSymbol de cette structure.
CBA_EVENT 0x00000010	Affichez des informations détaillées. Si vous ne gérez pas cet événement, les informations sont réinsentrées via l’événement CBA_DEBUG_INFO. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_CBA_EVENT .
CBA_READ_MEMORY 0x00000006	L’image chargée a été lue. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_CBA_READ_MEMORY . La fonction de rappel doit lire le nombre d’octets spécifié par le membre d’octets dans la mémoire tampon spécifiée par le membre buf et mettre à jour le membre bytesread en conséquence.
CBA_SET_OPTIONS 0x00000008	Les options de symbole ont été mises à jour. Pour récupérer les options actuelles, appelez la fonction SymGetOptions . Le paramètre CallbackData doit être ignoré.
CBA_SRCSRV_EVENT 0x40000000	Affichez des informations détaillées pour le serveur source. Si vous ne gérez pas cet événement, les informations sont réinsentrées via l’événement CBA_DEBUG_INFO. Le paramètre CallbackData est un pointeur vers une structure IMAGEHLP_CBA_EVENT . DbgHelp 6.6 et versions antérieures : Cette valeur n’est pas prise en charge.
CBA_SRCSRV_INFO 0x20000000	Affichez des informations détaillées pour le serveur source. Le paramètre CallbackData est un pointeur vers une chaîne. DbgHelp 6.6 et versions antérieures : Cette valeur n’est pas prise en charge.
CBA_SYMBOLS_UNLOADED 0x00000004	Les symboles ont été déchargés. Le paramètre CallbackData doit être ignoré.

[in, optional] CallbackData

Données de l’opération. Le format de ces données dépend de la valeur du paramètre ActionCode .

Si la fonction de rappel a été inscrite auprès de SymRegisterCallbackW64, les données sont une chaîne Unicode ou une structure de données. Sinon, les données utilisent le format ANSI.

[in, optional] UserContext

Valeur définie par l’utilisateur spécifiée dans SymRegisterCallback64, ou NULL. En règle générale, ce paramètre est utilisé par une application pour passer un pointeur vers une structure de données qui permet à la fonction de rappel d’établir un contexte.

Valeur retournée

Pour indiquer la réussite de la gestion du code, retourne TRUE.

Pour indiquer l’échec de la gestion du code, retournez FALSE. Si votre code ne gère pas un code particulier, vous devez également retourner FALSE. (Le retour de TRUE dans ce cas peut avoir des conséquences inattendues.)

Remarques

L’application appelante est appelée via la fonction de rappel inscrite à la suite d’un autre appel à l’une des fonctions de gestionnaire de symboles. L’application appelante doit être préparée pour les effets secondaires possibles que cela peut provoquer. Si l’application n’a qu’une seule fonction de rappel utilisée par plusieurs threads, il peut être nécessaire de synchroniser certains types d’accès aux données dans le contexte de la fonction de rappel.

Cette fonction de rappel remplace la fonction de rappel PSYMBOL_REGISTERED_CALLBACK . PSYMBOL_REGISTERED_CALLBACK est défini comme suit dans 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

Pour obtenir un exemple plus détaillé, consultez Obtenir des notifications.