Export (0) Print
Expand All
Expand Minimize

SymRegisterCallbackProc64 callback function

An application-defined callback function used with the SymRegisterCallback64 function. It is called by the symbol handler.

The PSYMBOL_REGISTERED_CALLBACK64 type defines a pointer to this callback function. SymRegisterCallbackProc64 is a placeholder for the application-defined function name.

Syntax


BOOL CALLBACK SymRegisterCallbackProc64(
  _In_      HANDLE hProcess,
  _In_      ULONG ActionCode,
  _In_opt_  ULONG64 CallbackData,
  _In_opt_  ULONG64 UserContext
);

Parameters

hProcess [in]

A handle to the process that was originally passed to the SymInitialize function.

ActionCode [in]

The callback code. This parameter can be one of the following values.

ValueMeaning
CBA_DEBUG_INFO
0x10000000

Display verbose information.

The CallbackData parameter is a pointer to a string.

CBA_DEFERRED_SYMBOL_LOAD_CANCEL
0x00000007

Deferred symbol loading has started. To cancel the symbol load, return TRUE.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure.

CBA_DEFERRED_SYMBOL_LOAD_COMPLETE
0x00000002

Deferred symbol load has completed.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure.

CBA_DEFERRED_SYMBOL_LOAD_FAILURE
0x00000003

Deferred symbol load has failed.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure. The symbol handler will attempt to load the symbols again if the callback function sets the FileName member of this structure.

CBA_DEFERRED_SYMBOL_LOAD_PARTIAL
0x00000020

Deferred symbol load has partially completed. The symbol loader is unable to read the image header from either the image file or the specified module.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure. The symbol handler will attempt to load the symbols again if the callback function sets the FileName member of this structure.

DbgHelp 5.1:  This value is not supported.

CBA_DEFERRED_SYMBOL_LOAD_START
0x00000001

Deferred symbol load has started.

The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure.

CBA_DUPLICATE_SYMBOL
0x00000005

Duplicate symbols were found. This reason is used only in COFF or CodeView format.

The CallbackData parameter is a pointer to a IMAGEHLP_DUPLICATE_SYMBOL64 structure. To specify which symbol to use, set the SelectedSymbol member of this structure.

CBA_EVENT
0x00000010

Display verbose information. If you do not handle this event, the information is resent through the CBA_DEBUG_INFO event.

The CallbackData parameter is a pointer to a IMAGEHLP_CBA_EVENT structure.

CBA_READ_MEMORY
0x00000006

The loaded image has been read.

The CallbackData parameter is a pointer to a IMAGEHLP_CBA_READ_MEMORY structure. The callback function should read the number of bytes specified by the bytes member into the buffer specified by the buf member, and update the bytesread member accordingly.

CBA_SET_OPTIONS
0x00000008

Symbol options have been updated. To retrieve the current options, call the SymGetOptions function.

The CallbackData parameter should be ignored.

CBA_SRCSRV_EVENT
0x40000000

Display verbose information for source server. If you do not handle this event, the information is resent through the CBA_DEBUG_INFO event.

The CallbackData parameter is a pointer to a IMAGEHLP_CBA_EVENT structure.

DbgHelp 6.6 and earlier:  This value is not supported.

CBA_SRCSRV_INFO
0x20000000

Display verbose information for source server.

The CallbackData parameter is a pointer to a string.

DbgHelp 6.6 and earlier:  This value is not supported.

CBA_SYMBOLS_UNLOADED
0x00000004

Symbols have been unloaded.

The CallbackData parameter should be ignored.

 

CallbackData [in, optional]

Data for the operation. The format of this data depends on the value of the ActionCode parameter.

If the callback function was registered with SymRegisterCallbackW64, the data is a Unicode string or data structure. Otherwise, the data uses ANSI format.

UserContext [in, optional]

User-defined value specified in SymRegisterCallback64, or NULL. Typically, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context.

Return value

To indicate success handling the code, return TRUE.

To indicate failure handling the code, return FALSE. If your code does not handle a particular code, you should also return FALSE. (Returning TRUE in this case may have unintended consequences.)

Remarks

The calling application gets called through the registered callback function as a result of another call to one of the symbol handler functions. The calling application must be prepared for the possible side effects that this can cause. If the application has only one callback function that is being used by multiple threads, then care may be necessary to synchronize some types of data access while in the context of the callback function.

This callback function supersedes the PSYMBOL_REGISTERED_CALLBACK callback function. PSYMBOL_REGISTERED_CALLBACK is defined as follows 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

For a more extensive example, read Getting Notifications.

Requirements

Redistributable

DbgHelp.dll 5.1 or later

Header

DbgHelp.h

See also

DbgHelp Functions
Getting Notifications
IMAGEHLP_CBA_EVENT
IMAGEHLP_CBA_READ_MEMORY
IMAGEHLP_DEFERRED_SYMBOL_LOAD64
IMAGEHLP_DUPLICATE_SYMBOL64
SymRegisterCallback64

 

 

Community Additions

ADD
Show:
© 2014 Microsoft