See Also
 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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.
IExternalConnectionis 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 IExternalConnectionrisk 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::SaveObjecton the link container, and the link container's return call to IPersistStorage::Savefails, 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::AddConnectionon the object when the object is first marshaled to increment its count of external connections. The stub manager calls the methods of IExternalConnectionon 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 IExternalConnectionshould explicitly call CoDisconnectObjecton 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 IExternalConnectionon 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 IExternalConnectionalso 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 IExternalConnectionto keep a container application running during a silent update.
A class factory object can implement IExternalConnectionto keep running even when no clients are requesting or using the objects it creates.
An in-place container should also implement IExternalConnectionto keep itself running while contained objects save their data before shutting down.
When to Use
You do not typically call the methods of IExternalConnectionfrom your own code. In nearly every case, COM makes these calls for you.
The only time to use IExternalConnectionfrom your own code is when you write a custom marshaler that implements its own stub manager functionality.
Methods in Vtable Order
| IUnknown method | Description |
|---|---|
|
Returns pointers to supported interfaces. |
|
|
Increments the reference count. |
|
|
Decrements the reference count. |
| Method | Description |
|---|---|
|
Increments count of external locks. |
|
|
Decrements count of external locks. |
Remarks
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Requirements
| Header | objidl.h, objidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |