This documentation is archived and is not being maintained.

IVsRunningDocumentTable.FindAndLockDocument Method

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)

int FindAndLockDocument (
	[InAttribute] uint dwRDTLockType,
	[InAttribute] string pszMkDocument,
	out IVsHierarchy ppHier,
	out uint pitemid,
	out IntPtr ppunkDocData,
	out uint pdwCookie
)
int FindAndLockDocument (
	/** @attribute InAttribute() */ UInt32 dwRDTLockType, 
	/** @attribute InAttribute() */ String pszMkDocument, 
	/** @attribute OutAttribute() */ /** @ref */ IVsHierarchy ppHier, 
	/** @attribute OutAttribute() */ /** @ref */ UInt32 pitemid, 
	/** @attribute OutAttribute() */ /** @ref */ IntPtr ppunkDocData, 
	/** @attribute OutAttribute() */ /** @ref */ UInt32 pdwCookie
)
JScript does not support passing value-type arguments by reference.

Parameters

dwRDTLockType

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

pszMkDocument

[in] Path to the located document.

ppHier

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

pitemid

[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

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

pdwCookie

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

Return Value

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

COM Signature

From vsshell.idl:

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

punkDocData Parameter

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 a null reference (Nothing in Visual Basic) 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.

pdwCookie Parameter

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

Show: