Функция 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
Тип создаваемого именованного канала. Может иметь одно из следующих значений:
[in] ReadMode
Режим чтения из канала.
[in] CompletionMode
Режим завершения для операций чтения и записи по каналу.
[in] MaximumInstances
Максимальное число экземпляров, разрешенное для этого именованного канала.
InboundQuota
Число байтов, зарезервированных для входного буфера.
OutboundQuota
Число байтов, зарезервированных для выходного буфера.
[in, optional] DefaultTimeout
Время ожидания по умолчанию с шагом в 100 наносекунд. Это значение выражается как отрицательное целое число. Например, 250 миллисекундам указывается как –10 * 1000 * 250.
[in, optional] DriverContext
Необязательный указатель на структуру IO_DRIVER_CREATE_CONTEXT , уже инициализированную IoInitializeDriverCreateContext.
Возвращаемое значение
FltCreateNamedPipeFile возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Фильтр или экземпляр, указанный в параметрах Фильтра или Экземпляра , будет снесен. Этот код состояния можно получить, если открытый запрос пересекает точку подключения тома, а параметр Instance имеет значение, отличное от NULL. Это код ошибки. |
|
Параметр 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