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

FSCTL_REQUEST_OPLOCK IOCTL (winioctl.h)

  • Статья

Запрашивает оппортунистическую блокировку (oplock) в файле и подтверждает, что произошел разрыв оплока.

Чтобы выполнить эту операцию, вызовите функцию DeviceIoControl с помощью следующих параметров.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                 // handle to file
  FSCTL_REQUEST_OPLOCK,             // dwIoControlCode
  (LPVOID) lpInBuffer,              // pointer to REQUEST_OPLOCK_INPUT_BUFFER
  (DWORD) nInBufferSize,            // size of input buffer
  (LPVOID) lpOutBuffer,             // pointer to REQUEST_OPLOCK_OUTPUT_BUFFER
  (DWORD) nOutBufferSize,           // size of output buffer
  NULL,                             // number of bytes returned
  (LPOVERLAPPED) lpOverlapped       // OVERLAPPED structure
);

Замечания

Эта операция используется клиентскими приложениями для запроса оппортунистической блокировки (oplock) с локального сервера. Клиентские приложения не должны запрашивать оппортунистические блокировки с удаленных серверов напрямую — средство перенаправления сети прозрачно запрашивает оппортунистические блокировки для приложения. Использование этой операции для запроса оппортунистических блокировок с удаленных серверов приведет к отказу запроса.

Если операция DeviceIoControl возвращает код ошибки ERROR_IO_PENDING, запрос oplock был предоставлен. Если он возвращает любой другой код ошибки, oplock не был предоставлен. Если код ошибки является значением предупреждения, например ERROR_CANNOT_GRANT_REQUESTED_OPLOCK, расширенные сведения могут быть доступны в структуре REQUEST_OPLOCK_OUTPUT_BUFFER.

Когда предоставленные разрывы оплока, объект события в структуре OVERLAPPED будет сигнализировать, а сведения будут возвращены в структуре REQUEST_OPLOCK_OUTPUT_BUFFER. элемент внутренней структуры OVERLAPPED будет иметь значение NTSTATUS, которое предоставляет расширенные сведения о том, как сломался оплок.

ПЕРЕКРЫВАЮЩИХСЯ. Внутреннее значение Значение
STATUS_SUCCESS
0x0		 Блокировка была нарушена другой операцией файловой системы.
STATUS_OPLOCK_HANDLE_CLOSED
0x00000216		 Оплок больше не применяется, так как дескриптор файла, используемый для запроса, был закрыт. Обратите внимание, что если оплок прерывается, так как дескриптор, используемый для запроса, закрыт, не требуется подтвердить разрыв независимо от типа oplock.
STATUS_OPLOCK_SWITCHED_TO_NEW_HANDLE
0x00000215		 Оплок по-прежнему действует, однако он больше не связан с дескриптором файла, который использовался для запроса. Вызывающий объект использовал другой дескриптор файла для запроса нового оплока, и этот дескриптор теперь владеет оплоком.

Код элемента управления FSCTL_REQUEST_OPLOCK обеспечивает более эффективные функции, чем следующие связанные коды управления: FSCTL_REQUEST_OPLOCK_LEVEL_1, FSCTL_REQUEST_OPLOCK_LEVEL_2, FSCTL_REQUEST_FILTER_OPLOCKи FSCTL_REQUEST_BATCH_OPLOCK. Запрос различных уровней оплока можно выполнять многократно на одном дескрипторе без закрытия и повторного открытия дескриптора при использовании FSCTL_REQUEST_OPLOCK; Другие коды управления требуют закрытия дескриптора, а затем повторного открытия с помощью CreateFile внести такое изменение. Это достигается путем управления элементом RequestedOplockLevel структуры REQUEST_OPLOCK_INPUT_BUFFER при повторном выпуске кода элемента управления FSCTL_REQUEST_OPLOCK.

В следующей таблице показано, как возможность кэширования типов оплоков, доступных из FSCTL_REQUEST_OPLOCK, соответствует уровню 2, уровню 1 и пакетной блокировки.

Альтернативный код элемента управления Эквивалентное значение флагов RequestedOplockLevel Тип Oplock
FSCTL_REQUEST_BATCH_OPLOCK OPLOCK_LEVEL_CACHE_READ \| OPLOCK_LEVEL_CACHE_WRITE \| OPLOCK_LEVEL_CACHE_HANDLE RWH
FSCTL_REQUEST_OPLOCK_LEVEL_1 OPLOCK_LEVEL_CACHE_READ \| OPLOCK_LEVEL_CACHE_WRITE RW
FSCTL_REQUEST_OPLOCK_LEVEL_2 OPLOCK_LEVEL_CACHE_READ R

Использование кода элемента управления FSCTL_REQUEST_OPLOCK с RequestedOplockLevel, OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE предоставляет типаRH. Оплок RH похож на фильтр, предоставленный кодом элемента управления FSCTL_REQUEST_FILTER_OPLOCK. Однако обратите внимание, что блокировка фильтра позволяет одновременно хранить в файле только один клиент; FSCTL_REQUEST_OPLOCK позволяет нескольким клиентам одновременно блокировать RH. Другое различие заключается в том, что FSCTL_REQUEST_FILTER_OPLOCK требует подтверждения останова оплока перед записью, где FSCTL_REQUEST_OPLOCK не потому, что уведомление о приостановке действия является консультативным, и записи разрешены идти вперед без подтверждения. Дополнительные сведения см. в разделе Критическиеoplocks.

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

Сведения о последствиях перекрывающихся операций ввода-вывода в этой операции см. в разделе "Примечания" раздела DeviceIoControl.

В Windows 8 и Windows Server 2012 этот код поддерживается следующими технологиями.

Технологии Поддержанный
Протокол SMB 3.0 Нет
Отработка отказа SMB 3.0 (TFO) Нет
SMB 3.0 с масштабируемыми общими папками (SO) Нет
Файловая система общего тома кластера (CSVFS) Да
Отказоустойчивая файловая система (ReFS) Да

Кроме того, начиная с Windows 8 и Windows Server 2012, код элемента управления FSCTL_REQUEST_OPLOCK можно использовать для запроса оплока в каталоге, а также файла. Запрос oplock в каталоге может указывать либо OPLOCK_LEVEL_CACHE_READ, либо OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE в элементе RequestOplockLevel.

Оплок R или RH в каталоге прерывается на None, когда содержимое перечисления каталога изменится. Например, добавление и удаление файла в каталоге, изменение размера файла в каталоге, изменение метки времени файла в каталоге и т. д., приведет ко всем разрывам оплока в каталоге. Этот разрыв оплока не требует подтверждения, прежде чем изменения в каталоге могут возникнуть; это только рекомендации.

Оплок RH в каталоге прерывается на R при переименовании или удалении самого каталога. Этот разрыв оплока требует подтверждения перед изменением каталога.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows 7 [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2008 R2 [только классические приложения]
заголовка winioctl.h (включая Windows.h)

См. также