IVsUIHierarchy.GetNestedHierarchy Method

Article
03/06/2013

Makes it possible for a node of a given hierarchy to be a shortcut to the middle of another hierarchy.

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

Syntax

'Declaration
Function GetNestedHierarchy ( _
    itemid As UInteger, _
    ByRef iidHierarchyNested As Guid, _
    <OutAttribute> ByRef ppHierarchyNested As IntPtr, _
    <OutAttribute> ByRef pitemidNested As UInteger _
) As Integer

int GetNestedHierarchy(
    uint itemid,
    ref Guid iidHierarchyNested,
    out IntPtr ppHierarchyNested,
    out uint pitemidNested
)

int GetNestedHierarchy(
    [InAttribute] unsigned int itemid, 
    [InAttribute] Guid% iidHierarchyNested, 
    [OutAttribute] IntPtr% ppHierarchyNested, 
    [OutAttribute] unsigned int% pitemidNested
)

abstract GetNestedHierarchy : 
        itemid:uint32 * 
        iidHierarchyNested:Guid byref * 
        ppHierarchyNested:IntPtr byref * 
        pitemidNested:uint32 byref -> int

function GetNestedHierarchy(
    itemid : uint, 
    iidHierarchyNested : Guid, 
    ppHierarchyNested : IntPtr, 
    pitemidNested : uint
) : int

Parameters

itemid
Type: System.UInt32
[in] Item identifier of the node whose nested hierarchy information is requested. For a list of itemid values, see VSITEMID.

iidHierarchyNested
Type: System.Guid%
[in] Identifier of the interface to be returned in ppHierarchyNested. To implement, first get the object that represents the nested hierarchy and run IUnknown::QueryInterface on it to obtain the interface ID (IID). Then, pass the IID in with iidHierarchyNested. The result of the QueryInterface call goes into ppHierarchyNested.

ppHierarchyNested
Type: System.IntPtr%
[out, iid_is(iidHierarchyNested)] Pointer to the interface whose identifier was passed in iidHierarchyNested.

pitemidNested
Type: System.UInt32%
[out] Pointer to an item identifier of the root node of the nested hierarchy. For a list of pitemidnested values, see VSITEMID. Although the interface is set up to support shortcutting to any node in another hierarchy, the environment currently only supports shortcutting to the root node of the nested hierarchy, in which case pitemidNested must be set to VSITEMID_ROOT.

Return Value

Type: System.Int32
If itemid is not a nested hierarchy, this method returns E_FAIL. If the requested interface is not supported on the hierarchy object, E_NOINTERFACE is returned. The caller would then treat this node as if it had no children, if the requested interface had been essential (as is often the case when the requested interface is IID_IVsUIHierarchy).

Implements

IVsHierarchy.GetNestedHierarchy(UInt32, Guid%, IntPtr%, UInt32%)

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsUIHierarchy::GetNestedHierarchy(
   [in] VSITEMID itemid,
   [in] REFIID iidHierarchyNested,
   [out, iid_is(iidHierarchyNested)] void **ppHierarchyNested,
   [out] VSITEMID *pitemidNested
);

Hierarchies can nest within other hierarchies. For example, you can create a parent hierarchy named Hierarchy 1. If Hierarchy 1 contains two items, Item A and Item B, with Item B being a nested hierarchy (named Hierarchy 2) the nested hierarchy has two identifiers:

Item B in Hierarchy 1

Root of Hierarchy 2

Use the IVsHierarchy.GetNestedHierarchy method to determine if a given hierarchy is a nested hierarchy. In the example above, you would specify the itemid corresponding to Item B in Hierarchy 1, and the method would return the root of Hierarchy 2. This method allows you to have two different hierarchies for implementation reasons even though to the user the nested hierarchy looks like a child of the parent hierarchy.

If the return value is E_NOINTERFACE and the requested interface is essential, as is often the case when the requested interface is IID_IVsUIHierarchy, the caller treats this node as if it has no child nodes and is not a nested hierarchy.

With nested hierarchies, the parent hierarchy can override the behavior of any of its nested hierarchies. Thus, if a command is executed on an item in the nested hierarchy, the parent hierarchy is allowed first chance at responding to that command.

.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.

Share via