IVsRunningDocumentTable::FindAndLockDocument Method (UInt32, String^, IVsHierarchy^, UInt32, IntPtr, UInt32)

Visual Studio 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 (in Microsoft.VisualStudio.Shell.Interop.dll)

C#
C++
F#
VB
Copy 
int FindAndLockDocument(
	unsigned int dwRDTLockType,
	String^ pszMkDocument,
	[OutAttribute] IVsHierarchy^% ppHier,
	[OutAttribute] unsigned int% pitemid,
	[OutAttribute] IntPtr% ppunkDocData,
	[OutAttribute] unsigned int% pdwCookie
)

Parameters

dwRDTLockType
Type: System::UInt32

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

pszMkDocument
Type: System::String^

[in] Path to the located document.

ppHier
Type: Microsoft.VisualStudio.Shell.Interop::IVsHierarchy^

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

pitemid
Type: System::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.

ppunkDocData
Type: System::IntPtr

[out, optional] Returns the IUnknown interface. See Remarks for details.

pdwCookie
Type: System::UInt32

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

Return Value

Type: System::Int32

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

FindAndLockDocumentEx is similar to this method 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 order to avoid a memory leak, you should call M:System.Runtime.InteropServices.Marshal.Release on the ppunkDocData object returned by this method.

From vsshell.idl:

C++
Copy 
HRESULT IVsRunningDocumentTable::FindAndLockDocument(
   [in] VSRDTFLAGS      dwRDTLockType,
   [in] LPCOLESTR       pszMkDocument,
   [out] IVsHierarchy **ppHier,
   [out] VSITEMID      *pitemid,
   [out] IUnknown     **ppunkDocData,
   [out] VSCOOKIE      *pdwCookie
);

If the document is registered, then the punkDocData value that is returned is always non-null because the environment will create a punkDocData on behalf of Editors that registered with a null value for punkDocData, as is the case when an Editor does not have data/view separation. This object represents the document data object associated with the registered document. Typically, the IVsPersistDocData and IVsDocDataFileChangeControl interfaces are obtained from this IUnknown object.

The pdwCookie parameter returns a cookie representing the document. This cookie can be passed to the following methods:

Return to top
Show: