IExternalConnection  4BK154

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 an interface on the object and initiate shutdown of the object. When the object calls IOleClientSite::SaveObjectJSS2IT, its container s return call to IPersistStorage::SaveS4I7H8 would fail because the stub manager would no longer have a pointer to any interface on 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 OleLockRunningF.1NK1 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