Функция IoCreateFileSpecifyDeviceObjectHint (ntddk.h)

Статья
03/08/2023

Подпрограмма IoCreateFileSpecifyDeviceObjectHint используется драйверами фильтров файловой системы для отправки запроса на создание только в фильтры под указанным объектом устройства и в файловую систему.

Синтаксис

NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
  [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              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options,
  [in, optional] PVOID              DeviceObject
);

Параметры

[out] FileHandle

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

[in] DesiredAccess

Битовая маска флагов, указывающая тип доступа, необходимый вызывающей объекту к файлу или каталогу. Набор системных флагов DesiredAccess определяет следующие конкретные права доступа для файловых объектов.

Флаги DesiredAccess	Значение
DELETE	Файл можно удалить.
FILE_READ_DATA	Данные могут быть считаны из файла.
FILE_READ_ATTRIBUTES	Флаги FileAttributes, описанные далее, можно считать.
FILE_READ_EA	Расширенные атрибуты (EA), связанные с файлом, могут быть прочитаны.
READ_CONTROL	Список управления доступом (ACL) и сведения о владельцах, связанные с файлом, можно считать.
FILE_WRITE_DATA	Данные могут быть записаны в файл.
FILE_WRITE_ATTRIBUTES	Можно записать флаги FileAttributes.
FILE_WRITE_EA	Можно записать расширенные атрибуты, связанные с файлом.
FILE_APPEND_DATA	Данные можно добавить в файл.
WRITE_DAC	Можно записать список управления доступом (DACL), связанный с файлом.
WRITE_OWNER	Можно записать сведения о владельце, связанные с файлом.
SYNCHRONIZE	Вызывающий объект может синхронизировать завершение операции ввода-вывода, ожидая, пока возвращенный файл FileHandle будет установлен в состояние Signaled. Этот флаг должен быть установлен, если установлен флаг CreateOptions FILE_SYNCHRONOUS_IO_ALERT или FILE_SYNCHRONOUS_IO_NONALERT.
FILE_EXECUTE	Данные можно считывать в память из файла с помощью системного ввода-вывода подкачки.

Вызывающие объекты IoCreateFileSpecifyDeviceObjectHint могут указать один или сочетание следующих, возможно, ORed с дополнительными совместимыми флагами из предыдущего списка флаговDesiredAccess для любого объекта файла, который не представляет файл каталога:

DesiredAccess к значениям файла	Сопоставляется с флагами DesiredAccess
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, SYNCHRONIZE, FILE_READ_ATTRIBUTES и FILE_EXECUTE.

STANDARD_RIGHTS_XXX — это предопределенные системные значения, используемые для обеспечения безопасности системных объектов.

Если установлен флаг CreateOptions FILE_DIRECTORY_FILE, вызывающие объекты IoCreateFileSpecifyDeviceObjectHint могут указать один или комбинацию следующих, возможно, ORed с одним или несколькими совместимыми флагами из предыдущего списка флаговDesiredAccess .

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

Флаги DesiredAccess FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE и FILE_APPEND_DATA несовместимы с созданием или открытием файла каталога.

[in] ObjectAttributes

Указатель на структуру OBJECT_ATTRIBUTES , уже инициализированную подпрограммой InitializeObjectAttributes . Если вызывающий объект выполняется в контексте системного процесса, этот параметр (ObjectAttributes) может иметь значение NULL. В противном случае вызывающий объект должен задать атрибут OBJ_KERNEL_HANDLE в вызове подпрограммы InitializeObjectAttributes . Элементы структуры OBJECT_ATTRIBUTES для файлового объекта включают следующее.

Член	Значение
ULONGLength	Указывает количество байтов предоставленных данных ObjectAttributes . Это значение должно быть не менее sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Указатель на буферивированную строку Юникода, именующую создаваемый или открываемый файл. Это значение должно быть полной спецификацией файла, если оно не является именем файла относительно каталога, заданного RootDirectory. Например, \Device\Floppy1\myfile.dat или \?? \B:\myfile.dat может быть полной спецификацией файла при условии, что драйвер дискеты и файловая система с избыточной нагрузкой уже загружены. (Обратите внимание, что \?? заменяет \DosDevices в качестве имени пространства имен объектов Win32. \DosDevices по-прежнему будет работать, но \?? преобразуется быстрее диспетчером объектов.)
HANDLERootDirectory	При необходимости задает дескриптор каталога, который был получен при предыдущем вызове IoCreateFileSpecifyDeviceObjectHint. Если это значение равно NULL, элемент ObjectName должен быть полной спецификацией файла, которая включает полный путь к целевому файлу. Если это значение не равно NULL, элемент ObjectName указывает имя файла относительно этого каталога.
PSECURITY_DESCRIPTOR SecurityDescriptor	При необходимости задает дескриптор безопасности, применяемый к файлу. Списки управления доступом, заданные таким дескриптором безопасности, применяются к файлу только при его создании. Если при создании файла задано значение NULL , список управления доступом, размещенный в файле, зависит от файловой системы; большинство файловых систем распространяет часть такого списка управления доступом из родительского файла каталога в сочетании с ACL вызывающего объекта по умолчанию.
ULONGAttributes	Набор флагов, управляющий атрибутами объекта файла. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может быть равен нулю. В противном случае вызывающий объект должен установить флаг OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имени должен игнорировать регистр ObjectName , а не выполнять поиск точного соответствия.

[out] IoStatusBlock

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

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

При необходимости задает начальный размер выделения (в байтах) для файла. Ненулевое значение не оказывает никакого влияния, если только файл не создается, не перезаписывается или не заменяет его.

[in] FileAttributes

Явно указанные атрибуты применяются только при создании, замене или перезаписи файла. По умолчанию это значение FILE_ATTRIBUTE_NORMAL, которое может быть переопределено любым другим флагом или сочетанием совместимых флагов ORed. Возможные флаги FileAttributes включают следующие.

Флаги FileAttributes	Значение
FILE_ATTRIBUTE_NORMAL	Необходимо создать файл со стандартными атрибутами.
FILE_ATTRIBUTE_READONLY	Необходимо создать файл, доступный только для чтения.
FILE_ATTRIBUTE_HIDDEN	Должен быть создан скрытый файл.
FILE_ATTRIBUTE_SYSTEM	Необходимо создать системный файл.
FILE_ATTRIBUTE_ARCHIVE	Файл должен быть помечен так, чтобы он был архивирован.
FILE_ATTRIBUTE_TEMPORARY	Необходимо создать временный файл.

[in] ShareAccess

Указывает тип доступа к файлу, который требуется вызывающей объекту, равный нулю, единице или сочетанию следующих флагов. Чтобы запросить монопольный доступ, задайте для этого параметра нулевое значение. Если флаг IO_IGNORE_SHARE_ACCESS_CHECK указан в параметре Options , диспетчер ввода-вывода игнорирует этот параметр. Однако файловая система может по-прежнему выполнять проверки доступа. Таким образом, важно указать режим общего доступа для этого параметра, даже если используется флаг IO_IGNORE_SHARE_ACCESS_CHECK. Чтобы с наибольшей вероятностью избежать ошибок нарушения общего доступа, укажите все следующие флаги общего доступа.

Флаги ShareAccess	Значение
FILE_SHARE_READ	Файл можно открыть для чтения другими потоками.
FILE_SHARE_WRITE	Файл можно открыть для записи другими потоками.
FILE_SHARE_DELETE	Файл может быть открыт для удаления доступа другими потоками.

[in] Disposition

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

Значения перед ликвидацией	Значение
FILE_SUPERSEDE	Если файл уже существует, замените его указанным файлом. Если это не так, создайте указанный файл.
FILE_CREATE	Если файл уже существует, завершите запрос и не создавайте и не открывайте указанный файл. Если это не так, создайте указанный файл.
FILE_OPEN	Если файл уже существует, откройте его вместо создания нового. Если это не так, выполните запрос и не создавайте новый файл.
FILE_OPEN_IF	Если файл уже существует, откройте его. Если это не так, создайте указанный файл.
FILE_OVERWRITE	Если файл уже существует, откройте его и перезапишите. Если это не так, запрос завершится ошибкой.
FILE_OVERWRITE_IF	Если файл уже существует, откройте его и перезапишите. Если это не так, создайте указанный файл.

[in] CreateOptions

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

Флаги CreateOptions	Значение
FILE_DIRECTORY_FILE	Создаваемый или открываемый файл является файлом каталога. Если этот флаг установлен, для параметра Disposition необходимо задать одно из FILE_CREATE, FILE_OPEN или FILE_OPEN_IF. Этот флаг совместим со следующими флагами CreateOptions : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT и FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE	Открываемый файл не должен быть файлом каталога, иначе этот вызов завершится ошибкой. Открываемый объект файла должен представлять файл данных.
FILE_WRITE_THROUGH	Системные службы, FSD и драйверы, которые записывают данные в файл, должны фактически передавать данные в файл, прежде чем любая запрошенная операция записи будет считаться завершенной.
FILE_SEQUENTIAL_ONLY	Все доступы к файлу будут последовательными.
FILE_RANDOM_ACCESS	Доступ к файлу может быть случайным, поэтому не следует выполнять последовательные операции упреждающего чтения с файлом с помощью FSD или системы.
FILE_NO_INTERMEDIATE_BUFFERING	Файл не может быть кэширован или помещен во внутренние буферы драйвера. Этот флаг несовместим с флагом DesiredAccess FILE_APPEND_DATA.
FILE_SYNCHRONOUS_IO_ALERT	Все операции с файлом выполняются синхронно. Любое ожидание от имени звонящего зависит от преждевременного завершения оповещений. Этот флаг также приводит к тому, что система ввода-вывода будет поддерживать контекст позиции файла. Если этот флаг установлен, необходимо также установить флаг DesiredAccess SYNCHRONIZE.
FILE_SYNCHRONOUS_IO_NONALERT	Все операции с файлом выполняются синхронно. Ожидания, существующие в системе для синхронизации очередей и завершения операций ввода-вывода, не подлежат оповещениям. Этот флаг также приводит к тому, что система ввода-вывода будет поддерживать контекст позиции файла. Если этот флаг установлен, необходимо также установить флаг DesiredAccess SYNCHRONIZE.
FILE_CREATE_TREE_CONNECTION	Создайте подключение в виде дерева для этого файла, чтобы открыть его по сети.
FILE_COMPLETE_IF_OPLOCKED	Выполните эту операцию немедленно, используя альтернативный код успешного выполнения, если целевой файл заблокирован, а не блокирует поток вызывающего объекта. Если файл заблокирован, другой вызывающий объект уже имеет доступ к файлу по сети.
FILE_NO_EA_KNOWLEDGE	Если расширенные атрибуты в открываемом существующем файле указывают на то, что вызывающий объект должен понимать EAs для правильной интерпретации файла, выполните этот запрос, так как вызывающий объект не понимает, как работать с EAs.
FILE_OPEN_REPARSE_POINT	Откройте файл с точкой повторного обработки и обйдите обычную обработку точек повторного обработки для файла. Дополнительные сведения см. в разделе Примечания ниже.
FILE_DELETE_ON_CLOSE	Удалите файл при передаче последнего дескриптора в ZwClose.
FILE_OPEN_BY_FILE_ID	Имя файла, указанное в параметре ObjectAttributes , включает 8-байтовый номер ссылки на файл. Этот номер назначается файловой системой и зависит от файловой системы. Если файл является точкой повторного обновления, имя файла также включает имя устройства. Примечание. Файловая система FAT не поддерживает FILE_OPEN_BY_FILE_ID.
FILE_OPEN_FOR_BACKUP_INTENT	Файл открывается с целью резервного копирования, поэтому система должна проверка определенные права доступа и предоставить вызывающему объекту соответствующие доступы к файлу перед проверкой входных данных DesiredAccess с дескриптором безопасности файла.
FILE_OPEN_REQUIRING_OPLOCK	Файл открывается и запрашивается оппортунистическая блокировка (oplock) файла в виде одной атомарной операции. Файловая система проверяет наличие блокировок перед выполнением операции создания, и операция создания завершается сбоем с кодом возврата STATUS_CANNOT_BREAK_OPLOCK, если создание разорвет существующую блокировку.
FILE_RESERVE_OPFILTER	Этот флаг позволяет приложению запрашивать фильтрацию оппортунистической блокировки (oplock), чтобы предотвратить нарушения общей папки в других приложениях. Если дескрипторы уже открыты, запрос на создание завершается сбоем с STATUS_OPLOCK_NOT_GRANTED. Дополнительные сведения см. в разделе "Примечания".

[in, optional] EaBuffer

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

[in] EaLength

Длина (в байтах) EaBuffer.

[in] CreateFileType

Драйверы должны задать для этого параметра значение CreateFileTypeNone.

[in, optional] InternalParameters

Драйверы должны задать для этого параметра значение NULL.

[in] Options

Задает параметры, используемые во время создания запроса на создание. В следующей таблице перечислены доступные варианты.

Флаги параметров	Значение
IO_FORCE_ACCESS_CHECK	Указывает, что диспетчер ввода-вывода должен проверка запрос на создание к дескриптору безопасности файла.
IO_IGNORE_SHARE_ACCESS_CHECK	Указывает, что диспетчер операций ввода-вывода не должен выполнять проверки доступа к общей папке для объекта файла после его создания. Однако файловая система может по-прежнему выполнять эти проверки.

[in, optional] DeviceObject

Указатель на объект устройства, которому должен быть отправлен запрос на создание. Объект устройства должен быть фильтром или объектом устройства файловой системы в стеке драйверов файловой системы для тома, на котором находится файл или каталог. Этот параметр является необязательным и может иметь значение NULL. Если этот параметр имеет значение NULL, запрос будет отправлен объекту устройства в верхней части стека драйверов.

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

IoCreateFileSpecifyDeviceObjectHint возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	Указанный Объект DeviceObject не подключен к стеку драйверов файловой системы для тома, указанного в имени файла или каталога. Эта ошибка также может возникать, если имя содержит точку повторного анализа, отличаемую от точки подключения.
STATUS_MOUNT_POINT_NOT_RESOLVED	Имя файла или каталога содержит точку подключения, которая разрешается в том, отличный от тома, к которому подключен указанный DeviceObject .
STATUS_OBJECT_PATH_SYNTAX_BAD

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

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

Подпрограмма IoCreateFileEx в Windows Vista аналогична процедуре IoCreateFileSpecifyDeviceObjectHint , но предоставляет более широкие функциональные возможности, чем процедура IoCreateFileSpecifyDeviceObjectHint , включая доступ к дополнительным параметрам создания (ECP) и сведениям о транзакциях.

Если вы используете подпрограмму IoCreateFileEx вместо процедуры IoCreateFileSpecifyDeviceObjectHint , обратите внимание, что параметр DriverContextподпрограммы IoCreateFileSpecifyDeviceObjectHint был перемещен в элемент DeviceObjectHint структуры IO_DRIVER_CREATE_CONTEXT . Структура IO_DRIVER_CREATE_CONTEXT передается в подпрограмму IoCreateFileEx с помощью параметра DriverContext .

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

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

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

Любой дескриптор, полученный из IoCreateFileSpecifyDeviceObjectHint , в конечном итоге должен быть освобожден путем вызова ZwClose.

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

Некоторые флаги DesiredAccess и сочетания флагов имеют следующие эффекты:

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

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

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

Если IO_IGNORE_SHARE_ACCESS_CHECK указано в параметре Options , диспетчер ввода-вывода игнорирует параметр ShareAccess . Однако файловая система может по-прежнему выполнять проверки доступа. Поэтому важно указать режим общего доступа для параметра ShareAccess , даже если используется флаг IO_IGNORE_SHARE_ACCESS_CHECK.

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

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

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

Вызывающий объект должен иметь доступ на запись к файлу, а не доступ к удалению. Это означает, что если файл уже был открыт другим потоком, он открыл файл с флагом FILE_SHARE_WRITE, установленным во входном shareAccess.
Указанные атрибуты файла логически определяются вместе с атрибутами, уже имеющимися в файле. Это означает, что если файл уже открыт другим потоком, последующий вызывающий объект IoCreateFileSpecifyDeviceObjectHint не может отключить существующие флаги FileAttributes , но может включить дополнительные флаги для того же файла.

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

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

Любое значение смещения байтов, передаваемое в ZwReadFile или ZwWriteFile, должно быть кратно размеру сектора базового устройства.
Длина, передаваемая в ZwReadFile или ZwWriteFile, должна быть кратна размеру сектора. Обратите внимание, что указание операции чтения в буфер, длина которого точно равна размеру сектора, может привести к меньшему числу значительных байтов, передаваемых в этот буфер, если во время передачи был достигнут конец файла.
Буферы должны быть выровнены в соответствии с требованиями выравнивания базового устройства. Эти сведения можно получить, вызвав IoCreateFileSpecifyDeviceObjectHint , чтобы получить дескриптор для объекта файла, представляющего физическое устройство, а затем вызвав ZwQueryInformationFile с этим дескриптором. Список системных значений FILE_XXX_ALIGNMENT см. в разделе DEVICE_OBJECT.
Вызовы ZwSetInformationFile с параметром FileInformationClass, для параметра FileInformationClass , равным FilePositionInformation, должны указывать смещение, кратное размеру сектора.

Взаимоисключающие функции CreateOptions, FILE_SYNCHRONOUS_IO_ALERT и FILE_SYNCHRONOUS_IO_NONALERT, указывают, что все операции ввода-вывода с файлом должны быть синхронными, если они выполняются через объект file, на который ссылается возвращаемый FileHandle. Все операции ввода-вывода в таком файле сериализуются во всех потоках с помощью возвращенного дескриптора. При использовании любого из этих свойств CreateOptions необходимо установить флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект файла в качестве объекта синхронизации. При любом из этих наборов CreateOptions диспетчер операций ввода-вывода поддерживает "контекст позиции файла" для объекта файла, внутреннее смещение текущей позиции файла. Это смещение можно использовать в вызовах ZwReadFile и ZwWriteFile. Его положение также можно запросить путем вызова ZwQueryInformationFile или задать путем вызова ZwSetInformationFile.

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

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

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

Если эта операция создания приведет к прерыванию блокировки, которая уже существует в файле, установка флага FILE_OPEN_REQUIRING_OPLOCK приведет к сбою операции создания с STATUS_CANNOT_BREAK_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, может иметь 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.

IoCreateFileSpecifyDeviceObjectHint нельзя использовать для получения дескриптора тома.

Если путь к имени файла, передаваемый в IoCreateFileSpecifyDeviceObjectHint , содержит точку повторного анализов, точка повторного анализов должна разрешаться в том же томе, где находится файл или каталог. В противном случае возвращается ошибка STATUS_INVALID_DEVICE_OBJECT_PARAMETER или STATUS_MOUNT_POINT_NOT_RESOLVED.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h, Ntifs.h, FltKernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL