Функция CoLockObjectExternal (combaseapi.h)
Вызывается либо для блокировки объекта, чтобы убедиться, что он остается в памяти, либо для снятия такой блокировки.
Синтаксис
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 должна вызываться в процессе, в котором фактически находится объект (процесс EXE, а не процесс, в котором могут быть загружены обработчики).
Функция 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 , чтобы он завершал работу, когда число блокировок достигает нуля, а контейнер невидим. Сохранение всех аспектов завершения работы и, таким образом, избегание сохранения количества закрытых блокировок означает, что CoLockObjectExternal должен вызываться всякий раз, когда возникает одно из следующих условий:
- Документ создается и уничтожается, становится видимым или невидимым.
- Приложение запускается и завершается пользователем.
- Создается и уничтожается псевдо-объект.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | combaseapi.h (включая Objbase.h) |
| Библиотека | Ole32.lib |
| DLL | Ole32.dll |