Called either to lock an object to ensure that it stays in memory, or to release such a lock.
HRESULT CoLockObjectExternal( LPUNKNOWN pUnk, BOOL fLock, BOOL fLastUnlockReleases );
A pointer to the IUnknown interface on the object to be locked or unlocked.
Indicates whether the object is to be locked or released. If this parameter is TRUE, the object is kept in memory, independent of AddRef/Release operations, registrations, or revocations. If this parameter is FALSE, the lock previously set with a call to this function is released.
If the lock is the last reference that is supposed to keep an object alive, specify TRUE to release all pointers to the object (there may be other references that are not supposed to keep it alive). Otherwise, specify FALSE.
If fLock is TRUE, this parameter is ignored.
This function can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and S_OK.
The CoLockObjectExternal function must be called in the process in which the object actually resides (the EXE process, not the process in which handlers may be loaded).
The CoLockObjectExternal function prevents the reference count of an object from going to zero, thereby "locking" it into existence until the lock is released. The same function (with different parameters) releases the lock. The lock is implemented by having the system call IUnknown::AddRef on the object. The system then waits to call IUnknown::Release on the object until a later call to CoLockObjectExternal with fLock set to FALSE. This function can be used to maintain a reference count on the object on behalf of the end user, because it acts outside of the object, as does the user.
The end user has explicit control over the lifetime of an application, even if there are external locks on it. That is, if a user decides to close the application, it must shut down. In the presence of external locks (such as the lock set by CoLockObjectExternal), the application can call the CoDisconnectObject function to force these connections to close prior to shutdown.
Calling CoLockObjectExternal sets a strong lock on an object. A strong lock keeps an object in memory, while a weak lock does not. Strong locks are required, for example, during a silent update to an OLE embedding. The embedded object's container must remain in memory until the update process is complete. There must also be a strong lock on an application object to ensure that the application stays alive until it has finished providing services to its clients. All external references place a strong reference lock on an object.
The CoLockObjectExternal function is typically called in the following situations:
- Object servers should call CoLockObjectExternal with both fLock and fLastLockReleases set to TRUE when they become visible. This call creates a strong lock on behalf of the user. When the application is closing, free the lock with a call to CoLockObjectExternal, setting fLock to FALSE and fLastLockReleases to TRUE.
- A call to CoLockObjectExternal on the server can also be used in the implementation of IOleContainer::LockContainer.
Unless an application manages all aspects of its application and document shutdown completely with calls to CoLockObjectExternal, the container must keep a private lock count in LockContainer so that it exits when the lock count reaches zero and the container is invisible. Maintaining all aspects of shutdown, and thereby avoiding keeping a private lock count, means that CoLockObjectExternal should be called whenever one of the following conditions occur:
- A document is created and destroyed or made visible or invisible.
- An application is started and shut down by the user.
- A pseudo-object is created and destroyed.
|Windows version||Windows 2000 Professional [desktop apps only] Windows 2000 Server [desktop apps only]|
|Header||combaseapi.h (include Objbase.h)|