IExternalConnection (Compact 2013)

3/26/2014

This interface manages a server object's count of marshaled, or external, connections. A server that maintains such a count can detect when it has no external connections and shut itself down in an orderly fashion.

IExternalConnection is most commonly implemented on server objects to enable the safe and orderly shutdown of a link to an embedded object following a silent update.

Objects that do not implement IExternalConnection risk losing data in such a situation: when the final link client releases the embedded (server) object, the last external connection on the object's stub manager is released, causing the stub manager to release its pointers to interfaces on the embedded object and initiate shutdown of the object.

At this point the server object calls IOleClientSite::SaveObject on the link container, and the link container's return call to IPersistStorage::Save fails, because the stub manager no longer has a pointer to the embedded object. Any unsaved changes to the server object's data would then be lost.

If the server object implements IExternalConnection, however, its stub manager will not release its connection to the object when the last external connection is released. Instead, it will stay connected until the object is ready to destroy itself.

In standard marshaling, COM calls IExternalConnection::AddConnection on the object when the object is first marshaled to increment its count of external connections. The stub manager calls the methods of IExternalConnection on the object as subsequent external connections are obtained and released.

When the object's count of external connections goes to zero, the object can save its data and then revoke itself from the running object table and do whatever else is necessary to reduce its object reference count to zero.

An object that implements IExternalConnection should explicitly call CoDisconnectObject on itself when its external reference count drops to 0. This call will cause the stub manager to call Release on the object so the object can destroy itself.

When to Implement

Implement IExternalConnection on server objects that need to detect marshaled connections to themselves from clients that are either out-of-process or residing in another apartment in the same process.

Implement IExternalConnection also on objects that need to keep the stub manager in memory independent of the proxy count. For example, as explained above, objects that can be linked and embedded should implement IExternalConnection to keep a container application running during a silent update.

A class factory object can implement IExternalConnection to keep running even when no clients are requesting or using the objects it creates.

An in-place container should also implement IExternalConnection to keep itself running while contained objects save their data before shutting down.

When to Use

You do not typically call the methods of IExternalConnection from your own code. In nearly every case, COM makes these calls for you.

The only time to use IExternalConnection from your own code is when you write a custom marshaler that implements its own stub manager functionality.

Methods in Vtable Order

Remarks

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

See Also

Reference

COM Interfaces
IOleObject
CoLockObjectExternal
CoDisconnectObject