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

Драйверы минифильтра вызывают 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 можно считать. Дополнительные сведения см. в таблице допустимых значений флагов в параметре FileAttributesобъекта FltCreateFileEx2.
READ_CONTROL	Список управления доступом (ACL) и сведения о владельцах, связанные с именованным каналом, можно считывать.
FILE_WRITE_DATA	Данные можно записать в именованный канал.
FILE_WRITE_ATTRIBUTES	Можно записывать флаги FileAttributes.
FILE_APPEND_DATA	Данные можно добавить в файл.
WRITE_DAC	Можно записать список управления доступом на уровне пользователей (DACL), связанный с именованным каналом.
WRITE_OWNER	Можно записать сведения о владельце, связанные с именованным каналом.
ACCESS_SYSTEM_SECURITY	Вызывающий объект будет иметь доступ на запись в SACL именованного канала.
SYNCHRONIZE	Вызывающий объект может синхронизировать завершение операции ввода-вывода, ожидая, пока возвращенное значение FileHandle будет установлено в состояние Signaled. Этот флаг необходимо задать, если установлен флаг CreateOptions FILE_SYNCHRONOUS_IO_ALERT или FILE_SYNCHRONOUS_IO_NONALERT.

 

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

DesiredAccess к значениям файлов	Сопоставляется с флагами DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA и SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA и SYNCHRONIZE.

[in] ObjectAttributes

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

Член	Значение
Длина ULONG	Количество байтов данных, содержащихся в структуре, на которую указывает ObjectAttributes. Это значение должно быть по крайней мере sizeof(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 , список управления доступом, размещенный в канале, зависит от файловой системы именованного канала и может разрешить клиенту с любым доступом создать экземпляр.
Атрибуты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	Системные службы, системы каналов и драйверы, которые записывают данные в канал, должны фактически передавать данные в канал, прежде чем любая запрошенная операция записи будет считаться завершенной. Этот флаг устанавливается автоматически, если установлен флаг CreateOptions FILE_NO_INTERMEDIATE_BUFFERING.
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	Фильтр или экземпляр, указанный в параметрах Фильтра или Экземпляра , будет снесен. Этот код состояния можно получить, если открытый запрос пересекает точку подключения тома, а параметр Instance имеет значение, отличное от 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 с помощью процедуры FltAllocateExtraCreateParameterList . Если используются ECP, их необходимо выделить, инициализировать и освободить с помощью связанных процедур поддержки. После возвращения из вызова FltCreateNamedPipeFile список ECP не изменяется и может передаваться в дополнительные вызовы FltCreateNamedPipeFile для других операций создания. Структура списка ECP не освобождается автоматически. Вызывающий объект FltCreateNamedPipeFile должен освободить эту структуру, вызвав подпрограмму FltFreeExtraCreateParameterList .

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

Требования

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

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

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext