Debug Property InterfacesDebug Property Interfaces*
*Contents  *Index  *Topic Contents
*Previous Topic: Active Script Debugging Interfaces

Debug Property Interfaces

This document describes the following interfaces used to examine debugging properties:

IDebugProperty;

IDebugExtendedProperty;

IEnumDebugPropertyInfo;

IEnumDebugExtendedPropertyInfo;

IPerPropertyBrowsing2;

IDebugProperty Intro

The IDebugProperty interface provides a language-neutral way to browse entities such as:

IDebugProperty is not intended to be a general replacement for ITypeInfo. For example, it does not include enough low-level information to construct vtable calls or implement IDispatch.

Instead, IDebugProperty is intended to provide human-readable information to allow IDE users to browse and modify objects at design or run-time. Because of this more limited scope, IDebugProperty is much easier to use and to implement than ITypeInfo.

One example of how IDebugProperty can be used is to get a root IDebugProperty from a given stack frame (this IDebugProperty actually represents that stack frame). The members of this root IDebugProperty are the local variables and method parameters, and can be retrieved by calling IDebugProperty::EnumMembers followed by IEnumDebugPropertyInfo::Next. Next returns an array of DebugPropertyInfo structures that contains all the info generally displayed by IDEs in a variables window: name, type, value, etc, as well as attributes that specify if a property is expandable, among other things.

The IDebugProperty interface could also be used to represent registers, memory, or whatever.

The majority of consumers of this interface will be interested only in the IDebugProperty and IEnumDebugPropertyInfo interfaces and will probably want to ignore IDebugExtendedProperty and IEnumDebugExtendedProperty.

INTERFACE NOTES:

===============

Run-time type vs. declared type

The type of a DebugProperty can be determined via two methods. When the type is obtained via GetPropertyInfo, the type is the run-time type. However, when the type obtained via a GetMemberEnum on the parent, the type is the declared type. In other words, object ‘A’ will give you its run-time type, but A’s parent will give you A’s declared type.

enum

{

// -----------------------------------------------------------------------

// OBJECT ATTRIBUTES

DBGPROP_ATTRIB_NO_ATTRIB = 0x00000000,

// ---------------------

// Characteristics

DBGPROP_ATTRIB_VALUE_IS_INVALID = 0x00000008, // the value in this slot is invalid

DBGPROP_ATTRIB_VALUE_IS_EXPANDABLE =0x00000010, // the object has children

DBGPROP_ATTRIB_VALUE_READONLY = 0x00000800, // the value is read-only

// ---------------------

// Attributes about a slot's type

// ---------------------

// Common attributes

// field access control

DBGPROP_ATTRIB_ACCESS_PUBLIC = 0x00001000,

DBGPROP_ATTRIB_ACCESS_PRIVATE = 0x00002000,

DBGPROP_ATTRIB_ACCESS_PROTECTED = 0x00004000,

DBGPROP_ATTRIB_ACCESS_FINAL = 0x00008000,

// storage types

DBGPROP_ATTRIB_STORAGE_GLOBAL = 0x00010000,

DBGPROP_ATTRIB_STORAGE_STATIC = 0x00020000,

DBGPROP_ATTRIB_STORAGE_FIELD = 0x00040000,

// type modifiers

DBGPROP_ATTRIB_STORAGE_VIRTUAL = 0x00080000, // this slot is virtual

DBGPROP_ATTRIB_TYPE_IS_CONSTANT = 0x00100000, // this slot is a constant value

DBGPROP_ATTRIB_TYPE_IS_SYNCHRONIZED =0x00200000, // this slot is thread synchronized

DBGPROP_ATTRIB_TYPE_IS_VOLATILE = 0x00400000, // this slot is volatile storage

DBGPROP_ATTRIB_HAS_EXTENDED_ATTRIBS =0x00800000 // has more attributes

};

typedef DWORD DBGPROP_ATTRIB_FLAGS;

// -----------------------------------------------------------------------

// DebugPropertyInfo

// Basic info that all IDebugProperty implementations must support

enum

{

// Flags used to specify DebugPropertyInfo (and ExtendedDebugPropertyInfo) fields

DBGPROP_INFO_NAME = 0x001, // init the bstrName field

DBGPROP_INFO_TYPE = 0x002, // init the bstrType field

DBGPROP_INFO_VALUE = 0x004, // init the bstrValue field

DBGPROP_INFO_FULLNAME = 0x020, // init the full name field

DBGPROP_INFO_ATTRIBUTES = 0x008, // init the dwAttrib field

DBGPROP_INFO_DEBUGPROP = 0x010, // init the pDebugProp field

DBGPROP_INFO_AUTOEXPAND = 0x8000000 // make the Value result auto-expand

};

typedef DWORD DBGPROP_INFO_FLAGS;

const DBGPROP_INFO_FLAGS DBGPROP_INFO_STANDARD =

DBGPROP_INFO_NAME |

DBGPROP_INFO_TYPE |

DBGPROP_INFO_VALUE |

DBGPROP_INFO_ATTRIBUTES;

const DBGPROP_INFO_FLAGS DBGPROP_INFO_ALL =

DBGPROP_INFO_NAME |

DBGPROP_INFO_TYPE |

DBGPROP_INFO_VALUE |

DBGPROP_INFO_FULLNAME |

DBGPROP_INFO_ATTRIBUTES |

DBGPROP_INFO_DEBUGPROP;

typedef struct tagDebugPropertyInfo

{

DBGPROP_INFO_FLAGS m_dwValidFields; // which DebugPropertyInfo fields were successfully initialized

BSTR m_bstrName; // property name

BSTR m_bstrType; // property type, as formatted string

BSTR m_bstrValue; // property value, as formatted string

BSTR m_bstrFullName; // property's full name, like pObject->m_fFlag

DBGPROP_ATTRIB_FLAGS m_dwAttrib; // property attributes (ORed DBGPROP_ATTRIB_* above)

IDebugProperty* m_pDebugProp; // IDebugProperty object corresponding to this DebugPropertyInfo

} DebugPropertyInfo;

// -----------------------------------------------------------------------

// Extended info that some IDebugProperty implementations support

enum

{

// Flags used to specify ExtendedDebugPropertyInfo fields

EX_DBGPROP_INFO_ID = 0x0100, // init the nDISPID field

EX_DBGPROP_INFO_NTYPE = 0x0200, // init the nType field

EX_DBGPROP_INFO_NVALUE = 0x0400, // init the varValue field

EX_DBGPROP_INFO_LOCKBYTES = 0x0800, // init the plb field

EX_DBGPROP_INFO_DEBUGEXTPROP = 0x1000, // init the pDebugExtProp field

};

typedef DWORD EX_DBGPROP_INFO_FLAGS;

typedef struct tagExtendedDebugPropertyInfo

{

// members from DebugPropertyInfo

DBGPROP_INFO_FLAGS m_dwValidFields; // which ExtendedDebugPropertyInfo fields were successfully initialized

LPOLESTR m_bstrName; // property name

LPOLESTR m_bstrType; // property type, as formatted string

LPOLESTR m_bstrValue; // property value, as formatted string

LPOLESTR m_bstrFullName; // property's full name, like pObject->m_fFlag

DBGPROP_ATTRIB_FLAGS m_dwAttrib; // property attributes (ORed DBGPROP_ATTRIB_* above)

IDebugProperty* m_pDebugProp; // IDebugProperty object corresponding to this DebugPropertyInfo

// extra members

DWORD m_nDISPID; // DISPID of this child (DISPID_NIL, if n/a or none)

DWORD m_nType; // property type

VARIANT m_varValue; // property value (if value can physically fit in VARIANT)

ILockBytes* m_plbValue; // property value (actual data bytes)

IDebugExtendedProperty* m_pDebugExtProp; // IDebugExtendedProperty object corresponding to this DebugPropertyInfo

} ExtendedDebugPropertyInfo;

// -----------------------------------------------------------------------

// IDebugProperty

[

object,

uuid(51973C50-CB0C-11d0-B5C9-00A0244A0E7A),,

pointer_default(unique)

]

interface IDebugProperty : IUnknown

{

// Get Information for this object

// By setting various PROPERTY_INFO_FLAGS, any subset of the basic info

// contained in DebugPropertyInfo can be fetched

HRESULT GetPropertyInfo(

[in] DBGPROP_INFO_FLAGS dwFieldSpec,

[in] UINT nRadix,

[out] DebugPropertyInfo* pPropertyInfo);

// Get ExtendedInfo for this object. This API only exists for the purpose

// of retrieving info that does not lend itself to being retrieved via the

// standard means (i.e. using DebugPropertyInfo)

//

// An array of GUIDs and result VARIANTs is passed so that multiple items

// of extended info can be fetched at the same time. If a variant cannot

// be initialized for some reason, the vt field should be set to VT_ERROR.

// The currently defined extended info guids are described below.

// A QI is typically required to obtain interfaces on the right from

// IUnknowns in the variant.

// GUID VALUE

//

// guidDefinitionContext IDebugDocumentContext2

// ISSUE: Add additional GUIDS, such as:

// <guidSomeRandomBSTR> BSTR

// <guidSomeRandomI4> I4

HRESULT GetExtendedInfo(

[in] ULONG cInfos,

[in, size_is(cInfos)] GUID* rgguidExtendedInfo,

[out, size_is(cInfos)] VARIANT* rgvar);

// Set the value of this object as a string

HRESULT SetValueAsString(

[in] LPCOLESTR pszValue,

[in] UINT nRadix);

// Get enumerator for props of members

HRESULT EnumMembers(

[in] DBGPROP_INFO_FLAGS dwFieldSpec,

[in] UINT nRadix,

[in] REFIID refiid,

[out] IEnumDebugPropertyInfo **ppepi);

// Get the parent property

HRESULT GetParent(

[out] IDebugProperty **ppDebugProp);

};

[

object,

uuid(51973C51-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IEnumDebugPropertyInfo : IUnknown

{

// Enumerate information for sub-objects

// get the next celt elements, if possible

[local]

HRESULT Next(

[in] ULONG celt,

[out] DebugPropertyInfo *pi,

[out] ULONG *pcEltsfetched

);

// Skip the next celt slots

HRESULT Skip(

[in] ULONG celt);

// Restart from the beginning

HRESULT Reset(void);

// Clone this property browser at the current enumeration state

HRESULT Clone(

[out] IEnumDebugPropertyInfo **ppepi);

// Get the number of elements in the enumerator

HRESULT GetCount(

[out] ULONG* pcelt);

};

Note: The IDebugExtendedProperty is QI’able from an IDebugProperty, and contains more information than the simpler IDebugProperty.

[

object,

uuid(51973C52-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IDebugExtendedProperty : IDebugProperty

{

// Get Information for this object

// By setting various EXPROPERTY_INFO_FLAGS and PROPERTY_INFO_FLAGS,

// any subset of the basic info contained in ExtendedDebugPropertyInfo

// can be fetched

HRESULT GetExtendedPropertyInfo(

[in] EX_DBGPROP_INFO_FLAGS dwFieldSpec,

[in] UINT nRadix,

[out] ExtendedDebugPropertyInfo *pExtendedPropertyInfo);

// Get enumerator for props of members

HRESULT EnumExtendedMembers(

[in] EX_DBGPROP_INFO_FLAGS dwFieldSpec,

[in] UINT nRadix,

[out] IEnumDebugExtendedPropertyInfo **ppeepi);

};

[

object,

uuid(51973C53-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IEnumDebugExtendedPropertyInfo : IUnknown

{

// Enumerate information for sub-objects

// Get the next celt elements, if possible

HRESULT Next(

[in] ULONG celt,

[out, size_is(celt), length_is(*pceltFetched)] ExtendedDebugPropertyInfo *rgExtendedPropertyInfo,

[out] ULONG *pceltFetched);

// Skip the next celt slots

HRESULT Skip(

[in] ULONG celt);

// Restart from the beginning

HRESULT Reset(void);

// Clone this property browser at the current enumeration state

HRESULT Clone(

[out] IEnumDebugExtendedPropertyInfo **pedpe);

// Get the number of elements in the enumerator

HRESULT GetCount(

[out] ULONG* pcelt);

};

[

object,

uuid(51973C54-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IPerPropertyBrowsing2 : IUnknown

{

// Get a string to display for those types which are inheritly non-viewable

// Note: The returned string is *not* a legal value for the property,

// just an indication to the user of what the property is.

HRESULT GetDisplayString(

[in] DISPID dispid,

[out] BSTR *pBstr);

// Return the CLSID of the property page which can be used to edit this

// property.

HRESULT MapPropertyToPage(

[in] DISPID dispid,

[out] CLSID *pClsidPropPage);

// These methods allow the caller to fill a listbox with a set of strings

// which _represent_ potential values for this property. When an item

// is chosen, the cookie is passed back to the object, so that the object

// can set itself to the corresponding value.

HRESULT GetPredefinedStrings(

[in] DISPID dispid,

[out] CALPOLESTR *pCaStrings,

[out] CADWORD *pCaCookies);

HRESULT SetPredefinedValue(

[in] DISPID dispid,

[in] DWORD dwCookie);

};

// the IDebugPropertyEnumType interfaces are really defined for their IIDs,

// we have no need currently to *implement* any of them, but we might one day

// These IIDs are passed to EnumMembers for filtering the enumerator.

[

object,

uuid(51973C55-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IDebugPropertyEnumType_All : IUnknown

{

HRESULT GetName([out] BSTR *);

};

[

object,

uuid(51973C56-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IDebugPropertyEnumType_Locals : IDebugPropertyEnumType_All

{

};

[

object,

uuid(51973C57-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IDebugPropertyEnumType_Arguments : IDebugPropertyEnumType_All

{

};

[

object,

uuid(51973C58-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IDebugPropertyEnumType_LocalsPlusArgs : IDebugPropertyEnumType_All

{

};

[

object,

uuid(51973C59-CB0C-11d0-B5C9-00A0244A0E7A),

pointer_default(unique)

]

interface IDebugPropertyEnumType_Registers : IDebugPropertyEnumType_All

{

};

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.