Функция LockFileEx (fileapi.h)
Блокирует указанный файл для монопольного доступа вызывающим процессом. Эта функция может работать синхронно или асинхронно и запрашивать монопольную или общую блокировку.
Синтаксис
BOOL LockFileEx(
[in] HANDLE hFile,
[in] DWORD dwFlags,
DWORD dwReserved,
[in] DWORD nNumberOfBytesToLockLow,
[in] DWORD nNumberOfBytesToLockHigh,
[in, out] LPOVERLAPPED lpOverlapped
);
Параметры
[in] hFile
Дескриптор файла. Дескриптор должен быть создан с правом доступа GENERIC_READ или GENERIC_WRITE . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.
[in] dwFlags
Этот параметр может иметь одно или несколько из следующих значений.
dwReserved
Зарезервированный параметр; значение должно быть равно нулю.
[in] nNumberOfBytesToLockLow
32 бита нижнего порядка длины байтового диапазона для блокировки.
[in] nNumberOfBytesToLockHigh
Высокий порядок 32 бита длины диапазона байтов для блокировки.
[in, out] lpOverlapped
Указатель на структуру OVERLAPPED , используемую функцией с запросом блокировки. Эта структура, которая является обязательной, содержит смещение файла начала диапазона блокировки. Необходимо инициализировать элемент hEvent допустимым дескриптором или нулевым значением.
Возвращаемое значение
Если функция выполнена успешно, возвращается ненулевое значение (TRUE).
Если функция завершается сбоем, возвращаемое значение равно нулю (FALSE). Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Блокировка области файла используется для получения общего или монопольного доступа к указанному региону с помощью этого дескриптора файла. Если дескриптор файла наследуется процессом, созданным процессом блокировки, дочернему процессу не предоставляется доступ к заблокированной области. Если процесс блокировки открывает файл во второй раз, он не сможет получить доступ к указанному региону через этот второй дескриптор, пока не разблокирует регион.
Блокировка части файла для монопольного доступа запрещает всем остальным процессам доступ к указанной области файла как для чтения, так и для записи. Блокировка области, которая выходит за пределы текущей позиции в конце файла, не является ошибкой.
Блокировка части файла для общего доступа запрещает всем процессам доступ на запись в указанную область файла, включая процесс, который сначала блокирует регион. Все процессы могут считывать заблокированную область.
Блокировка области файла не препятствует чтению или записи из сопоставленного представления файла.
Функция LockFileEx работает асинхронно, если дескриптор файла был открыт для асинхронного ввода-вывода, если не указан флаг LOCKFILE_FAIL_IMMEDIATELY . Если запрашивается монопольная блокировка для диапазона файла, который уже имеет общую или монопольную блокировку, функция возвращает ошибку ERROR_IO_PENDING. Система будет сигнализировать о событии, указанном в структуре OVERLAPPED после предоставления блокировки. Чтобы определить, когда блокировка была предоставлена, используйте функцию GetOverlappedResult или одну из функций ожидания. Дополнительные сведения см. в разделе Синхронный и асинхронный ввод-вывод.
Если дескриптор файла не был открыт для асинхронного ввода-вывода и блокировка недоступна, этот вызов ожидает предоставления блокировки или возникновения ошибки, если не указан флаг LOCKFILE_FAIL_IMMEDIATELY .
Монопольные блокировки не могут перекрывать существующую заблокированную область файла. Общие блокировки могут перекрывать заблокированный регион, если блокировки, удерживаемые в этом регионе, являются общими. Общая блокировка может перекрывать монопольную блокировку, если обе блокировки были созданы с помощью одного дескриптора файла. Когда общая блокировка перекрывает монопольную блокировку, единственным возможным доступом является чтение владельцем блокировок. Если один и тот же диапазон заблокирован монопольной и общей блокировкой, для разблокировки региона необходимы две операции разблокировки; первая операция разблокировки разблокирует монопольную блокировку, вторая — общую блокировку.
Если процесс завершается блокировкой части файла или закрывается файл с незаблокированными блокировками, блокировки разблокируются операционной системой. Однако время, необходимое операционной системе для разблокировки этих блокировок, зависит от доступных системных ресурсов. Поэтому рекомендуется явно разблокировать все файлы, заблокированные при завершении процесса. Если этого не сделать, доступ к этим файлам может быть запрещен, если операционная система еще не разблокировала их.
В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.
| Технология | Поддерживается |
|---|---|
| Протокол SMB 3.0 | Да |
| Прозрачная отработка отказа (TFO) SMB 3.0 | Да |
| SMB 3.0 с масштабируемыми общими папками (SO) | Да |
| Файловая система общего тома кластера (CSVFS) | Да |
| Восстанавливаемая файловая система (ReFS) | Да |
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | fileapi.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |