Expand Minimize

CoDisconnectObject function

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

pUnk [in]

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

dwReserved [in]

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.

An object's client does not call CoDisconnectObject to disconnect itself from the server (clients should use IUnknown::Release for this purpose). Rather, an OLE server calls CoDisconnectObject to forcibly disconnect an object's clients, usually in response to a user closing the server application.

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.

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps | Windows Store apps]

Minimum supported server

Windows 2000 Server [desktop apps | Windows Store apps]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

IAdviseSink::OnClose
IMarshal::DisconnectObject
IOleObject::Close

 

 

Community Additions

ADD
Show:
© 2014 Microsoft