Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

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

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 earlier in this topic, 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 usually 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.

Members

The IExternalConnection interface inherits from the IUnknown interface. IExternalConnection also has these types of members:

Methods

The IExternalConnection interface has these methods.

MethodDescription
AddConnection

Increments the count of an object's strong external connections.

ReleaseConnection

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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ObjIdl.h

IDL

ObjIdl.idl

IID

IID_IExternalConnection is defined as 00000019-0000-0000-C000-000000000046

See also

CoDisconnectObject
CoLockObjectExternal
IOleObject

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.