The IExternalConnection 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

IUnknown Methods
Returns pointers to supported interfaces.
Increments reference count.
Decrements reference count.

IExternalConnection Methods
Increments count of external locks.
Decrements count of external locks.

Software for developers
Delphi Components
.Net Components
Software for Android Developers
More information resources
Unix Manual Pages
Delphi Examples
Databases for Amazon shops developers
Amazon Categories Database
Browse Nodes Database