Debugging Tools for Windows

ControlledOutput

The ControlledOutput and ControlledOutputWide methods format a string and send the result to output callbacks that were registered with some of the engine's clients.

HRESULT
  IDebugControl::ControlledOutput(
    IN ULONG  OutputControl,
    IN ULONG  Mask,
    IN PCSTR  Format,
    ...
    );

HRESULT
  IDebugControl4::ControlledOutputWide(
    IN ULONG  OutputControl,
    IN ULONG  Mask,
    IN PCWSTR  Format,
    ...
    );

#ifdef UNICODE
#define ControlledOutputT ControlledOutputWide
#else
#define ControlledOutputT ControlledOutput
#endif

Parameters

OutputControl

Specifies an output control that determines which of the clients' output callbacks will receive the output. For possible values, see DEBUG_OUTCTL_XXX. For more information about output, see Input and Output.

Mask

Specifies the output-type bit field. See DEBUG_OUTPUT_XXX for possible values.

Format

Specifies the format string, as in printf. Typically, conversion characters work exactly as they do in C. For the floating-point conversion characters, the 64-bit argument is interpreted as a 32-bit floating-point number unless the l modifier is used.

The %p conversion character is supported, but it represents a pointer in a target's address space. It might not have any modifiers and it uses the debugger's internal address formatting. The following additional conversion characters are supported.

Character	Argument type	Argument	Text printed
%p	ULONG64	Pointer in an address space.	The value of the pointer.
%N	DWORD_PTR (32 or 64 bits, depending on the host's architecture)	Pointer in the host's virtual address space.	The value of the pointer. (This is equivalent to the standard C %p character.)
%I	ULONG64	Any 64-bit value.	The specified value. If this is greater than 0xFFFFFFFF, it is printed as a 64-bit value; otherwise, it is printed as a 32-bit value.
%ma	ULONG64	Address of a NULL-terminated ASCII string in the process's virtual address space.	The specified string.
%mu	ULONG64	Address of a NULL-terminated Unicode string in the process's virtual address space.	The specified string.
%msa	ULONG64	Address of an ANSI_STRING structure in the process's virtual address space.	The specified string.
%msu	ULONG64	Address of a UNICODE_STRING structure in the process's virtual address space.	The specified string.
%y	ULONG64	Address in the process's virtual address space of an item with symbol information.	String that contains the name of the specified symbol (and displacement, if any).
%ly	ULONG64	Address in the process's virtual address space of an item with symbol information.	String that contains the name of the specified symbol (and displacement, if any), as well as any available source line information.

...

Specifies additional parameters that represent values to be inserted into the output during formatting.

Return Value

S_OK: The method was successful.

This method may also return error values. See Return Values for more details.

Interface Version

ControlledOutput is available in all versions of IDebugControl. ControlledOutputWide is available in IDebugControl4 and later versions.

Comments

When generating very large output strings, it is possible to reach the limits of the debugger engine or of the operating system. For example, some versions of the debugger engine have a 16K character limit for a single output. If you find that very large output is getting truncated, you might need to split your output into multiple requests.

Requirements