The Debug Interface Specification

Version 1.0

Introduction

The Debug Interface operates like an outline iterator. That is, a TDebug_Interface instance represents a line in an outline. It has zero or more children TDebug_Interface objects which represent all of the lines under this object, at the same level. And so on. The child objects are not actually created until asked for, and are deleted when the parent closes. Thus, the entire hierarchy can be represented with relatively little resource overhead, regardless of how many levels it has and how many items total. For instance, assume that a program has two modules, each of which has two objects. The debug information hierarchy might look like this:

Program
	Module 1
		Object 1
		Object 2
	Module 2
		Object 3
		Object 4

The program would provide a single debug interface object which provided two children debug objects (one for Module 1 and one for Module 2). Module 1's debug interface provides two children debug objects (Object 3and Object 4).

The parent/child relationship is not enforced by the specification, so it is possible to have Object 3 provide a debug interface for Module 2, if that is desired. This allows the person debugging the code to quickly navigate either way through the debug data.

TDebug_Interface object

The TDebug_Interface object has the following methods. Parameter and result types:

Type	C++ equivalent	Delphi/Kylix equivalent	Comments
Integer	int	Integer	4-byte signed.
String	char*	PChar	Strings returned by TDebug_Interface methods are only guaranteed to be valid until the next call to a TDebug_Interface method, and are read-only.
Boolean	bool	Boolean
Pointer	void*	Pointer

Integer Count() ;

Returns the number of child components under this level. If this is a terminal (leaf) node, the method returns 0.

String Get_Title() ;

Returns the title text representing this level (such as "Cached data").

void Set_Title( String Value ) ;

Sets the title text representing this level. Generally the returned child already has an appropriate title.

void Activate() ;

Indicates that the user wished to activate this level. The behavior is undefined and up to the implementor. Typically, this does nothing unless this level is a terminal representing some complex data which is not viewable in a hierarchical form.

Boolean Can_Change() ;

Returns True if this item can be modified.

TDebug_Interface* Child( Integer Index ) ;

Returns a debug interface for the specified child level (first child level is 0).

void procedure Kill() ;

Tells object to destroy itself.

String Modify( String Data, Integer Size ) ;

Modifies data. If Size is -1, Data is assumed to be null-terminated and its length is automatically determined. The result will be nil or a pointer to a null string to indicate success, and error text otherwise.