PSYMBOL_REGISTERED_CALLBACK función de devolución de llamada (dbghelp.h)

Artículo
02/29/2024

Función de devolución de llamada definida por la aplicación que se usa con la función SymRegisterCallback64 . Lo llama el controlador de símbolos.

El tipo PSYMBOL_REGISTERED_CALLBACK64 define un puntero a esta función de devolución de llamada. SymRegisterCallbackProc64 es un marcador de posición para el nombre de función definido por la aplicación.

Sintaxis

PSYMBOL_REGISTERED_CALLBACK PsymbolRegisteredCallback;

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

Parámetros

[in] hProcess

Identificador del proceso que se pasó originalmente a la función SymInitialize .

[in] ActionCode

Código de devolución de llamada. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
CBA_DEBUG_INFO 0x10000000	Mostrar información detallada. El parámetro CallbackData es un puntero a una cadena.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL 0x00000007	Se ha iniciado la carga de símbolos diferida. Para cancelar la carga de símbolos, devuelva TRUE. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE 0x00000002	Se ha completado la carga de símbolos diferida. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DEFERRED_SYMBOL_LOAD_FAILURE 0x00000003	Error en la carga de símbolos diferida. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . El controlador de símbolos intentará cargar los símbolos de nuevo si la función de devolución de llamada establece el miembro FileName de esta estructura.
CBA_DEFERRED_SYMBOL_LOAD_PARTIAL 0x00000020	La carga de símbolos diferida se ha completado parcialmente. El cargador de símbolos no puede leer el encabezado de imagen desde el archivo de imagen o el módulo especificado. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_DEFERRED_SYMBOL_LOAD64 . El controlador de símbolos intentará cargar los símbolos de nuevo si la función de devolución de llamada establece el miembro FileName de esta estructura. DbgHelp 5.1: Este valor no se admite.
CBA_DEFERRED_SYMBOL_LOAD_START 0x00000001	Se ha iniciado la carga de símbolos diferida. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_DEFERRED_SYMBOL_LOAD64 .
CBA_DUPLICATE_SYMBOL 0x00000005	Se encontraron símbolos duplicados. Este motivo solo se usa en formato COFF o CodeView. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_DUPLICATE_SYMBOL64 . Para especificar qué símbolo usar, establezca el miembro SelectedSymbol de esta estructura.
CBA_EVENT 0x00000010	Mostrar información detallada. Si no controla este evento, la información se resentrada a través del evento CBA_DEBUG_INFO. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_CBA_EVENT .
CBA_READ_MEMORY 0x00000006	Se ha leído la imagen cargada. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_CBA_READ_MEMORY . La función de devolución de llamada debe leer el número de bytes especificados por el miembro bytes en el búfer especificado por el miembro buf y actualizar el miembro bytesread según corresponda.
CBA_SET_OPTIONS 0x00000008	Se han actualizado las opciones de símbolo. Para recuperar las opciones actuales, llame a la función SymGetOptions . Se debe omitir el parámetro CallbackData .
CBA_SRCSRV_EVENT 0x40000000	Mostrar información detallada para el servidor de origen. Si no controla este evento, la información se resentrada a través del evento CBA_DEBUG_INFO. El parámetro CallbackData es un puntero a una estructura de IMAGEHLP_CBA_EVENT . DbgHelp 6.6 y versiones anteriores: Este valor no se admite.
CBA_SRCSRV_INFO 0x20000000	Mostrar información detallada para el servidor de origen. El parámetro CallbackData es un puntero a una cadena. DbgHelp 6.6 y versiones anteriores: Este valor no se admite.
CBA_SYMBOLS_UNLOADED 0x00000004	Se han descargado símbolos. Se debe omitir el parámetro CallbackData .

[in, optional] CallbackData

Datos de la operación. El formato de estos datos depende del valor del parámetro ActionCode .

Si la función de devolución de llamada se registró con SymRegisterCallbackW64, los datos son una cadena Unicode o una estructura de datos. De lo contrario, los datos usan el formato ANSI.

[in, optional] UserContext

Valor definido por el usuario especificado en SymRegisterCallback64 o NULL. Normalmente, una aplicación usa este parámetro para pasar un puntero a una estructura de datos que permite que la función de devolución de llamada establezca algún contexto.

Valor devuelto

Para indicar que el código se ha realizado correctamente, devuelva TRUE.

Para indicar el error que controla el código, devuelva FALSE. Si el código no controla un código determinado, también debe devolver FALSE. (Devolver TRUE en este caso puede tener consecuencias imprevistas).

Comentarios

La aplicación que realiza la llamada se llama a través de la función de devolución de llamada registrada como resultado de otra llamada a una de las funciones del controlador de símbolos. La aplicación que llama debe estar preparada para los posibles efectos secundarios que esto puede causar. Si la aplicación tiene solo una función de devolución de llamada que usan varios subprocesos, es posible que sea necesario sincronizar algunos tipos de acceso a datos mientras se encuentra en el contexto de la función de devolución de llamada.

Esta función de devolución de llamada reemplaza a la función de devolución de llamada PSYMBOL_REGISTERED_CALLBACK . PSYMBOL_REGISTERED_CALLBACK se define de la siguiente manera en 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 obtener un ejemplo más extenso, lea Obtención de notificaciones.