interface enables an embedded object to keep track of external locks on it,
thereby enabling the safe and orderly shutdown of the object following silent
updates. An object that supports links either to itself or to some portion of
itself (a range of cells in a spreadsheet, for example) should implement this
interface to prevent possible loss of data during shutdown.
Such data loss can occur when an object happens to have unsaved changes at a
time when its stub manager's count of strong external references has reached
zero. This situation would arise, for example, at the end of a silent update, when
the final link client breaks its connection to the object. With the severing
of this connection, the stub manager's count of strong external references would
reach zero, causing it to release its pointers to the object and initiate
shutdown of the object. When the object calls IOleClientSite::SaveObject,
its container's return call to IPersistStorage::Save
would fail because the stub manager would no longer have a pointer to the
object. Any unsaved changes to the object would be lost.
If the object manages its own count of external locks, rather than relying on
the stub manager to do so, it can save its data before the stub manager has a
chance to release its pointers. An object can obtain a count of external
connections by implementing the IExternalConnection
interface. The stub manager calls this interface whenever a new strong
external reference is added or deleted. The object combines this count with its own
tally of strong internal references to maintain an accurate total of all locks.
When to Implement
All embeddable compound-document objects that support links to themselves or
portions of themselves should implement IExternalConnection
to prevent possible data loss during shutdown. In addition, an in-place
container should call OleLockRunning
to hold a strong lock on its embedded objects.
When to Use
An object's stub manager should call IExternalConnection
whenever an external connection is added or released.
Methods in VTable Order
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages