IVsHierarchy.GetCanonicalName Method

Article
05/06/2010

Returns a unique, string name for an item in the hierarchy. Used for workspace persistence, such as remembering window positions.

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop (in Microsoft.VisualStudio.Shell.Interop.dll)

Syntax

'Déclaration
Function GetCanonicalName ( _
    itemid As UInteger, _
    <OutAttribute> ByRef pbstrName As String _
) As Integer
'Utilisation
Dim instance As IVsHierarchy
Dim itemid As UInteger
Dim pbstrName As String
Dim returnValue As Integer

returnValue = instance.GetCanonicalName(itemid, _
    pbstrName)

int GetCanonicalName(
    uint itemid,
    out string pbstrName
)

int GetCanonicalName(
    [InAttribute] unsigned int itemid, 
    [OutAttribute] String^% pbstrName
)

abstract GetCanonicalName : 
        itemid:uint32 * 
        pbstrName:string byref -> int

function GetCanonicalName(
    itemid : uint, 
    pbstrName : String
) : int

Parameters

itemid
Type: System.UInt32
[in] Identifier of the hierarchy item. For a list of itemid values, see VSITEMID.

pbstrName
Type: System.String%
[out] Pointer to the canonical name of the hierarchy item.

Return Value

Type: System.Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

A hierarchy is an object that contains many items, but does not necessarily contain an object for each of those items. Thus, to get information about any of the hierarchy items, you need to query the hierarchy object for that information. The item identifier (itemid) is used to identify the requested item in that query. Using the GetCanonicalName method, you pass in the itemid and the canonical name is returned. The canonical name is a unique name used to distinguish a particular item in the hierarchy from every other item in the hierarchy.

Canonical names do not change between sessions of the environment, but item identifiers do. Use this method to manage workspace persistence, such as remembering window positions.

Notes

The environment typically calls this method, but it can be called by anyone with a hierarchy object and a particular item identifier.

Use ParseCanonicalName to determine an item identifier (item ID), given the canonical name for an item.

COM Signature

From vsshell.idl:

HRESULT IVsHierarchy::GetCanonicalName(
   [in] VSITEMID itemid,
   [out] BSTR *pbstrName
);

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Partager via