This .NET enumeration wraps the AcAp::DocLockMode ObjectARX enum.
Only a very small percentage of developers should be actively setting these modes. If you are one of them, here is a description of the ProtectedAutoWrite lock mode, and the problem it addresses.
AutoWrite has a simple implementation: a LockDocument(AutoWrite) call is a no-op if the document is already locked by that thread. If not, a lock is established, and whenever any thread requests another lock, of any kind, the AutoWrite lock is removed. Both Undo and Notification are sent on its setting and removal. It was intended for use by the AutoCAD ActiveX layer, which makes a series of modeless requests whose aggregate transaction boundaries are implicitly determined by explicitly set transaction boundaries. Its usage sequence is as follows:
set AutoWrite make changes make changes return // Opportunity for other locks here set AutoWrite make changes return
The second call to set AutoWrite will not create a second Undo mark, or send lock notification, unless another lock was set, and the first AutoWrite was removed.
In AutoCAD 2000, a new case was introduced that the earlier implementation did not cover--nested locking:
set AutoWrite make changes // Nested code creates another lock; removes kAutoWrite make changes // Lock violation return
The lock mode ProtectedAutoWrite is used to protect the AutoWrite during the scope of the function that set it, that is, up to the "return." This mode is so similar to kWrite that it has a shared bit. (See the DocLockMode table above.) In this way, any testing for (mode & Write) would also be true if the lock mode was ProtectedAutoWrite.
Unlike AutoWrite, use of ProtectedAutoWrite must be paired with an Unlock call. The unlock call does not completely unlock it, but instead downgrades it to a normal AutoWrite lock. There is no undo action, and no notification sent.
If a Write lock of any kind already exists when it is set, then it will not send notification or start an Undo record. This is identical to the existing AutoWrite setting, except that it will be slightly slower.
Use ProtectedAutoWrite instead of AutoWrite any time you were using AutoWrite before executing code which might perform a nested document lock that should leave the AutoWrite lock intact.
Use AutoWrite any time you execute code that you are absolutely sure will not apply a nested document lock.
When in doubt, use ProtectedAutoWrite.
Public Enum DocumentLockMode AutoWrite = 1 ExclusiveWrite = &H40 None = 0 NotLocked = 2 ProtectedAutoWrite = 20 Read = &H20 Write = 4 End Enum
public enum DocumentLockMode { AutoWrite = 1, ExclusiveWrite = 0x40, None = 0, NotLocked = 2, ProtectedAutoWrite = 20, Read = 0x20, Write = 4 }
Members |
Description |
AutoWrite = 1 |
This locking type indicates an Automatic Write lock. The purpose of this lock mode is to group contiguous sequences of ActiveX requests that were made without explicit locking, together as a single command. This insures their behavior as a single command with regards to Undo and notification, rather than as a bunch of separate commands/operations. This lock mode has the same effect as Write, except it is only effective when no other lock is active. An automatic lock will be unlocked when any other kind of lock is requested, complete with notification and the end undo markers and will occur just before the new notification and start undo markers for the new lock request. |
ExclusiveWrite = 0x40 |
This locking type indicates an Exclusive Write lock. It mutually excludes all other lock types by other execution contexts. It allows the execution context to examine and modify the given document contents. |
None = 0 |
No locking. |
NotLocked = 2 |
This locking type indicates there is no locking on the document context. |
ProtectedAutoWrite = 20 |
This locking type is used instead of AutoWrite before executing code which might perform a nested document lock which should leave the AutoWrite lock intact. See the description following this table. |
Read = 0x20 |
This locking type indicates a Read-only lock. It may coexist with Read locks placed by other execution contexts. It mutually excludes other Write and ExclusiveWrite locks. It allows the execution context to examine the given document contents, but not to modify. |
Write = 4 |
This locking type indicates an ExclusiveWrite lock. It mutually excludes all other lock types by other execution contexts. It allows the execution context to examine and modify the given document contents. |
Comments? |