| Debugging Tools for Windows |
For an overview of the input and output streams in the debugger engine, see Input and Output.
The engine will ask for input from all its clients if the Input method is called on a client. The input is returned to the caller of Input.
When the engine asks for input from a client, it uses the IDebugInputCallbacks object registered with that client. An IDebugInputCallbacks object may be registered with a client using SetInputCallbacks. Each client can have at most one IDebugInputCallbacks object registered with it.
The request for input begins with the engine calling the IDebugInputCallbacks::StartInput method. This informs the IDebugInputCallbacks object that the engine is now waiting for input.
If the IDebugInputCallbacks object has some input for the engine, it can call the ReturnInput method of any client. Once the ReturnInput method has been called, the engine will not take any more input. Subsequent callers of this method will be informed that the input was not received.
The engine will then call IDebugInputCallbacks::EndInput to indicate that it has stopped waiting for input.
Finally, the engine will echo this input to the registered IDebugOutputCallbacks object of every client (except the one used to provide the input) by using IDebugOutputCallbacks::Output with the bit-mask set to DEBUG_OUTPUT_PROMPT.
Output may be sent to the engine using several client methods — for example Output and OutputVaList. Upon receiving output, the engine sends it to some clients.
Clients use an output mask to indicate which types of output they are interested in. Whenever output is produced by the engine, it is accompanied by a mask specifying its output type. If the type of output matches the output mask of the client, the client will receive the output. The output mask may be set by calling SetOutputMask and queried using GetOutputMask. See DEBUG_OUTPUT_XXX for details of the output mask values.
The list of clients that the engine will send output to is controlled by the output control. Typically, the output control is set to send output to all clients; however, it can be temporarily changed using ControlledOutput and ControlledOutputVaList. See DEBUG_OUTCTL_XXX for details about output control values.
Output may be buffered by the engine. If multiple pieces of output are passed to the engine, it may collect them and send them to the clients in one large piece. To flush this buffer, use FlushCallbacks.
Each client object has an output width, which is the width of the output display for the client object. While this width is only used as a hint, some commands and extension functions format their output based on this width. The width is returned by the GetOutputWidth method and can be set using the SetOutputWidth method.
When the engine sends output to a client, it uses the IDebugOutputCallbacks object registered with the client. An IDebugOutputCallbacks object may be registered with a client using SetOutputCallbacks. Each client can have at most one IDebugInputCallbacks object registered with it.
To send the output, the engine calls the IDebugOutputCallbacks::Output method.
Each client object has an output line prefix which is prepended to every line of output sent to the output callback associated with the client object. This can be used for indentation or to place identifying marks on each line of output.
The output line prefix is returned by GetOutputLinePrefix and can be set using SetOutputLinePrefix. To temporarily change the output line prefix and later change it back again, use PushOutputLinePrefix and PopOutputLinePrefix.
The debugger engine supports opening a log file to record a debugging session. At most, one log file can be open at a time. Output sent to the output callbacks is also sent to this log file (unless it is flagged to not be logged).
To open a log file, use OpenLogFile2 (or OpenLogFile). The method GetLogFile2 (or GetLogFile) returns the currently open log file. To close the log file, use CloseLogFile.
The method SetLogMask can be used to filter the output sent to the log file, and GetLogMask will return the current log file filter.
In an interactive debugging session, a prompt can be used to indicate to the user that the debugger is waiting for user input. The prompt is sent to the output callbacks using the OutputPrompt and OutputPromptVaList methods. The contents of the standard prompt are returned by GetPromptText.