Метод ILockBytes::LockRegion (objidl.h)

Статья
08/25/2023

Метод LockRegion ограничивает доступ к указанному диапазону байтов в массиве байтов.

Синтаксис

HRESULT LockRegion(
  [in] ULARGE_INTEGER libOffset,
  [in] ULARGE_INTEGER cb,
  [in] DWORD          dwLockType
);

Параметры

[in] libOffset

Задает смещение в байтах для начала диапазона.

[in] cb

Указывает в байтах длину ограничивающего диапазона.

[in] dwLockType

Указывает тип запрашиваемых ограничений на доступ к диапазону. Этот параметр использует одно из значений перечисления LOCKTYPE .

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

Этот метод может возвращать одно из этих значений.

Код возврата	Описание
S_OK	Указанный диапазон байтов был заблокирован.
STG_E_INVALIDFUNCTION	Блокировка не поддерживается вообще или конкретный тип запрошенной блокировки не поддерживается.
STG_E_ACCESSDENIED	Доступ запрещен, так как у вызывающего абонента недостаточно разрешений или другой вызывающей стороны файл открыт и заблокирован.
STG_E_LOCKVIOLATION	Доступ запрещен, так как другой вызывающий объект открыт и заблокирован.
STG_E_INVALIDHANDLE	Базовый файл был преждевременно закрыт или правильный гибкий диск был заменен недопустимым.

ILockBytes::LockRegion ограничивает доступ к указанному диапазону байтов. После блокировки региона попытки других пользователей получить доступ к ограниченному диапазону должны завершиться ошибкой STG_E_ACCESSDENIED.

Диапазон байтов может расширяться после текущего конца массива байтов. Блокировка за пределами массива полезна как метод обмена данными между различными экземплярами объекта массива байтов без изменения данных, которые фактически являются частью массива байтов. Например, реализация ILockBytes для составных файлов может полагаться на блокировку после текущего конца массива в качестве средства управления доступом, используя определенные заблокированные регионы для указания предоставленных разрешений.

Параметр dwLockType указывает один из трех типов блокировки с использованием значений перечисления LOCKTYPE . Типы: блокировка для исключения других модулей записи, блокировка для исключения других модулей чтения или записи и блокировка, позволяющая только одному инициатору запроса получить блокировку в заданном диапазоне. Этот третий тип блокировки обычно является псевдонимом для одного из двух других типов блокировок и позволяет разработчику добавить другое поведение. Заданный массив байтов может поддерживать любой из первых двух типов или оба типа.

Чтобы определить типы блокировок, поддерживаемые конкретной реализацией ILockBytes , можно изучить элемент grfLocksSupported структуры STATSTG , возвращаемый вызовом метода ILockBytes::Stat.

Любой регион, заблокированный с помощью ILockBytes::LockRegion , должен быть позже явно разблокирован путем вызова метода ILockBytes::UnlockRegion с теми же значениями для параметров libOffset, cb и dwLockType . Регион должен быть разблокирован перед освобождением потока. Две смежные области нельзя заблокировать отдельно, а затем разблокировать с помощью одного вызова разблокировки.

Примечания к вызывающим абонентам

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

Примечания для разработчиков

Поддержка этого метода зависит от того, как используется объект хранилища, созданный на основе реализации ILockBytes . Если известно, что на устройстве хранения, лежащем в основе массива байтов, в любой момент времени может быть открыт только один объект хранилища, то реализация ILockBytes не должна поддерживать блокировку. Однако если возможно несколько одновременных открытий объекта хранилища, для их координации требуется блокировка региона.

Реализация LockRegion может поддерживать все, некоторые или ни один из типов блокировки. Для неподдерживаемых типов блокировок реализация должна возвращать STG_E_INVALIDFUNCTION.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	objidl.h
Библиотека	Uuid.lib
DLL	Ole32.dll