Called either to lock an object to ensure that it stays in memory, or to
release such a lock. Call CoLockObjectExternal
to place a strong lock on an object to ensure that it stays in memory.
| IUnknown * pUnk,
||//Pointer to object to be locked or unlocked
| BOOL fLock,
||//TRUE = lock, FALSE = unlock
| BOOL fLastUnlockReleases
||//TRUE = release all pointers to object
Points to the object (through its IUnknown
interface) to be locked or unlocked.
Specifies whether the object is to be locked or released. Specifying TRUE
holds a reference to the object (keeping it in memory), locking it independently of
external or internal AddRef/Release
operations, registrations, or revocations. If fLock
is TRUE, fLastLockReleases
is ignored. FALSE releases a lock previously set with a call to this function.
Specifies whether a given lock is the last reference that is supposed to keep
an object alive. If it is, TRUE releases all pointers to the object (there may
be other references that are not supposed to keep it alive).
Indicates the object was locked successfully.
Out of memory.
Indicates one or more arguments are invalid.
Indicates an unexpected error occurred.
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
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.
be called in the process in which the object actually resides (the EXE
process, not the process in which handlers may be loaded).
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.
function is typically called in the following situations:
- Object applications 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 application object can also be used in the implementation of IOleContainer::LockContainer.
There are several things to be aware of when you use CoLockObjectExternal
in the implementation of IOleContainer::LockContainer
. An embedded object would call IOleContainer::LockContainer
on its container to keep it running (to lock it) in the absence of other
reasons to keep it running. When the embedded object becomes visible, the container
must weaken its connection to the embedded object with a call to the OleSetContainedObject
function, so other connections can affect the object.
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 IOleContainer::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.
For debugging purposes, it may be useful to keep a count of the number of
external locks (and unlocks) set on the application.
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 (File, Exit), 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.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages