IDebugFAEntryTags::GetTagByName method (extsfns.h)

Article
10/21/2021

The GetTagByName method searches for a tag that has a specified name.

Syntax

HRESULT GetTagByName(
  [in]  PCSTR  PluginId,
  [in]  PCSTR  TagName,
  [out] FA_TAG *Tag
);

Parameters

[in] PluginId

A pointer to a null-terminated string that specifies the identifier of an analysis extension plug-in. This parameter can be NULL.

[in] TagName

A pointer to a null-terminated string that specifies the name to search for.

[out] Tag

A pointer to a variable that receives either a value in the FA_TAG enumeration or the value of a custom tag. If this method does not find a tag that has the specified name, nothing is written to this parameter.

Return value

If this method finds a tag that has the specified name, it returns S_OK. Otherwise it returns a failure code.

Remarks

A DebugFailureAnalysis object has a collection of FA entries, each of which has a tag. A DebugFailureAnalysis object is associated with a DebugFailureAnalysisTags, which contains a collection of tag properties. Also, the analysis engine has a global tag table. For more information, see Failure Analysis Entries, Tags, and Data Types.

If you specify a PluginId, this method does the following:

In the DebugFailureAnalysisTags object, search the collection of tag properties for a tag whose name matches TagName and whose plug-in id matches the PluginId. Note that this limits the search to custom tags created by the analysis extension plug-in identified by PluginId. If a match is found, return the tag in the Tag output parameter.
If a match is not found in the DebugFailureAnalysisTags object, search the global tag table for a tag whose name matches TagName. If a matching name is found, add the found tag to the DebugFailureAnalysisTags collection of tag properties, and return the tag in the Tag output parameter.
If a match is not found in the global tag table, write nothing to the Tag output parameter, and return a failure code.

If you call this method from an analysis extension plug-in, and you set PluginId to NULL, this method uses the plug-in identifier of the current plug-in. Then it behaves the same way that it does when a non-NULL PluginId is specified.

Requirements

Requirement	Value
Target Platform	Desktop
Header	extsfns.h