IDebugFailureAnalysis2::AddExtensionCommand method (extsfns.h)

Article
08/10/2023

The AddExtensionCommand method adds a new FA entry to a DebugFailureAnalysis object and sets the data block of the FA entry to a specified debugger command.

Syntax

PFA_ENTRY AddExtensionCommand(
       FA_TAG Tag,
  [in] PCSTR  Extension
);

Parameters

Tag

A value in the FA_TAG enumeration. The data type associated with this tag must be DEBUG_FA_ENTRY_EXTENSION_CMD or DEBUG_FA_ENTRY_ANSI_STRING.

[in] Extension

A pointer to a null-terminated ANSI string that is the debugger command. An example of debugger command is "!analyze -v".

Return value

If this method succeeds, it returns a returns a pointer to the new FA_ENTRY structure. If this method fails, it returns NULL.

Remarks

This method sets the DataSize member of the new FA_ENTRY structure to the length, in bytes, of the extension command including the NULL terminator.

Each tag is associated with one of the data types in the FA_ENTRY_TYPE enumeration. To determine the data type associated with a tag, call the GetType method of the IDebugFAEntryTags interface.

To get a pointer to an IDebugFAEntryTags interface, call the GetDebugFATagControl method of the IDebugFailureAnalysis2 interface.

[sperry] Note to Self: If the given tag has not already had its data type fixed, this method sets and fixes the data type for the tag. That would be the case if the DebugFailureAnalysis object does not yet have an FA entry with this tag. But if the DebugFailureAnalysis object already has an FA entry with this tag, then the data type of the tag is fixed. This method creates a new FA entry with the same tag. Now what if the data type that we're trying to write into the new data buffer does not match the data type that has been fixed for this tag. Then we see whether it's OK to cast from the fixed data type to the type we want to write.

It's OK to cast among ULONG64, POINTER, and InstructionOffset. It's OK to cast among String and ExtensionCommand. ULONG can only be ULONG. STRINGs can only be STRINGs.

Question: When does the data type of a tag get fixed? Is it when the first FA entry with that tag is created?

typedef struct _FA_TAG_PROPS
{
    FA_TAG Tag;
    FA_ENTRY_TYPE Type;
    ULONG Fixed:1;
    ULONG NameAllocated:1;
    ULONG DescriptionAllocated:1;
    PCSTR Name;
    PCSTR Description;
    AnalysisPlugIn *Plugin;
} FA_TAG_PROPS, *PFA_TAG_PROPS;

Requirements

Requirement	Value
Target Platform	Desktop
Header	extsfns.h