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

Статья
08/22/2023

Вызывается либо для блокировки объекта, чтобы убедиться, что он остается в памяти, либо для снятия такой блокировки.

Синтаксис

HRESULT CoLockObjectExternal(
  [in] LPUNKNOWN pUnk,
  [in] BOOL      fLock,
  [in] BOOL      fLastUnlockReleases
);

Параметры

[in] pUnk

Указатель на интерфейс IUnknown на объекте, который необходимо заблокировать или разблокировать.

[in] fLock

Указывает, должен ли объект быть заблокирован или освобожден. Если этот параметр имеет значение TRUE, объект хранится в памяти независимо от операций выпуска AddRef/, регистраций или отзывов. Если этот параметр имеет значение FALSE, блокировка, установленная ранее с вызовом этой функции, освобождается.

[in] fLastUnlockReleases

Если блокировка является последней ссылкой, которая должна поддерживать активный объект, укажите значение TRUE , чтобы освободить все указатели на объект (могут быть и другие ссылки, которые не должны поддерживать его в активном режиме). В противном случае укажите ЗНАЧЕНИЕ FALSE.

Если fLock имеет значение TRUE, этот параметр игнорируется.

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

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

Функция CoLockObjectExternal предотвращает нулевое число ссылок объекта, тем самым «блокируя» его до тех пор, пока блокировка не будет снята. Та же функция (с разными параметрами) снимает блокировку. Блокировка реализуется путем системного вызова IUnknown::AddRef для объекта . Затем система ожидает вызова IUnknown::Release в объекте, пока не будет позже вызывать CoLockObjectExternal с параметром flock , установленным для false. Эта функция может использоваться для поддержания количества ссылок на объект от имени конечного пользователя, так как она действует за пределами объекта, как и пользователь.

Конечный пользователь имеет явный контроль над временем существования приложения, даже если на нем есть внешние блокировки. То есть, если пользователь решит закрыть приложение, оно должно завершить работу. При наличии внешних блокировок (например, блокировки, установленной CoLockObjectExternal), приложение может вызвать функцию CoDisconnectObject , чтобы принудительно закрыть эти подключения перед завершением работы.

Вызов CoLockObjectExternal задает строжную блокировку объекта. Сильная блокировка сохраняет объект в памяти, а слабая блокировка — нет. Сильные блокировки требуются, например, при автоматическом обновлении внедрения OLE. Контейнер внедренного объекта должен оставаться в памяти до завершения процесса обновления. Кроме того, объект приложения должен иметь строгую блокировку, чтобы гарантировать, что приложение остается активным до тех пор, пока оно не завершит предоставление услуг своим клиентам. Все внешние ссылки помещируют строгой блокировку ссылок на объект .

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

Серверы объектов должны вызывать CoLockObjectExternal с параметром fLock и fLastLockReleases, когда они становятся видимыми. Этот вызов создает надежную блокировку от имени пользователя. Когда приложение закрывается, освободите блокировку с помощью вызова CoLockObjectExternal, установив для параметра fLockзначение FALSE , а fLastLockReleases — значение TRUE.
Вызов CoLockObjectExternal на сервере также можно использовать в реализации IOleContainer::LockContainer.

При использовании CoLockObjectExternal в реализации LockContainer следует учитывать несколько моментов. Внедренный объект вызывает LockContainer в своем контейнере, чтобы сохранить его работу (для блокировки) при отсутствии других причин для поддержания его работы. Когда внедренный объект становится видимым, контейнер должен ослабить свое соединение с внедренным объектом с помощью вызова функции OleSetContainedObject , чтобы другие подключения могли повлиять на объект.

Если приложение не полностью управляет всеми аспектами своего приложения и завершения работы документа с помощью вызовов CoLockObjectExternal, контейнер должен хранить количество закрытых блокировок в LockContainer , чтобы он завершал работу, когда число блокировок достигает нуля, а контейнер невидим. Сохранение всех аспектов завершения работы и, таким образом, избегание сохранения количества закрытых блокировок означает, что CoLockObjectExternal должен вызываться всякий раз, когда возникает одно из следующих условий:

Документ создается и уничтожается, становится видимым или невидимым.
Приложение запускается и завершается пользователем.
Создается и уничтожается псевдо-объект.

В целях отладки может быть полезно сохранить количество внешних блокировок (и разблокировок), установленных в приложении.

Требования

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

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

IOleContainer::LockContainer

OleSetContainedObject

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