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

Статья
03/08/2023

Подпрограмма IoCreateFileEx либо создает новый файл или каталог, либо открывает существующий файл, устройство, каталог или том и предоставляет вызывающей объекту дескриптор. Драйверы фильтров файловой системы (устаревшие драйверы фильтров) вызывают эту подпрограмму.

Синтаксис

NTSTATUS IoCreateFileEx(
  [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] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Параметры

[out] FileHandle

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

[in] DesiredAccess

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

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

Кроме того, для любого объекта файла, который не представляет каталог, можно указать один или несколько следующих универсальных флагов ACCESS_MASK. Флаги STANDARD_RIGHTS_XXX — это предопределенные системные значения, которые используются для обеспечения безопасности системных объектов. Вы также можете объединить эти универсальные флаги с дополнительными флагами из предыдущей таблицы.

Требуемый доступ к значениям файлов	Сопоставляется с флагами 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.

Для каталогов (FILE_DIRECTORY_FILE установлен флаг CreateOptions ) можно указать один или несколько следующих флагов ACCESS_MASK, которые также можно объединить с любыми совместимыми флагами, описанными ранее.

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

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

[in] ObjectAttributes

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

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

[out] IoStatusBlock

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

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

Явно указанные атрибуты применяются только при создании, замене или перезаписи файла. По умолчанию это значение равно FILE_ATTRIBUTE_NORMAL, которое может быть переопределено любым другим флагом или сочетанием (с помощью побитовой операции ИЛИ) совместимых флагов. Возможные флаги 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 , диспетчер ввода-вывода игнорирует параметр ShareAccess . Однако файловая система может по-прежнему выполнять проверки доступа. Таким образом, важно указать режим общего доступа для этого параметра, даже если вы используете флаг IO_IGNORE_SHARE_ACCESS_CHECK. Чтобы избежать ошибок нарушения общего доступа, укажите все следующие флаги общего доступа.

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

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

[in] Disposition

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

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

[in] CreateOptions

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

Флаг CreateOptions	Значение
FILE_DIRECTORY_FILE (0x00000001)	Создаваемый или открываемый файл является файлом каталога. При использовании этого флага параметру 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_WRITE_THROUGH (0x00000002)	Системные службы, файловые системы и драйверы, которые записывают данные в файл, должны фактически передать данные в файл, прежде чем любая запрошенная операция записи будет считаться завершенной.
FILE_SEQUENTIAL_ONLY (0x00000004)	Все доступы к файлу будут последовательными.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	Файл не может быть кэширован или помещен во внутренние буферы драйвера. Этот флаг несовместим с флагом DesiredAccessFILE_APPEND_DATA.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Все операции с файлом выполняются синхронно. Любое ожидание от имени вызывающей стороны может быть связано с преждевременным завершением оповещений. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст позиции файла. Если этот флаг установлен, необходимо также установить флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал файловый объект в качестве объекта синхронизации.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Все операции с файлом выполняются синхронно. Ожидания в системе для синхронизации очереди ввода-вывода и завершения не подлежат оповещениям. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст позиции файла. Если этот флаг установлен, необходимо также установить флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал файловый объект в качестве объекта синхронизации.
FILE_NON_DIRECTORY_FILE (0x00000040)	Открываемый файл не должен быть файлом каталога, иначе этот вызов завершается ошибкой. Открываемый объект файла может представлять файл данных; логическое, виртуальное или физическое устройство; или том.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Создайте древовидное подключение для этого файла, чтобы открыть его по сети.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Выполните эту операцию немедленно с альтернативным кодом успешного выполнения, если целевой файл заблокирован, а не блокирует поток вызывающего объекта. Если файл заблокирован, другой вызывающий объект уже имеет доступ к файлу по сети.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Если открытые расширенные атрибуты в существующем файле указывают на то, что вызывающий объект должен понимать расширенные атрибуты для правильной интерпретации файла, этот запрос завершится ошибкой, так как вызывающий объект не понимает, как работать с расширенными атрибутами.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Зарезервировано для использования системой; не использовать.
FILE_RANDOM_ACCESS (0x00000800)	Доступ к файлу может быть случайным, поэтому файловые системы или операционная система не должны выполнять с файлом последовательные операции упреждающего чтения.
FILE_DELETE_ON_CLOSE (0x00001000)	Удалите файл при передаче последнего дескриптора в FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	Файл открывается по идентификатору. Имя файла содержит имя устройства и 64-разрядный идентификатор, используемый для открытия файла.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	Файл открывается для намерения резервного копирования; Поэтому система должна проверка определенные права доступа и предоставить вызывающему объекту соответствующие доступы к файлу, прежде чем проверять входные данные 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.
FILE_SESSION_AWARE (0x00040000)	Файл или устройство открывается с пониманием сеанса. Если этот флаг не указан, то устройства для сеанса (например, устройства, использующие перенаправление USB RemoteFX) не могут быть открыты процессами, выполняемыми в сеансе 0. Этот флаг не действует для вызывающих абонентов, не в сеансе 0. Этот флаг поддерживается только в серверных выпусках Windows. Этот флаг не поддерживается до Windows Server 2012.
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.

[in, optional] EaBuffer

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

[in] EaLength

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

[in] CreateFileType

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

[in, optional] InternalParameters

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

[in] Options

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

Флаг параметров	Значение
IO_FORCE_ACCESS_CHECK	Диспетчер операций ввода-вывода должен проверка запрос на создание к дескриптору безопасности файла. Дополнительные сведения см. в подразделе "Примечания".
IO_IGNORE_SHARE_ACCESS_CHECK	Диспетчер операций ввода-вывода не должен выполнять проверки доступа к общей папке для файлового объекта после его создания. Однако файловая система может по-прежнему выполнять эти проверки.
IO_STOP_ON_SYMLINK	Если при открытии или создании файла обнаруживается соединение, символьная ссылка или глобальная точка повторного вскрытия, диспетчер ввода-вывода вернет STATUS_STOPPED_ON_SYMLINK. Кроме того, в IoStatusBlock-Information> будет возвращена структура REPARSE_DATA_BUFFER. Вызывающий объект отвечает за освобождение структуры REPARSE_DATA_BUFFER .
IO_OPEN_TARGET_DIRECTORY	Откройте родительский каталог файла.

[in, optional] DriverContext

Необязательный указатель на структуру IO_DRIVER_CREATE_CONTEXT , которая ранее была инициализирована подпрограммой IoInitializeDriverCreateContext . Структуру IO_DRIVER_CREATE_CONTEXT можно использовать для передачи дополнительных параметров подпрограммам IoCreateFileEx и FltCreateFileEx2 . Дополнительные сведения см. в следующем разделе Примечаний.

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

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

Код возврата	Описание
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx возвращает это значение состояния, если параметр DriverContext не имеет значения NULL и если указанный объект устройства не присоединен к стеку драйверов файловой системы для тома, указанного в имени файла или каталога. Этот объект устройства задается элементом DeviceObjectHint структуры IO_DRIVER_CREATE_CONTEXT. Дополнительные сведения см. в разделе IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx возвращает это значение состояния, если параметр DriverContext не равен NULL и если имя файла или каталога содержит точку подключения, которая разрешается в том, отличный от тома, к которому присоединен указанный объект устройства. Этот объект устройства задается элементом DeviceObjectHint структуры IO_DRIVER_CREATE_CONTEXT. Дополнительные сведения см. в разделе IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx возвращает это значение состояния, если параметр ObjectAttributes не содержал элемента RootDirectory , но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символа OBJECT_NAME_PATH_SEPARATOR. Это указывает на неправильный синтаксис пути к объекту.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx возвращает это значение состояния, если установлен флаг параметра OptionsIO_STOP_ON_SYMLINK и при открытии или создании файла обнаружена символьная ссылка.

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

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

Подпрограмма IoCreateFileEx похожа на подпрограмму IoCreateFile и IoCreateFileSpecifyDeviceObjectHint, но предоставляет дополнительные функции, включая доступ к дополнительным параметрам создания (ECP), указаниям объектов устройств и сведениям о транзакциях с помощью параметра DriverContext подпрограммы IoCreateFileEx. Дополнительные сведения об этих параметрах на основе структуры см. в разделе IO_DRIVER_CREATE_CONTEXT.

Драйверы фильтров файловой системы вызывают IoCreateFileEx для отправки запроса на создание только указанному объекту устройства, подключенным к ним фильтрам и файловой системе. Фильтры, подключенные над указанным объектом устройства в стеке драйверов, не получают запрос на создание. Однако если элемент DeviceObjectHint структуры IO_DRIVER_CREATE_CONTEXT (передаваемый через параметр DriverContext ) имеет значение NULL, запрос направляется в верхнюю часть стека и получается всеми фильтрами и файловой системой.

Если запрос ввода-вывода не переходит в верхнюю часть стека драйверов, то есть если параметр DriverContext не имеет значения NULL и допустимый объект устройства указан членом DeviceObjectHint структуры IO_DRIVER_CREATE_CONTEXT, применяется следующее ограничение:

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

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

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

В виде полного имени пути, указанного в элементе ObjectName входного параметра ObjectAttributes .
Как путь относительно дескриптора в элементе RootDirectory входного параметра ObjectAttributes . (Этот дескриптор может представлять файл каталога.)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Флаг CreateOptions , FILE_RESERVE_OPFILTER, позволяет приложению запрашивать oplock уровня 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 делает это практичным только для фильтров oplock. Дескриптор, открытый на шаге 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 бесполезным для этих типов oplock.

Если для запросов на создание, исходящих в пользовательском режиме, драйвер задает IO_FORCE_ACCESS_CHECK в параметре OptionsioCreateFileEx , он также должен задать OBJ_FORCE_ACCESS_CHECK в параметре ObjectAttributes . Сведения об этом флаге см. в разделе АтрибутыOBJECT_ATTRIBUTES.

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

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

Требования

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