Функция FltCreateFileEx2 (fltkernel.h)

Статья
03/08/2023

Драйверы минифильтра вызывают FltCreateFileEx2 , чтобы создать новый файл или открыть существующий файл. Эта подпрограмма включает необязательный параметр контекста создания (ECP).

Синтаксис

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Параметры

[in] Filter

Указатель непрозрачного фильтра для вызывающего объекта.

[in, optional] Instance

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

[out] FileHandle

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

[out, optional] FileObject

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

[in] DesiredAccess

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

[in] ObjectAttributes

Указатель на непрозрачную структуру OBJECT_ATTRIBUTES , которая уже инициализирована с помощью Атрибутов InitializeObjectAttributes. Дополнительные сведения и описание каждого элемента структуры см. в разделе Параметр ObjectAttributesioCreateFileEx .

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения о запрошенной операции. Дополнительные сведения об этом параметре см. в разделе Параметр IoStatusBlockioCreateFileEx .

[in, optional] AllocationSize

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

[in] FileAttributes

Указывает один или несколько флагов FILE_ATTRIBUTE_XXX, которые представляют атрибуты файла, которые необходимо задать при создании, замене или перезаписи файла. Дополнительные сведения и список флагов см. в разделе Параметр FileAttributesioCreateFileEx .

[in] ShareAccess

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

[in] CreateDisposition

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

[in] CreateOptions

Указывает параметры, применяемые при создании или открытии файла. Этот параметр является совместимым сочетанием флагов, перечисленных и описанных в параметре CreateOptionsобъекта IoCreateFileEx.

[in, optional] EaBuffer

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

[in] EaLength

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

[in] Flags

Задает параметры, используемые во время создания запроса на создание. Список возможных параметров см. в разделе ПараметрыIoCreateFileEx .

[in, optional] DriverContext

Необязательный указатель на структуру IO_DRIVER_CREATE_CONTEXT , уже инициализированную IoInitializeDriverCreateContext.

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

FltCreateFileEx2 возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS. Список возможных кодов возврата см. в разделе Возвращаемое значениеioCreateFileEx .

Примечание

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

Чтобы указать ECP в рамках операции создания, инициализируйте элемент ExtraCreateParameter структуры IO_DRIVER_CREATE_CONTEXT с помощью процедуры FltAllocateExtraCreateParameterList . Если используются ECP, их необходимо создавать, манипулировать и освобождать с помощью соответствующих процедур.

Драйверы фильтрации под вызывающим элементом FltCreateFileEx2 не должны добавлять или удалять ecp в вызывающем объекте. Следовательно, при возвращении из вызова FltCreateFileEx2 список ECP должен быть без изменений и может быть передан в дополнительные вызовы FltCreateFileEx2 для других операций создания. Обратите внимание, что операционная система не освобождает структуру списка ECP автоматически. Вызывающий объект FltCreateFileEx2 должен отменить выделение этой структуры, вызвав подпрограмму FltFreeExtraCreateParameterList .

Чтобы создать или открыть файл в контексте транзакции, задайте для элемента TxnParameters структуры IO_DRIVER_CREATE_CONTEXT значение, возвращаемое подпрограммой IoGetTransactionParameterBlock .

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

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

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

Все fileHandle , полученные из FltCreateFileEx2 , в конечном итоге должны быть освобождены путем вызова FltClose. Кроме того, любой возвращенный указатель FileObject должен быть разыменован, если он больше не нужен путем вызова ObDereferenceObject.

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

Примечание

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Драйверы минифильтра должны использовать FltSetInformationFile, а не ZwSetInformationFile, чтобы переименовать файл.

Примечание

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

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

Не следует использовать FltCreateFileEx2 , чтобы открыть дескриптор с прямым доступом к устройству хранения тома, иначе системные ресурсы будут утечки. Если вы хотите открыть дескриптор с прямым доступом к устройству хранения, вызовите вместо него функцию IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint или ZwCreateFile .

Если вызывающий объект FltCreateFileEx2 хочет включить повторное просмотр для целевого объекта тома, FLT_CREATEFILE_TARGET_ECP_CONTEXT можно включить в качестве ECP в список ECP в параметре DriverContext . Если этот ECP присутствует, FltCreateFileEx2 настроит целевое устройство для операции создания и попытается найти отфильтрованный экземпляр тома, соответствующего данным о файлах. Использование этого ECP доступно начиная с Windows 8.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows Vista.
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая FltKernel.h)
Библиотека	Fltmgr.lib
IRQL	PASSIVE_LEVEL