IExternalConnection interface (objidl.h)
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.
Inheritance
The IExternalConnection interface inherits from the IUnknown interface. IExternalConnection also has these types of members:
Methods
The IExternalConnection interface has these methods.
| IExternalConnection::AddConnection The IExternalConnection::AddConnection method (objidl.h) increments the count of an object's strong external connections. |
| IExternalConnection::ReleaseConnection The IExternalConnection::ReleaseConnection method (objidl.h) decrements the count of an object's strong external connections. |
Remarks
IExternalConnection is most commonly implemented on server objects, to enable the 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, to increment the object's count of external connections, COM calls IExternalConnection::AddConnection on the object when the object is first marshaled. 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 that the object can destroy itself.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | objidl.h (include ObjIdl.h) |