CoLockObjectExternal
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.
STDAPI CoLockObjectExternal(
|
IUnknown *
pUnk, |
//Pointer to object to be locked or unlocked |
|
BOOL fLock, |
//TRUE = lock, FALSE = unlock |
|
BOOL fLastUnlockReleases |
//TRUE = release all pointers to object |
|
); |
|
Parameters
pUnk
[in] Pointer
to the IUnknown
interface on the object to be locked or unlocked.
fLock
[in] 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.
fLastUnlockReleases
[in] 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).
Return Values
This function
supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and
E_UNEXPECTED, as well as the following:
S_OK
The object
was locked successfully.
Remarks
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
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).
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.
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.
Note 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.
See Also