IMarshal::DisconnectObject

Article
06/30/2006

This method forcibly releases all external connections to an object. The object's server calls the object's implementation of this method prior to shutting down.

HRESULT DisconnectObject(
  DWORD dwReserved 
);

Parameters

dwReserved
[in] Reserved for future use; must be zero. To ensure compatibility with future use, DisConnectObject must not check for zero.

Return Values

The method supports the standard return value E_FAIL, as well as the following:

S_OK
The object was disconnected successfully.

Remarks

This method is implemented on the object, not the proxy.

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

Notes to Callers

The usual case in which this method is called occurs when an end user forcibly closes a COM server that has one or more running objects that implement IMarshal. Prior to shutting down, the server calls the CoDisconnectObject helper function to sever external connections to all its running objects. For each object that implements IMarshal, however, this function calls IMarshal::DisconnectObject, so that each object that manages its own marshaling can take steps to notify its proxy that it is about to shut down.

Notes to Implementers

As part of its standard shutdown code, a server should call the CoDisconnectObject function, which in turn calls IMarshal::DisconnectObject, on each of its running objects that implements IMarshal.

The outcome of any implementation of this method should be to enable a proxy to respond to all subsequent calls from its client by returning RPC_E_DISCONNECTED or CO_E_OBJECTNOTCONNECTED rather than attempting to forward the calls on to the original object. It is up to the client, of course, to destroy the proxy.

If you are implementing this method for an immutable object, such as a moniker, your implementation does not need to do anything because such objects are typically copied whole into the client's address space. Therefore, they have neither a proxy nor a connection to the original object. For more information on marshaling immutable objects, see IMarshal.

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Objidl.h, Objidl.idl.
Link Library: Ole32.lib, Uuid.lib.

Share via