Функция NtCreateFile (ntifs.h)

Статья
04/11/2023

Подпрограмма NtCreateFile создает новый файл или открывает существующий.

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Параметры

[out] FileHandle

Указатель на переменную HANDLE, которая получает дескриптор файла.

[in] DesiredAccess

Задает значение ACCESS_MASK , определяющее запрошенный доступ к объекту.

Помимо стандартных прав доступа, определенных для всех типов объектов, вызывающий объект может указать любое из следующих конкретных прав доступа: то есть права, относящиеся к файлам.

флаг ACCESS_MASK	Позволяет вызывающей службе сделать это
FILE_READ_DATA	Чтение данных из файла.
FILE_READ_ATTRIBUTES	Чтение атрибутов файла. Дополнительные сведения см. в описании параметра FileAttributes .
FILE_READ_EA	Чтение расширенных атрибутов (EAs) файла. Этот флаг не имеет отношения к драйверам устройств и промежуточным драйверам.
FILE_WRITE_DATA	Запись данных в файл.
FILE_WRITE_ATTRIBUTES	Запись атрибутов файла. Дополнительные сведения см. в описании параметра FileAttributes .
FILE_WRITE_EA	Изменение расширенных атрибутов (EAs) файла. Этот флаг не имеет отношения к драйверам устройств и промежуточным драйверам.
FILE_APPEND_DATA	Добавление данных в файл.
FILE_EXECUTE	Используйте системные операции ввода-вывода подкачки для чтения данных из файла в память. Этот флаг не имеет отношения к драйверам устройств и промежуточным драйверам.

Примечание

Не указывайте FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA или FILE_EXECUTE при создании или открытии каталога.

Вызывающий объект также может указать следующие универсальные права доступа (права, которые применяются ко всем типам объектов, где значение каждого универсального права доступа зависит от типа объекта). Универсальные права доступа для файлового объекта соответствуют определенным правам доступа, как показано в следующей таблице. (Обратите внимание, что "соответствовать" означает "сопоставляется с" и не означает, что значение универсального права "равно" значению побитового или сопоставления его конкретных прав. Диспетчер ввода-вывода определяет фактическое сопоставление.

Универсальное право доступа	Сопоставляется с этими конкретными правами доступа
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA и SYNCHRONIZE
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA и SYNCHRONIZE
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, FILE_EXECUTE, FILE_READ_ATTRIBUTES и SYNCHRONIZE. Это значение не имеет значения для устройств и промежуточных драйверов.
GENERIC_ALL	FILE_ALL_ACCESS

Примечание

Универсальные права доступа можно указать только для файла; их нельзя указать для каталога.

Некоторые флаги CreateOptions требуют установки определенных флагов доступа в DesiredAccess при вызове NtCreateFile . Эти сведения см. в параметре CreateOptions .

Например, если указать GENERIC_READ для объекта файла, подпрограмма сопоставляет это значение с FILE_GENERIC_READ битовой маской определенных прав доступа. В предыдущей таблице конкретные права доступа, перечисленные для GENERIC_READ соответствуют (но не равны) флагам доступа, содержащимся в FILE_GENERIC_READ битовой маске.

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

Флаг DesiredAccess	Позволяет вызывающей службе сделать это
FILE_LIST_DIRECTORY	Вывод списка файлов в каталоге.
FILE_TRAVERSE	Перейдите по каталогу, иными словами, включите каталог в путь к файлу.

Дополнительные сведения о правах доступа см. в разделе ACCESS_MASK и права доступа.

[in] ObjectAttributes

Указатель на структуру OBJECT_ATTRIBUTES , указывающую имя объекта и другие атрибуты. Используйте InitializeObjectAttributes для инициализации этой структуры. Если вызывающий объект не выполняется в контексте системного потока, он должен задать атрибут OBJ_KERNEL_HANDLE при вызове InitializeObjectAttributes.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает состояние окончательного завершения и другие сведения о запрошенной операции. В частности, элемент Information получает одно из следующих значений:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Указатель на LARGE_INTEGER, содержащий начальный размер выделения (в байтах) для созданного или перезаписываемого файла. Если значение AllocationSize равно NULL, размер выделения не указан. Если файл не создан или не перезаписан, AllocationSize игнорируется.

[in] FileAttributes

Задает один или несколько флагов FILE_ATTRIBUTE_XXX , которые представляют атрибуты файла, устанавливаемые при создании или перезаписи файла. Вызывающий объект обычно задает FILE_ATTRIBUTE_NORMAL, который задает атрибуты по умолчанию. Список допустимых флагов FILE_ATTRIBUTE_XXX см. в подпрограмме CreateFile документации по Microsoft Windows SDK. Если файл не создается или не перезаписывается, атрибуты FileAttributes игнорируются.

[in] ShareAccess

Тип доступа к общей папке, который указывается как ноль или любое сочетание следующих флагов.

Флаг ShareAccess	Позволяет другим потокам делать это
FILE_SHARE_READ	Чтение файла
FILE_SHARE_WRITE	Запись файла
FILE_SHARE_DELETE	Удаление файла

Драйверы устройств и промежуточных водителей обычно устанавливают для ShareAccess нулевое значение, что предоставляет вызывающей объекту монопольный доступ к открытому файлу.

[in] CreateDisposition

Указывает действие, которое необходимо выполнить, если файл существует или не существует. CreateDisposition может быть одним из значений в следующей таблице.

Значение CreateDisposition	Действие, если файл существует	Действие, если файл не существует
FILE_SUPERSEDE	Замените файл.	Создайте файл.
FILE_CREATE	Возвращает ошибку.	Создайте файл.
FILE_OPEN	Откройте файл.	Возвращает ошибку.
FILE_OPEN_IF	Откройте файл.	Создайте файл.
FILE_OVERWRITE	Откройте файл и перезапишите его.	Возвращает ошибку.
FILE_OVERWRITE_IF	Откройте файл и перезапишите его.	Создайте файл.

[in] CreateOptions

Указывает параметры, применяемые при создании или открытии файла драйвером. Используйте один или несколько флагов в следующей таблице.

Флаг CreateOptions	Значение
FILE_DIRECTORY_FILE (0x00000001)	Файл является каталогом. Совместимые флаги CreateOptions : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT и FILE_OPEN_BY_FILE_ID. Параметру CreateDisposition необходимо задать значение FILE_CREATE, FILE_OPEN или FILE_OPEN_IF.
FILE_WRITE_THROUGH (0x00000002)	Системные службы, драйверы файловой системы и драйверы, которые записывают данные в файл, должны фактически передавать данные в файл, прежде чем любая запрошенная операция записи будет считаться завершенной.
FILE_SEQUENTIAL_ONLY (0x00000004)	Весь доступ к файлу будет последовательным.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	Файл не может быть кэширован или помещен во внутренние буферы драйвера. Этот флаг несовместим с флагом FILE_APPEND_DATA параметра DesiredAccess .
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Все операции с файлом выполняются синхронно. Любое ожидание от имени вызывающей стороны может быть связано с преждевременным завершением оповещений. Этот флаг также приводит к тому, что система ввода-вывода сохраняет указатель на положение файла. Если этот флаг установлен, флаг SYNCHRONIZE должен быть задан в параметре DesiredAccess .
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Все операции с файлом выполняются синхронно. Ожидания в системе, которые синхронизируют постановку в очередь и завершение ввода-вывода, не подлежат оповещениям. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст положения файла. Если этот флаг установлен, флаг SYNCHRONIZE должен быть задан в параметре DesiredAccess .
FILE_NON_DIRECTORY_FILE (0x00000040)	Файл не является каталогом. Открываемый объект файла может представлять файл данных; логическое, виртуальное или физическое устройство; или том.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Создайте древовидное подключение для этого файла, чтобы открыть его по сети. Этот флаг не используется устройствами и промежуточными драйверами.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Выполните эту операцию немедленно, используя альтернативный код успешного STATUS_OPLOCK_BREAK_IN_PROGRESS, если целевой файл заблокирован, а не блокирует поток вызывающего объекта. Если файл заблокирован, другой вызывающий объект уже имеет доступ к файлу. Этот флаг не используется устройствами и промежуточными драйверами.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Если расширенные атрибуты (EAs) для открываемого существующего файла указывают на то, что вызывающий объект должен понимать EAs для правильной интерпретации файла, ntCreateFile возвращает ошибку. Этот флаг не имеет отношения к драйверам устройств и промежуточным драйверам.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Зарезервировано для использования системой; не использовать.
FILE_RANDOM_ACCESS (0x00000800)	Доступ к файлу может быть случайным, поэтому драйверы файловой системы или система не должны выполнять последовательные операции упреждающего чтения.
FILE_DELETE_ON_CLOSE (0x00001000)	Система удаляет файл, когда последний дескриптор файла передается в NtClose. Если этот флаг установлен, флаг DELETE должен быть установлен в параметре DesiredAccess .
FILE_OPEN_BY_FILE_ID (0x00002000)	Имя файла, заданное параметром ObjectAttributes , включает двоичный 8-байтовый или 16-байтовый ссылочный номер файла или идентификатор объекта для файла в зависимости от файловой системы. При необходимости имя устройства, за которым следует символ обратной косой черты, может продолжить эти двоичные значения. Дополнительные сведения и пример см. в разделе Примечания.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	Файл открывается для намерения резервного копирования. Поэтому система должна проверка определенные права доступа и предоставить вызывающему объекту соответствующий доступ к файлу, прежде чем проверять параметр DesiredAccess на основе дескриптора безопасности файла. Этот флаг не используется устройствами и промежуточными драйверами.
FILE_NO_COMPRESSION (0x00008000)	Подавление наследования FILE_ATTRIBUTE_COMPRESSED из родительского каталога. Это позволяет создать не сжатый файл в каталоге, который помечен как сжатый.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	Файл открывается, а оппортунистическая блокировка (оппортунистическая блокировка) для файла запрашивается в виде одной атомарной операции. Файловая система проверяет наличие блокировок перед выполнением операции создания и завершит создание ошибкой с кодом возврата STATUS_CANNOT_BREAK_OPLOCK, если результатом будет прерывание существующей блокировки. Этот флаг доступен начиная с Windows 7 и Windows Server 2008 R2.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Если при открытии существующего файла FILE_SHARE_READ не указан и проверки доступа к файловой системе не предоставили вызывающему объекту доступ на запись к файлу, завершится STATUS_ACCESS_DENIED. Это поведение по умолчанию до Windows 7. Этот флаг доступен начиная с Windows 7 и Windows Server 2008 R2.
FILE_SESSION_AWARE (0x00040000)	Клиент, открывающий файл или устройство, учитывает сеанс, и при необходимости проверяется доступ к каждому сеансу. Этот флаг доступен, начиная с Windows 8.
FILE_RESERVE_OPFILTER (0x00100000)	Этот флаг позволяет приложению запрашивать оппортунистическую блокировку фильтра (oplock), чтобы другие приложения не получали нарушения общего доступа. Если дескрипторы уже открыты, запрос на создание завершится ошибкой с STATUS_OPLOCK_NOT_GRANTED. Дополнительные сведения см. в разделе "Примечания".
FILE_OPEN_REPARSE_POINT (0x00200000)	Откройте файл с точкой повторного обработки и обйдите обычную обработку точек повторного перепарирования для файла. Дополнительные сведения см. в разделе "Примечания".
FILE_OPEN_NO_RECALL (0x00400000)	Предписывает фильтрам, выполняющим автономное хранение или виртуализацию, не отзывать содержимое файла в результате этого открытия.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Этот флаг указывает файловой системе записать пользователя, связанного с вызывающим потоком. При любых последующих вызовах FltQueryVolumeInformation или ZwQueryVolumeInformationFile с использованием возвращенного дескриптора предполагается, что для вычисления свободного пространства, доступного вызывающей объекту, используется захваченный пользователь, а не вызывающий пользователь. Это относится к следующим значениям FsInformationClass: FileFsSizeInformation, FileFsFullSizeInformation и FileFsFullSizeInformationEx.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	Интерпретирует параметр EaBuffer как экземпляр EXTENDED_CREATE_INFORMATION. Этот флаг доступен начиная с Windows 11 версии 22H2.

[in, optional] EaBuffer

Для драйверов устройств и промежуточных драйверов этот параметр должен быть указателем NULL .

[in] EaLength

Для драйверов устройств и промежуточных драйверов этот параметр должен быть равен нулю.

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

NtCreateFile возвращает STATUS_SUCCESS при успешном выполнении или соответствующий код ошибки NTSTATUS при сбое. В последнем случае вызывающий объект может определить причину сбоя, проверив параметр IoStatusBlock .

Примечание

NtCreateFile может возвращать STATUS_FILE_LOCK_CONFLICT в качестве возвращаемого значения или в элементе Statusструктуры IO_STATUS_BLOCK , на которую указывает параметр IoStatusBlock . Это произойдет только в том случае, если файл журнала NTFS заполнен, а при попытке NtCreateFile справиться с этой ситуацией возникает ошибка.

NtCreateFile предоставляет дескриптор, который вызывающий объект может использовать для управления данными файла или состоянием и атрибутами файлового объекта. Дополнительные сведения см. в разделе Использование файлов в драйвере.

Когда дескриптор, на который указывает FileHandle , больше не используется, драйвер должен вызвать NtClose , чтобы закрыть его.

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

Существует два альтернативных способа указать имя файла, который будет создан или открыт с помощью NtCreateFile:

В виде полного имени пути, указанного в элементе ObjectName входных атрибутов ObjectAttributes.
Значение pathname относительно файла каталога, представленного дескриптором в элементе RootDirectory входного объекта ObjectAttributes.

Установка определенных флагов в параметре DesiredAccess приводит к следующим последствиям:

Чтобы вызывающий объект синхронизировать завершение ввода-вывода, ожидая возвращаемого объекта FileHandle, необходимо установить флаг SYNCHRONIZE. В противном случае вызывающий объект, который является устройством или промежуточным драйвером, должен синхронизировать завершение ввода-вывода с помощью объекта события.
Если вызывающий объект задает только флаги FILE_APPEND_DATA и SYNCHRONIZE, он может записывать данные только в конец файла, а любые сведения смещения об операциях записи в файл игнорируются. Файл будет автоматически расширен по мере необходимости для операций этого типа.
Установка флага FILE_WRITE_DATA для файла также позволяет вызывающей стороне выполнять запись за пределами конца файла. Опять же, файл автоматически расширяется при необходимости.
Если вызывающий объект задает только флаги FILE_EXECUTE и SYNCHRONIZE, он не может напрямую считывать или записывать данные в файл с помощью возвращенного fileHandle. То есть все операции с файлом выполняются через системный пейджер в ответ на инструкции и операции доступа к данным. Драйверы устройств и промежуточных водителей не должны устанавливать флаг FILE_EXECUTE.

Параметр ShareAccess определяет, могут ли отдельные потоки получать доступ к одному файлу, возможно, одновременно. При условии, что у обоих вызывающих абонентов есть соответствующие права доступа, файл можно успешно открыть и предоставить к ним общий доступ. Если исходный вызывающий объект NtCreateFile не указывает FILE_SHARE_READ, FILE_SHARE_WRITE или FILE_SHARE_DELETE, другой вызывающий объект не может открыть файл, то есть исходному вызывающему объекту предоставляется монопольный доступ.

Чтобы успешно открыть общий файл, флаги DesiredAccess должны быть совместимы с флагами DesiredAccess и ShareAccess всех предыдущих открытых операций, которые еще не были освобождены через . То есть значение DesiredAccess , указанное в ntCreateFile для данного файла, не должно конфликтовать с доступом, запрещенным другими средствами открытия файла.

Значение CreateDisposition FILE_SUPERSEDE требует, чтобы вызывающий объект мог иметь доступ DELETE к существующему объекту файла. Если это так, успешный вызов NtCreateFile с FILE_SUPERSEDE в существующем файле фактически удаляет этот файл, а затем повторно создает его. Это означает, что, если файл уже был открыт другим потоком, он открыл файл, указав параметр ShareAccess с флагом FILE_SHARE_DELETE. Обратите внимание, что этот тип ликвидации соответствует стилю POSIX для перезаписи файлов.

Значения CreateDisposition FILE_OVERWRITE_IF и FILE_SUPERSEDE похожи. Если ntCreateFile вызывается с существующим файлом и любое из этих значений CreateDisposition , файл будет заменен.

Перезапись файла семантически эквивалентна операции замены, за исключением следующего:

Вызывающий объект должен иметь доступ на запись к файлу, а не доступ к удалению. Это означает, что, если файл уже был открыт другим потоком, он открыл файл с флагом FILE_SHARE_WRITE, установленным во входном shareAccess.
Указанные атрибуты файла логически являются ORed с атрибутами, уже имеющимися в файле. Это означает, что если файл уже открыт другим потоком, последующий вызывающий объект NtCreateFile не может отключить существующие флаги FileAttributes , но может включить дополнительные флаги для того же файла. Обратите внимание, что этот стиль перезаписи файлов согласуется с MS-DOS, Microsoft Windows 3.1 и OS/2.

Значение FILE_DIRECTORY_FILE CreateOptions указывает, что создаваемый или открытый файл является каталогом. При создании файла каталога файловая система создает соответствующую структуру на диске, которая представляет пустой каталог для структуры на диске конкретной файловой системы. Если этот параметр был указан, а открываемый файл не является файлом каталога или если вызывающий объект указал несогласованное значение CreateOptions или CreateDisposition , вызов NtCreateFile завершится ошибкой.

Флаг createOptions FILE_NO_INTERMEDIATE_BUFFERING запрещает файловой системе выполнять промежуточную буферизацию от имени вызывающего объекта. Указание этого флага накладывает следующие ограничения на параметры вызывающего объекта для других подпрограмм ZwXxxFile .

Любой необязательный параметр ByteOffset , передаваемый в NtReadFile или NtWriteFile, должен быть кратным размеру сектора.
Длина, передаваемая в NtReadFile или NtWriteFile, должна быть целой частью размера сектора. Обратите внимание, что указание операции чтения в буфер, длина которого точно равна размеру сектора, может привести к тому, что в этот буфер будет передано меньшее количество байтов, если во время передачи был достигнут конец файла.
Буферы должны быть выровнены в соответствии с требованиями к выравниванию базового устройства. Чтобы получить эти сведения, вызовите NtCreateFile , чтобы получить дескриптор для объекта файла, представляющего физическое устройство, и передайте этот дескриптор в NtQueryInformationFile. Список системных значений FILE_XXX_ALIGNMENT см. в разделе DEVICE_OBJECT.
Вызовы NtSetInformationFile с параметром FileInformationClass , для параметра FileInformation, равным FilePositionInformation, должны указывать смещение, кратное размеру сектора.

Флаги FILE_SYNCHRONOUS_IO_ALERT и FILE_SYNCHRONOUS_IO_NONALERT CreateOptions (которые являются взаимоисключающими) указывают, что все операции ввода-вывода с файлом будут синхронными, если операции выполняются через объект файла, на который ссылается возвращаемый ФайлHandle. Все операции ввода-вывода в таком файле сериализуются во всех потоках с помощью возвращенного дескриптора. Если задан любой из этих флагов CreateOptions , необходимо также установить флаг SYNCHRONIZE DesiredAccess , чтобы заставить диспетчер ввода-вывода использовать файловый объект в качестве объекта синхронизации. В таких случаях диспетчер ввода-вывода отслеживает смещение текущей позиции файла, которое можно передать в NtReadFile и NtWriteFile. Вызовите NtQueryInformationFile или NtSetInformationFile , чтобы получить или задать эту позицию.

Если флаг CreateOptions FILE_OPEN_REPARSE_POINT не указан и NtCreateFile пытается открыть файл с точкой повторного обработки, для файла выполняется обычная обработка точек повторного обработки. Если, с другой стороны, указан флаг FILE_OPEN_REPARSE_POINT, обычная обработка повторного обработки не выполняется и NtCreateFile пытается открыть файл точки повторного вычисления напрямую. В любом случае, если операция открытия была успешной, NtCreateFile возвращает STATUS_SUCCESS; В противном случае подпрограмма возвращает код ошибки NTSTATUS. NtCreateFile никогда не возвращает STATUS_REPARSE.

Флаг createOptions FILE_OPEN_REQUIRING_OPLOCK исключает время между открытием файла и запросом блокировки, что может позволить третьей стороне открыть файл и получить нарушение общего доступа. Приложение может использовать флаг FILE_OPEN_REQUIRING_OPLOCK в NtCreateFile , а затем запрашивать любую блокировку. Это гарантирует, что владелец блокировки будет уведомлен о любом последующем открытом запросе, который вызывает нарушение общего доступа.

В Windows 7, если в файле существуют другие дескрипторы, когда приложение использует флаг FILE_OPEN_REQUIRING_OPLOCK, операция создания завершится сбоем с STATUS_OPLOCK_NOT_GRANTED. Это ограничение больше не существует, начиная с Windows 8.

Если эта операция создания приведет к прерыванию блокировки, которая уже существует в файле, установка флага FILE_OPEN_REQUIRING_OPLOCK приведет к сбою операции создания с STATUS_CANNOT_BREAK_OPLOCK. Существующая блокировка не будет нарушена этой операцией создания.

Приложение, использующее флаг FILE_OPEN_REQUIRING_OPLOCK, должно запросить блокировку после успешного вызова, иначе все последующие попытки открыть файл будут заблокированы без обычной обработки блокировки. Аналогичным образом, если этот вызов завершается успешно, но последующий запрос oplock завершается сбоем, приложение, использующее этот флаг, должно закрыть свой дескриптор после обнаружения сбоя запроса на блокировку.

Примечание

Флаг FILE_OPEN_REQUIRING_OPLOCK доступен в операционных системах Windows 7, Windows Server 2008 R2 и более поздних версий. Файловые системы Майкрософт, реализующие этот флаг в Windows 7, — это NTFS, FAT и exFAT.

Флаг CreateOptions FILE_RESERVE_OPFILTER позволяет приложению запрашивать блокировку уровня 1, пакетной службы или фильтра, чтобы другие приложения не получали нарушения общего доступа. Однако FILE_RESERVE_OPFILTER практически полезно только для операций фильтрации. Чтобы использовать его, необходимо выполнить следующие действия.

Выполните запрос на создание с помощью свойств CreateOptions FILE_RESERVE_OPFILTER, DesiredAccess точно FILE_READ_ATTRIBUTES и ShareAccess точно FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Если дескрипторы уже открыты, запрос на создание завершается сбоем с STATUS_OPLOCK_NOT_GRANTED, а следующая запрошенная блокировка также завершается ошибкой.
- Если открыть с большим или меньшим доступом, также произойдет сбой STATUS_OPLOCK_NOT_GRANTED.
Если запрос на создание выполнен успешно, запросите блокировку.
Откройте другой дескриптор файла для выполнения операций ввода-вывода.

Шаг 3 делает это практическим только для операций фильтрации. Дескриптор, открытый на шаге 3, может иметь desiredAccess , содержащий максимум FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL и по-прежнему не прерывать блокировку фильтра. Однако любой объект DesiredAccess , превышающий FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | Функция SYNCHRONIZE разрушит блокировку уровня 1 или пакетной службы и сделает флаг FILE_RESERVE_OPFILTER бесполезным для этих типов блокировки.

NTFS — единственная файловая система Майкрософт, реализующая FILE_RESERVE_OPFILTER.

Для флага CreateOptions FILE_OPEN_BY_FILE_ID пример имени устройства будет иметь следующий формат:

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

Где FileID — 8 байт, а ObjectID — 16 байт:

В NTFS это может быть 8-байтовый или 16-байтовый ссылочный номер или идентификатор объекта. 16-байтовый ссылочный номер совпадает с 8-байтным числом, заполненным нулями.
В ReFS это может быть 8-байтовый или 16-байтовый ссылочный номер. 16-байтовое число не связано с 8-байтным числом. Идентификаторы объектов не поддерживаются.
Файловые системы FAT, ExFAT, UDFS и CDFS не поддерживают флаг FILE_OPEN_BY_FILE_ID.

Этот номер присваивается и зависит от конкретной файловой системы. Так как поле имени файла будет частично содержать двоичный BLOB-объект, неправильно предполагать, что это допустимая строка Юникода и, что более важно, не может быть строкой, завершающейся null.

Вызывающие функции NtCreateFile должны выполняться в IRQL = PASSIVE_LEVEL и с включенными специальными api ядрами.

Примечание

Если вызов этой функции происходит в пользовательском режиме, следует использовать имя NtCreateFile вместо ZwCreateFile.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx и ZwXxx см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs, PowerIrpDDis