IVsRunningDocumentTable2::FindOrRegisterAndLockDocument Method (UInt32, String^, IVsHierarchy^, UInt32, IntPtr, IVsHierarchy^, UInt32, IntPtr, UInt32)
Adds a lock to a registered or unregistered document.
Assembly: Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)
int FindOrRegisterAndLockDocument( unsigned int grfRDTLockType, String^ pszMkDocument, IVsHierarchy^ pHierPreferred, unsigned int itemidPreferred, IntPtr punkDocData, [OutAttribute] IVsHierarchy^% ppHierActual, [OutAttribute] unsigned int% pitemidActual, [OutAttribute] IntPtr% ppunkDocDataActual, [OutAttribute] unsigned int% pdwCookie )
Parameters
- grfRDTLockType
-
Type:
System::UInt32
[in] Flags whose values are taken from the _VSRDTFLAGS enumeration.
- pszMkDocument
-
Type:
System::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:
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.
- punkDocData
-
Type:
System::IntPtr
[out, optional] Returns the IUnknown interface.
- ppHierActual
-
Type:
Microsoft.VisualStudio.Shell.Interop::IVsHierarchy^
[out, optional] Returns the actual IVsHierarchy interface for the located document.
- pitemidActual
-
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.
- ppunkDocDataActual
-
Type:
System::IntPtr
[out, optional] Returns the IUnknown interface.
- pdwCookie
-
Type:
System::UInt32
[out, optional] Returns an abstract value for the document.
Return Value
Type: System::Int32If the method succeeds, it returns S_OK. If it fails, it returns an error code.
This method handles all cases to add a lock to a document whether the document is already registered or not. This is a convenience method that combines the functionality of RegisterAndLockDocument and FindAndLockDocumentEx. RegisterAndLockDocument returns an error if the document is already registered. FindAndLockDocumentEx returns an error if it is not registered. In the case where an RDT_EditLock is desired and the document is currently registered only with a RDT_ReadLock with no pHier/itemid assigned, this function will assign the preferred pHier/itemid to the document.
From vsshell80.idl:
HRESULT FindOrRegisterAndLockDocument(
[in] VSRDTFLAGS grfRDTLockType,
[in] LPCOLESTR pszMkDocument,
[in] IVsHierarchy *pHierPreferred,
[in] VSITEMID itemidPreferred,
[in] IUnknown *punkDocData,
[out] IVsHierarchy **ppHierActual,
[out] VSITEMID *pitemidActual,
[out] IUnknown **ppunkDocDataActual,
[out] VSCOOKIE *pdwCookie
);