IVsRunningDocumentTable.FindAndLockDocument Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Locates a document in the RDT using the document file name, then obtains a read or edit lock on that document.
public:
int FindAndLockDocument(System::UInt32 dwRDTLockType, System::String ^ pszMkDocument, [Runtime::InteropServices::Out] Microsoft::VisualStudio::Shell::Interop::IVsHierarchy ^ % ppHier, [Runtime::InteropServices::Out] System::UInt32 % pitemid, [Runtime::InteropServices::Out] IntPtr % ppunkDocData, [Runtime::InteropServices::Out] System::UInt32 % pdwCookie);
public int FindAndLockDocument (uint dwRDTLockType, string pszMkDocument, out Microsoft.VisualStudio.Shell.Interop.IVsHierarchy ppHier, out uint pitemid, out IntPtr ppunkDocData, out uint pdwCookie);
abstract member FindAndLockDocument : uint32 * string * IVsHierarchy * uint32 * nativeint * uint32 -> int
Public Function FindAndLockDocument (dwRDTLockType As UInteger, pszMkDocument As String, ByRef ppHier As IVsHierarchy, ByRef pitemid As UInteger, ByRef ppunkDocData As IntPtr, ByRef pdwCookie As UInteger) As Integer
Parameters
- dwRDTLockType
- UInt32
[in] Flags whose values are taken from the _VSRDTFLAGS enumeration.
- pszMkDocument
- String
[in] Path to the located document.
- ppHier
- IVsHierarchy
[out, optional] Returns the IVsHierarchy interface for the located document.
- pitemid
- 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
-
IntPtr
nativeint
[out, optional] Returns the IUnknown
interface. See Remarks for details.
- pdwCookie
- UInt32
[out, optional] Returns an abstract value for the document.
Returns
If the method succeeds, it returns S_OK. If it fails, it returns an error code.
Remarks
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 Release on the ppunkDocData
object returned by this method.
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 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.
pdwCookie Parameter
The pdwCookie
parameter returns a cookie representing the document. This cookie can be passed to the following methods: