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

2025-02-06

Драйверы минифильтра вызывают вызов FltCreateNamedPipeFile для создания нового канала или открытия существующего канала.

Синтаксис

NTSTATUS FLTAPI FltCreateNamedPipeFile(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ULONG                     DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in]            ULONG                     NamedPipeType,
  [in]            ULONG                     ReadMode,
  [in]            ULONG                     CompletionMode,
  [in]            ULONG                     MaximumInstances,
                  ULONG                     InboundQuota,
                  ULONG                     OutboundQuota,
  [in, optional]  PLARGE_INTEGER            DefaultTimeout,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Параметры

[in] Filter

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

[in, optional] Instance

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

[out] FileHandle

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

[out, optional] FileObject

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

[in] DesiredAccess

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

Флаги DesiredAccess	Значение
FILE_READ_DATA	Данные можно считывать из именованного канала.
FILE_READ_ATTRIBUTES	флаги FileAttributes можно считывать. Дополнительные сведения см. в таблице допустимых значений флагов в параметре FileAttributesFltCreateFileEx2.
READ_CONTROL	Список управления доступом (ACL) и сведения о владельце, связанные с именованным каналом, можно считывать.
FILE_WRITE_DATA	Данные можно записать в именованный канал.
FILE_WRITE_ATTRIBUTES	флаги FileAttributes можно записать.
FILE_APPEND_DATA	Данные можно добавить в файл.
WRITE_DAC	Можно записать список управления доступом (DACL), связанный с именованным каналом.
WRITE_OWNER	Сведения о собственности, связанные с именованным каналом, можно записать.
ACCESS_SYSTEM_SECURITY	Вызывающий объект будет иметь доступ на запись к SACL именованного канала
СИНХРОНИЗИРОВАТЬ	Вызывающий объект может синхронизировать завершение операции ввода-вывода, ожидая, пока возвращенный FileHandle будет задано состояние Signaled. Этот флаг необходимо задать, если установлен флаг CreateOptions FILE_SYNCHRONOUS_IO_ALERT или флаг FILE_SYNCHRONOUS_IO_NONALERT.

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

DesiredAccess to File Values	Карты с флагами DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA и СИНХРОНИЗИРОВАТЬ.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA и СИНХРОНИЗИРОВАТЬ.

[in] ObjectAttributes

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

Член	Ценность
длина ULONG	Количество байтов данных, содержащихся в структуре, на которые указывает ObjectAttributes. Это значение должно быть по крайней мере размера(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Указатель на UNICODE_STRING структуру, содержащую имя канала, который должен быть создан или открыт. Это имя должно быть полной спецификацией файла или именем объекта устройства, если он не является именем файла относительно каталога, указанного RootDirectory. Например, "\Device\NamedPipe\mypipe" или "\?? \pipe\mypipe" может быть допустимыми спецификациями файлов. (Примечание. "\??" заменяет "\DosDevices" в качестве имени пространства имен объекта Win32. "\DosDevices" по-прежнему работает, но "\??" преобразуется быстрее диспетчером объектов.)
HANDLE RootDirectory	Необязательный дескриптор каталога, полученный при предыдущем вызове FltCreateFileEx2. Если это значение равно NULL, элемент objectNameдолжен быть полной спецификацией файла, которая включает полный путь к целевому каналу. Если это значение не являетсяNULL, элемент ObjectName указывает имя канала относительно этого каталога.
PSECURITY_DESCRIPTOR SecurityDescriptor	Необязательный дескриптор безопасности (SECURITY_DESCRIPTOR) для применения к каналу. списки управления доступом, указанные таким дескриптором безопасности, применяются только к каналу при его создании. Если значение NULL при создании канала, ACL, помещенный на канал, зависит от файловой системы именованного канала и может разрешить клиенту любой доступ к созданию экземпляра.
атрибуты ULONG	Набор флагов, которые управляют атрибутами объекта файла. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может быть равен нулю. В противном случае вызывающий объект должен задать флаг OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имен должен игнорировать регистр ObjectName вместо выполнения поиска точного соответствия.

[out] IoStatusBlock

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

FILE_CREATED

FILE_OPENED

[in] ShareAccess

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

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

[in] CreateDisposition

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

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

[in] CreateOptions

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

флаги CreateOptions	Значение
FILE_WRITE_THROUGH	Системные службы, системы каналов и драйверы, которые записывают данные в канал, должны фактически передавать данные в канал, прежде чем любая запрошенная операция записи считается завершенной. Этот FILE_NO_INTERMEDIATE_BUFFERING флаг устанавливается автоматически, если установлен флаг CreateOptions.
FILE_SYNCHRONOUS_IO_ALERT	Все операции с каналом выполняются синхронно. Любое ожидание от имени вызывающего абонента подлежит преждевременному прекращению от оповещений. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст положения канала. Если этот флаг задан, необходимо также задать флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект файла в качестве объекта синхронизации.
FILE_SYNCHRONOUS_IO_NONALERT	Все операции с каналом выполняются синхронно. Ожидание синхронизации очереди ввода-вывода и завершения в системе не распространяется на оповещения. Этот флаг также приводит к тому, что система ввода-вывода поддерживает контекст положения файла. Если этот флаг задан, необходимо также задать флаг DesiredAccess SYNCHRONIZE, чтобы диспетчер ввода-вывода использовал объект файла в качестве объекта синхронизации.

[in] NamedPipeType

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

Ценность	Значение
FILE_PIPE_BYTE_STREAM_TYPE	Данные записываются в канал в виде потока байтов. Чтобы использовать этот тип, ReadMode не должно быть FILE_PIPE_MESSAGE_MODE.
FILE_PIPE_MESSAGE_TYPE	Данные записываются в канал в виде сообщения.

[in] ReadMode

Режим чтения из канала.

Ценность	Значение
FILE_PIPE_BYTE_STREAM_MODE	Данные канала считываются как поток байтов.
FILE_PIPE_MESSAGE_MODE	Данные канала считываются как сообщения. Чтобы использовать этот режим, NamedPipeType должны быть FILE_PIPE_MESSAGE_TYPE.

[in] CompletionMode

Режим завершения для операций чтения и записи канала.

Ценность	Значение
FILE_PIPE_QUEUE_OPERATION	Запросы на чтение и запись канала помещаются в очередь и могут блокироваться до завершения.
FILE_PIPE_COMPLETE_OPERATION	Запросы на чтение и запись канала выполняются немедленно.

[in] MaximumInstances

Максимальное количество экземпляров, разрешенных для этого именованного канала.

InboundQuota

Количество байтов для резервирования входного буфера.

OutboundQuota

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

[in, optional] DefaultTimeout

Время ожидания по умолчанию в 100-наносекундах увеличивается. Это значение выражается как отрицательное целое число. Например, 250 миллисекунда указывается как –10 * 1000 * 250.

[in, optional] DriverContext

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

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

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

Возвращаемый код	Описание
STATUS_FLT_DELETING_OBJECT	Фильтр или экземпляр, указанный в параметрах фильтра или экземпляра, отключается. Этот код состояния можно получить, если открытый запрос пересекает точку подключения тома, а параметр экземпляра не являетсяNULL. Это код ошибки.
STATUS_OBJECT_PATH_SYNTAX_BAD	Параметр ObjectAttributes не содержал элемента RootDirectory, но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символ OBJECT_NAME_PATH_SEPARATOR. Этот код ошибки указывает неправильный синтаксис пути к объекту.

Возвращаемый код

Описание

STATUS_FLT_DELETING_OBJECT

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

STATUS_OBJECT_PATH_SYNTAX_BAD

Параметр ObjectAttributes не содержал элемента RootDirectory, но элемент ObjectName в структуре OBJECT_ATTRIBUTES был пустой строкой или не содержал символ OBJECT_NAME_PATH_SEPARATOR. Этот код ошибки указывает неправильный синтаксис пути к объекту.

Замечания

Функция FltCreateNamedPipeFile позволяет драйверам минифильтра создавать или открывать экземпляры каналов. Это полезно для создания виртуальных каналов или создания союзов каналов для мультиплексирования операций ввода-вывода.

Параметр экземпляра является либо NULL, либо устанавливается ранее путем подключения к именованного тома канала. Указатель тома получается путем передачи "\Device\NamedPipe" в качестве имени тома в FltGetVolumeFromName.

Чтобы указать дополнительный параметр создания (ECP) в рамках операции создания, инициализировать элемент ExtraCreateParameter структуры IO_DRIVER_CREATE_CONTEXT с помощью подпрограммы FltAllocateExtraCreateParameter List. Если используются ЕЦП, они должны быть выделены, инициализированы и освобождены с помощью связанных подпрограмм поддержки. При возвращении из вызова FltCreateNamedPipeFileсписок ECP не изменяется и может передаваться в дополнительные вызовы FltCreateNamedPipeFile для других операций создания. Структура списка ECP не будет автоматически освобождена. Вызывающий объект FltCreateNamedPipeFile должен освободить эту структуру путем вызова подпрограммы FltFreeExtraCreateParameterList.

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows 8.
целевая платформа	Всеобщий
заголовка	fltkernel.h (include FltKernel.h)
библиотеки	Fltmgr.lib
IRQL	PASSIVE_LEVEL

См. также

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext