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

Подпрограмма 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 определяет следующие конкретные права доступа для файловых объектов.

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

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

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

[in] ObjectAttributes

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

[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 включают следующие.

[in] ShareAccess

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

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

[in] Disposition

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

[in] CreateOptions

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

[in, optional] EaBuffer

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

[in] EaLength

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

[in] CreateFileType

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

[in, optional] InternalParameters

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

[in] Options

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

[in, optional] DriverContext

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

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

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

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

1. Отправьте запрос на создание с помощью 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.

2. Если запрос на создание выполнен успешно, запросите блокировку операции.

3. Откройте другой дескриптор файла для выполнения операций ввода-вывода.

Шаг 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 можно использовать для получения дескриптора тома.

Требования

См. также раздел

ACCESS_MASK

ACL

DEVICE_OBJECT

FILE_FULL_EA_INFORMATION

FltAcknowledgeEcp

FltAllocateExtraCreateParameter

FltAllocateExtraCreateParameterList

FltClose

FltCreateFileEx2

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoCreateFile

IoCreateFileSpecifyDeviceObjectHint

UNICODE_STRING

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile