CoDisconnectObject function (combaseapi.h)

Disconnects all remote process connections being maintained on behalf of all the interface pointers that point to a specified object.

Only the process that actually manages the object should call CoDisconnectObject.

Syntax

HRESULT CoDisconnectObject(
  [in] LPUNKNOWN pUnk,
  [in] DWORD     dwReserved
);

Parameters

[in] pUnk

A pointer to any interface derived from IUnknown on the object to be disconnected.

[in] dwReserved

This parameter is reserved and must be 0.

Return value

This function returns S_OK to indicate that all connections to remote processes were successfully deleted.

Remarks

The CoDisconnectObject function enables a server to correctly disconnect all external clients to the object specified by pUnk.

It performs the following tasks:

1. Checks to see whether the object to be disconnected implements the IMarshal interface. If so, it gets the pointer to that interface; if not, it gets a pointer to the standard marshaler's (i.e., COM's) IMarshal implementation.
2. Using whichever IMarshal interface pointer it has acquired, the function then calls IMarshal::DisconnectObject to disconnect all out-of-process clients.

Similarly, an OLE container that supports external links to its embedded objects can call CoDisconnectObject to destroy those links. Again, this call is normally made in response to a user closing the application. The container should first call IOleObject::Close for all its OLE objects, each of which should send IAdviseSink::OnClose notifications to their various clients. Then the container can call CoDisconnectObject to close any existing connections.

CoDisconnectObject does not necessarily disconnect out-of-process clients immediately. If any marshaled calls are pending on the server object, CoDisconnectObject disconnects the object only when those calls have returned. In the meantime, CoDisconnectObject sets a flag that causes any new marshaled calls to return CO_E_OBJNOTCONNECTED.

Requirements

See also

IAdviseSink::OnClose

IMarshal::DisconnectObject

IOleObject::Close