Using Callback Objects

There are three callback COM like interfaces that are used by the engine: IDebugEventCallbacks for notifying debugger extensions and applications of changes to the engine or target, IDebugInputCallbacks for requesting input, and IDebugOutputCallbacks for sending output.

Callback objects are registered with clients. At most, one instance of each of the three callback interfaces can be registered with each client (the Unicode and ASCII versions of an interface count as the same interface).

When a client is created, the engine remembers the thread in which it was created. The engine uses this same thread whenever it makes a call to a callback instance registered with the client. If the thread is in use, the engine will queue the calls it needs to make. To allow the engine to make these calls, the method DispatchCallbacks should be called whenever a client's thread is idle. The method ExitDispatch will cause DispatchCallbacks to return. If the thread is the same thread that was used to start the debugger session, then the engine can make the callback calls during the WaitForEvent method, and DispatchCallbacks does not need to be called.

The method FlushCallbacks tells the engine to send all buffered output to the output callbacks.

Event Callback Objects

The IDebugEventCallbacks interface is used by the engine to notify the debugger extensions and applications of events and changes to the engine and target. An implementation of IDebugEventCallbacks can be registered with a client using SetEventCallbacks. The current implementation registered with a client can be found using GetEventCallbacks. The number of event callbacks registered across all clients can be found using GetNumberEventCallbacks.

For details on how the engine manages events, see Monitoring Events.

Input Callback Objects

The IDebugInputCallbacks interface is used by the engine to request input from debugger extensions and applications. An implementation of IDebugInputCallbacks can be registered with a client using SetInputCallbacks. The current implementation registered with a client can be found using GetInputCallbacks. The number of input callbacks registered across all clients can be found using GetNumberInputCallbacks.

For details on how the engine manages input, see Input and Output.

Output Callback Objects

The IDebugOutputCallbacks interface is used by the engine to send output to the debugger extensions and applications. An implementation of IDebugOutputCallbacks can be registered with a client using SetOutputCallbacks. The current implementation registered with a client can be found using GetOutputCallbacks. The number of output callbacks registered across all clients can be found using GetNumberOutputCallbacks.

For details on how the engine manages output, see Input and Output.

Note   As is typical for COM objects, the engine will call IUnknown::AddRef on a callback COM object when it is registered with a client, and IUnknown::Release when the object is replaced or the client is deleted.