IVsRunningDocumentTable2.FindAndLockDocumentEx Method

Article
04/29/2015

Locates a document in the RDT using the document file name, then obtains a read or edit lock on that document.

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

Syntax

'Declaration
Function FindAndLockDocumentEx ( _
    grfRDTLockType As UInteger, _
    pszMkDocument As String, _
    pHierPreferred As IVsHierarchy, _
    itemidPreferred As UInteger, _
    <OutAttribute> ByRef ppHierActual As IVsHierarchy, _
    <OutAttribute> ByRef pitemidActual As UInteger, _
    <OutAttribute> ByRef ppunkDocDataActual As IntPtr, _
    <OutAttribute> ByRef pdwCookie As UInteger _
) As Integer

int FindAndLockDocumentEx(
    uint grfRDTLockType,
    string pszMkDocument,
    IVsHierarchy pHierPreferred,
    uint itemidPreferred,
    out IVsHierarchy ppHierActual,
    out uint pitemidActual,
    out IntPtr ppunkDocDataActual,
    out uint pdwCookie
)

int FindAndLockDocumentEx(
    [InAttribute] unsigned int grfRDTLockType, 
    [InAttribute] String^ pszMkDocument, 
    [InAttribute] IVsHierarchy^ pHierPreferred, 
    [InAttribute] unsigned int itemidPreferred, 
    [OutAttribute] IVsHierarchy^% ppHierActual, 
    [OutAttribute] unsigned int% pitemidActual, 
    [OutAttribute] IntPtr% ppunkDocDataActual, 
    [OutAttribute] unsigned int% pdwCookie
)

abstract FindAndLockDocumentEx : 
        grfRDTLockType:uint32 * 
        pszMkDocument:string * 
        pHierPreferred:IVsHierarchy * 
        itemidPreferred:uint32 * 
        ppHierActual:IVsHierarchy byref * 
        pitemidActual:uint32 byref * 
        ppunkDocDataActual:IntPtr byref * 
        pdwCookie:uint32 byref -> int

function FindAndLockDocumentEx(
    grfRDTLockType : uint, 
    pszMkDocument : String, 
    pHierPreferred : IVsHierarchy, 
    itemidPreferred : uint, 
    ppHierActual : IVsHierarchy, 
    pitemidActual : uint, 
    ppunkDocDataActual : IntPtr, 
    pdwCookie : uint
) : int

Parameters

grfRDTLockType
Type: UInt32

[in] Flags whose values are taken from the _VSRDTFLAGS enumeration.

pszMkDocument
Type: String

[in] Path to the located document.

pHierPreferred
Type: Microsoft.VisualStudio.Shell.Interop.IVsHierarchy

[out, optional] Returns preferred the IVsHierarchy interface for the located document.

itemidPreferred
Type: UInt32

[out, optional] Returns an item identifier of the located document. This is a unique identifier or it can be one of the following values: VSITEMID_NIL, VSITEMID_ROOT, or VSITEMID_SELECTION.

ppHierActual
Type: Microsoft.VisualStudio.Shell.Interop.IVsHierarchy%

[out, optional] Returns the actual IVsHierarchy interface for the located document.

pitemidActual
Type: UInt32%

[out, optional] Returns an item identifier of the located document. This is a unique identifier or it can be one of the following values: VSITEMID_NIL, VSITEMID_ROOT, or VSITEMID_SELECTION.

ppunkDocDataActual
Type: IntPtr%

[out, optional] Returns the IUnknown interface.

pdwCookie
Type: UInt32%

[out, optional] Returns an abstract value for the document.

Return Value

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

Remarks

This method is similar to FindAndLockDocument but also allows the specification of a preferred hierarchy/itemid pair for the document in case an RDT_EditLock is desired and the document is currently registered with only a RDT_ReadLock with no hierarchy/itemid assigned. In this case FindAndLockDocument would have returned E_UNEXPECTED. This method will not register the document in the Running Document Table if it is not currently registered.

COM Signature

From vsshell80.idl:

HRESULT FindAndLockDocumentEx(
    [in] VSRDTFLAGS grfRDTLockType,
    [in] LPCOLESTR pszMkDocument,
    [in] IVsHierarchy *pHierPreferred,
    [in] VSITEMID itemidPreferred,
    [out] IVsHierarchy **ppHierActual,
    [out] VSITEMID *pitemidActual,
    [out] IUnknown **ppunkDocDataActual,
    [out] VSCOOKIE *pdwCookie
);

.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