Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

ITextStoreAnchor::RequestLock method

Syntax


HRESULT RequestLock(
  [in]   DWORD dwLockFlags,
  [out]  HRESULT *phrSession
);

Parameters

dwLockFlags [in]

Specifies the type of lock requested.

ValueMeaning
TS_LF_READ

The document has a read-only lock and cannot be modified.

TS_LF_READWRITE

The document has a read/write lock and can be modified.

TS_LF_SYNC

The document has a synchronous-lock if this flag is combined with other flags.

 

phrSession [out]

If the lock request is synchronous, receives an HRESULT value from the ITextStoreAnchorSink::OnLockGranted method that specifies the result of the lock request.

If the lock request is asynchronous and the result is TS_S_ASYNC, the document receives an asynchronous lock. If the lock request is asynchronous and the result is TS_E_SYNCHRONOUS, the document cannot be locked synchronously.

Return value

This method can return one of these values.

ValueDescription
S_OK

The method was successful.

E_FAIL

An unspecified error occurred.

 

Remarks

This method uses the ITextStoreAnchorSink::OnLockGranted method to lock the document. Applications must never modify the document or send change notifications using the ITextStoreAnchorSink::OnTextChange method from within the ITextStoreAnchor::RequestLock method. If the application has pending changes to report, the application can only respond to the asynchronous lock request.

Applications should not attempt to queue multiple ITextStoreAnchor::RequestLock method calls, because the application requires only a single callback. If the caller makes several read requests and one or more write requests, however, the callback should be for write access.

Successful requests for synchronous locks supersede requests for asynchronous locks. Unsuccessful requests for synchronous locks do not supersede requests for asynchronous locks. The implementation must still serve the outstanding asynchronous request, if one exists.

If the lock is granted before the ITextStoreAnchor::RequestLock method returns, the phrSession parameter will receive the HRESULT returned by the ITextStoreAnchorSink::OnLockGranted method. If the call is successful, but the lock will be granted later, the phrSession parameter receives the TS_S_ASYNC flag. The phrSession parameter should be ignored if ITextStoreAnchor::RequestLock returns anything other than S_OK.

A caller should never call this method reentrantly, except in the case that the caller holds a read-only lock. In this case the method can be called reentrantly to ask for an asynchronous write lock. The write lock will be granted later, after the read-only lock ends.

For more information about document locks, see Document Locks.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Redistributable

TSF 1.0 on Windows 2000 Professional

Header

Textstor.h

IDL

Textstor.idl

DLL

Msctf.dll

See also

ITextStoreAnchor
Document Locks
ITextStoreAnchorSink::OnLockGranted
TS_LF_* Constants
Text Store Return Values

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.