Функция CoDisconnectContext (combaseapi.h)

Статья
02/26/2024

Отключает все прокси-подключения, которые поддерживаются от имени всех указателей интерфейса, указывающих на объекты в текущем контексте.

Эта функция блокирует подключения до тех пор, пока все объекты не будут успешно отключены или не истечет время ожидания. Только контекст, который фактически управляет объектами, должен вызывать CoDisconnectContext.

Синтаксис

HRESULT CoDisconnectContext(
  [in] DWORD dwTimeout
);

Параметры

[in] dwTimeout

Время в миллисекундах, по истечении которого CoDisconnectContext возвращает, даже если прокси-подключения для всех объектов не были отключены. Infinite является допустимым значением для этого параметра.

Возвращаемое значение

Эта функция может возвращать стандартные возвращаемые значения E_FAIL, E_INVALIDARG и E_OUTOFMEMORY, а также следующие значения.

Код возврата	Описание
S_OK	Прокси-подключения для всех объектов были успешно отключены.
RPC_E_TIMEOUT	Не все прокси-подключения были успешно удалены за время, указанное в dwTimeout.
CO_E_NOTSUPPORTED	Текущий контекст не может быть отключен.
CONTEXT_E_WOULD_DEADLOCK	Объект пытался вызвать CoDisconnectContext в контексте, в который он находится. Это приведет к превышению времени ожидания функции и взаимоблокировке, если dwTimeout будет задано значение INFINITE.

Функция CoDisconnectContext используется для поддержки выгрузки служб на узлах общих служб, где необходимо выгрузить двоичные файлы службы, не затрагивая другие COM-серверы, работающие в том же процессе. Если вы управляете временем существования процесса и не выгружаете до завершения процесса, com-инфраструктура автоматически выполнит необходимую очистку и вам не придется вызывать эту функцию.

Функция CoDisconnectContext позволяет серверу правильно отключать все внешние клиенты всех объектов в текущем контексте. Контексты по умолчанию не могут быть отключены. Чтобы использовать CoDisconnectContext, необходимо сначала создать контекст, который можно отключить, и зарегистрировать фабрики классов для объектов, от которых требуется отключиться в этом контексте. Это можно сделать с помощью интерфейса IContextCallback .

Если CoDisconnectContext возвращает RPC_E_TIMEOUT, это не означает, что функция не отключает объекты, но не все отключения могут быть завершены в указанное dwTimeout время из-за невыполненных вызовов объектов. После завершения всех вызовов все объекты будут отключены.

Небезопасно выгружать библиотеку DLL, в котором размещена служба, пока CoDisconnectContext не вернет S_OK. Если функция возвращает RPC_E_TIMEOUT, служба может выполнить другую очистку. Служба должна вызывать функцию до тех пор, пока она не вернет S_OK, а затем сможет безопасно выгрузить свою библиотеку DLL.

Функция CoDisconnectContext выполняет следующие задачи:

Вызывает CoDisconnectObject для всех объектов в текущем контексте.
Блокируется, пока все объекты не будут отключены или не истечет время ожидания.

Функция CoDisconnectContext имеет следующие ограничения.

Асинхронные вызовы COM не поддерживаются.
Внутрипроцессные объекты должны быть зарегистрированы и включены с помощью флага CLSCTX_LOCAL_SERVER, иначе они не будут отключены.
COM+ не поддерживается.
Указатели com-интерфейса чувствительны к контексту. Поэтому любой указатель интерфейса, созданный в отсоединяемом контексте, можно использовать только в этом контексте.

Примеры

IContextCallback *icc;
hr = CoCreateInstance(CLSID_ContextSwitcher, NULL, CLSCTX_INPROC_SERVER, IID_IContextCallback, (void**)&icc);

icc->ContextCallback(EnterCallback, NULL, IID_IContextCallback, 5, NULL);

HRESULT __stdcall EnterCallback(ComCallData *pv)
{ 
    return CoRegisterClassObject(...);
}

/* All objects created by the class factories registered in the callback will be put into the newly created context.
To disconnect, re-enter the context, revoke the class factories, and call CoDisconnectContext. */

icc->ContextCallback(DisconnectCallback, NULL, IID_IContextCallback, 5, NULL);

HRESULT __stdcall DisconnectCallback(ComCallData *pv)
{
    CoRevokeClassObject(...);
    return CoDisconnectContext(timeout);
}

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	combaseapi.h (включая Objbase.h)
Библиотека	Ole32.lib
DLL	Ole32.dll

См. также раздел

CoDisconnectObject

IContextCallback

Поделиться через