KnownStructOutput

The engine calls the KnownStructOutput callback function once after the DLL is initialized to obtain a list of structures the DLL can print, and again each time the engine wants to print a summary of one of these structures.

HRESULT
CALLBACK
  KnownStructOutput (
    IN ULONG  Flag,
    IN ULONG64  Address,
    IN PSTR  StructName,
    OUT PSTR  Buffer,
    IN OUT PULONG  BufferSize
    );

Parameters

Flag

Can be either of the following values, depending on which action the engine wants the function to perform.

Value	Description
DEBUG_KNOWN_STRUCT_GET_NAMES	Get a list of names of known structures.
DEBUG_KNOWN_STRUCT_GET_SINGLE_LINE_OUTPUT	Format a structure for printing on a single line.

Address

When getting names: Unused.

When printing a structure: Specifies the location in the target's memory address space of the structure to be printed.

StructName

When getting names: Unused.

When printing a structure: Specifies the name of the structure to be printed. This is one of the names returned from the DEBUG_KNOWN_STRUCT_GET_NAMES query.

Buffer

When getting names: Receives a list of the names of each structure that the extension knows how to print. One null character must appear between each pair of names. The list must be terminated with two null characters.

When printing a structure: Receives a representation of the structure, identified by StructName and Address, as a string.

In each case, the number of characters written to this buffer must not exceed the value of BufferSize.

BufferSize

Specifies the size in characters of the buffer Buffer.

When getting names: If the buffer is too small to contain the list of names, this should return the required size of the buffer.

Return Value

S_OK

Buffer contains the requested information.

S_FALSE

When getting names: BufferSize was too small. Its new value is the size required to hold the list of structure names. The engine will call the function again passing in a new buffer of this size.

All other return values indicate that the function failed. The engine will continue ignoring the contents of Buffer.

Comments

This function is optional. An extension DLL only needs to export KnownStructOutput if it has the ability to format special structures for printing on a single line. The engine looks for this function by name in the extension DLL.

After initializing the extension DLL, the engine calls this function to query the DLL for the list of structure names it knows how to print. Then, whenever the engine prints a summary of one of the structures whose name is in the list, it calls this function to format the structure for printing.

Requirements

Headers: The function type is defined as PDEBUG_EXTENSION_KNOWNSTRUCT in dbgeng.h.

See Also

DebugExtensionInitialize