Document Locks
The Document Lock Protocol
To request a document lock for ACP-based applications, the TSF manager calls ITextStoreACP::RequestLock. For anchor-based applications, the TSF manager calls ITextStoreAnchor::RequestLock. The application grants the document lock by calling ITextStoreACPSink::OnLockGranted (ACP-based applications) or ITextStoreAnchorSink::OnLockGranted (anchor-based applications) inside of RequestLock. The lock is only valid during the OnLockGranted call. When OnLockGranted returns, the document is considered unlocked.
Types of Document Locks
There are two types of document locks, read-only and read/write. A read-only lock enables the manager to read the text, but it cannot modify or insert text. A read/write lock enables the manager to read, modify, and insert text. A read-only lock is requested by specifying TS_LF_READ in dwFlags. A read/write lock is requested by specifying TS_LF_READWRITE in dwFlags.
Asynchronous and Synchronous Requests
A lock request can be either synchronous or asynchronous. The manager requests a synchronous lock by using the TS_LF_SYNC flag in dwFlags. If this flag is not present, the request is asynchronous.
Granting the Lock
When RequestLock is called, the application must determine if the document is currently locked. If the document is not locked, and no other reason to deny the lock exists, the application should set phrSession to S_OK and return S_OK.
If the document is locked and the lock request is synchronous, the application should set phrSession to TS_E_SYNCHRONOUS and return S_OK. This indicates that a synchronous request cannot be granted.
If the document is locked and the lock request is asynchronous, the application should queue the request, set phrSession to TS_S_ASYNC and return S_OK. When the document becomes available, the application should remove the request from the queue and call OnLockGranted. This queuing of lock requests is optional; there is one scenario that an application must support. If the document has a read-only lock, the new lock request is read/write and the request is asynchronous, the application has called into OnLockGranted , which has caused a reentrant call to RequestLock. The application should set phrSession to TS_S_ASYNC and return S_OK. After the call to OnLockGranted returns, the application should process the upgrade request by calling OnLockGranted again with TS_LF_READWRITE.
Lock Enforcement
The application must ensure that the proper type of lock exists before allowing access to the document. For example, the application should verify that a document has at least a read-only lock before allowing ITextStoreACP::GetText or ITextStoreAnchor::GetText to proceed. If the proper lock does not exist, the application should return TF_E_NOLOCK.
Related topics