Функция 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	Значение
УДАЛИТЬ	Файл можно удалить.
FILE_READ_DATA	Данные можно считывать из файла.
FILE_READ_ATTRIBUTES	флаги fileAttributes, описанные ниже, можно прочитать.
FILE_READ_EA	Расширенные атрибуты (EAS), связанные с файлом, можно считывать.
READ_CONTROL	Список управления доступом (ACL) и сведения о владельце, связанные с файлом, можно считывать.
FILE_WRITE_DATA	Данные можно записать в файл.
FILE_WRITE_ATTRIBUTES	флаги FileAttributes можно записать.
FILE_WRITE_EA	EAs, связанные с файлом, можно записать.
FILE_APPEND_DATA	Данные можно добавить в файл.
WRITE_DAC	Список управления доступом (DACL), связанный с файлом, можно записать.
WRITE_OWNER	Сведения о собственности, связанные с файлом, можно записать.
СИНХРОНИЗИРОВАТЬ	Вызывающий объект может синхронизировать завершение операции ввода-вывода, ожидая, пока возвращенный 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, СИНХРОНИЗАЦИЯ.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, СИНХРОНИЗАЦИЯ.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, СИНХРОНИЗАЦИЯ, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

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

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

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

[in] ObjectAttributes

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

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

[out] IoStatusBlock

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

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

Явно указанные атрибуты применяются только при создании, замене файла или перезаписи. По умолчанию это значение FILE_ATTRIBUTE_NORMAL, которое можно переопределить любым другим флагом или сочетанием (через побитовую операцию OR) совместимых флагов. Возможные флаги 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 указан в параметре параметры, диспетчер ввода-вывода игнорирует параметр 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)	Созданный или открытый файл — это файл каталога. При использовании этого флага параметр ликвидации должен иметь значение одного из 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)	Файл открывается, а оппортунистическая блокировка (oplock) файла запрашивается как одна атомарная операция. Файловая система проверяет наличие оплоков перед выполнением операции создания, и операция создания завершится ошибкой с помощью возвращаемого кода STATUS_CANNOT_BREAK_OPLOCK если операция создания разорвит существующий 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. Кроме того, структура REPARSE_DATA_BUFFER будет возвращена в IoStatusBlock->Information. Вызывающий объект отвечает за освобождение 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 возвращает это значение состояния, если установлен флаг параметра параметры IO_STOP_ON_SYMLINK, а при открытии или создании файла возникает символьная ссылка.

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

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

Замечания

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

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

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

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

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

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

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

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

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

Чтобы вызывающий объект синхронизировал завершение ввода-вывода, ожидая, что возвращенный FileHandle будет задано состояние Signaled, необходимо задать флаг SYNCHRONIZE. В противном случае вызывающий объект, который является устройством или промежуточным драйвером, должен синхронизировать завершение ввода-вывода с помощью объекта события.
Если заданы только флаги FILE_APPEND_DATA и СИНХРОНИЗАЦИИ, вызывающий объект может записывать только в конец файла, а любые сведения о смещении записи в файл игнорируются. Однако файл будет автоматически расширен по мере необходимости для этой операции записи.
Установка флага FILE_WRITE_DATA для файла также позволяет записывать данные за пределы конца файла. Файл автоматически расширяется для такого типа записи, а также.
Если заданы только флаги FILE_EXECUTE и СИНХРОНИЗАЦИИ, вызывающий объект не может напрямую считывать или записывать данные в файле с помощью возвращенной 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 указан в параметре параметров, диспетчер ввода-вывода игнорирует параметр ShareAccess. Однако файловая система может по-прежнему выполнять проверки доступа. Таким образом, важно указать режим общего доступа для параметра ShareAccess, даже если используется флаг IO_IGNORE_SHARE_ACCESS_CHECK.

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

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

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

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

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

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

Любые необязательные ByteOffset, передаваемые в ZwReadFile или ZwWriteFile должны быть целочисленными (целыми числами) размера сектора.
длина, передаваемая ZwReadFile или ZwWriteFile, должна быть неотъемлемой частью размера сектора. Обратите внимание, что указание операции чтения в буфер, длина которого точно равна размеру сектора, может привести к меньшему количеству значительных байтов, передаваемых в этот буфер, если конец файла был достигнут во время передачи.
Буферы должны быть выровнены в соответствии с требованием выравнивания базового устройства. Эти сведения можно получить путем вызова IoCreateFileEx для получения дескриптора для объекта файла, представляющего физическое устройство, а затем вызова ZwQueryInformationFile с этим дескриптором. Список значений FILE_XXX_ALIGNMENT системы см. в DEVICE_OBJECT.
Вызовы ZwSetInformationFile с параметром 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 R2and позже. Файловые системы Майкрософт, реализующие этот флаг, — 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 | СИНХРОНИЗАЦИЯ | READ_CONTROL и по-прежнему не прерывать блокировку фильтра. Тем не менее, любой DesiredAccess больше FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | СИНХРОНИЗАЦИЯ разорвит уровень 1 или пакетную блокировку и сделает флаг FILE_RESERVE_OPFILTER бесполезным для этих типов oplock.

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

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

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

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	ntddk.h (include Ntddk.h, Ntifs.h, FltKernel.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL