Share via

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

  • Статья

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

Синтаксис

NTSTATUS FLTAPI FltCreateMailslotFile(
  [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                     CreateOptions,
  [in]            ULONG                     MailslotQuota,
  [in]            ULONG                     MaximumMessageSize,
  [in]            PLARGE_INTEGER            ReadTimeout,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Параметры

[in] Filter

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

[in, optional] Instance

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

[out] FileHandle

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

[out, optional] FileObject

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

[in] DesiredAccess

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

Флаг DesiredAccess Значение
FILE_READ_DATA Данные можно считывать из именованного почтового объекта.
FILE_READ_ATTRIBUTES Флаги FileAttributes можно считать. Дополнительные сведения см. в таблице допустимых значений флагов в параметре FileAttributesобъекта FltCreateFileEx2.
READ_CONTROL Список управления доступом список управления доступом и сведения о владельце, связанные с mailslot, можно считать.
FILE_WRITE_DATA Данные могут быть записаны в почтовый слой.
FILE_WRITE_ATTRIBUTES Можно записывать флаги FileAttributes.
FILE_APPEND_DATA К почтовому слою можно добавить данные.
WRITE_DAC Можно написать список управления доступом на уровне пользователей , связанный с почтовым слоем.
WRITE_OWNER Можно записать сведения о владельцах, связанных с почтовым слоем.
ACCESS_SYSTEM_SECURITY Вызывающий объект будет иметь доступ на запись к SACL почтового объекта mailslot.
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\Mailslot\myslot" или "?? \mailslot\myslot" может быть допустимыми спецификациями файлов. (Примечание. "??" заменяет "\DosDevices" в качестве имени пространства имен объекта Win32. "\DosDevices" по-прежнему работает, но "??" преобразуется быстрее диспетчером объектов.
HANDLE RootDirectory Необязательный дескриптор для каталога, полученный при предыдущем вызове FltCreateFileEx2. Если это значение равно NULL, элемент ObjectName должен быть полной спецификацией файла, которая включает полный путь к целевому почтовому слою. Если это значение не равно NULL, элемент ObjectName указывает имя почтового объекта относительно этого каталога.
PSECURITY_DESCRIPTOR SecurityDescriptor Необязательный SECURITY_DESCRIPTOR , применяемый к почтовому слою. Списки управления доступом , заданные таким дескриптором безопасности, применяются только к созданному почтовому слою. Если при создании mailslot значение равно NULL , список управления доступом, размещенный в mailslot, зависит от файловой системы mailslot и может разрешить клиенту с любым доступом создать экземпляр.
Атрибуты ULONG Набор флагов, управляющий атрибутами объекта файла. Если вызывающий объект выполняется в контексте системного процесса, этот параметр может быть равен нулю. В противном случае вызывающий объект должен установить флаг OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имени должен игнорировать регистр ObjectName , а не выполнять поиск точного соответствия.

[out] IoStatusBlock

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

  • FILE_CREATED
  • FILE_OPENED

[in] CreateOptions

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

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

[in] MailslotQuota

Размер (в байтах) буфера для операций записи в mailslot.

[in] MaximumMessageSize

Максимальный размер (в байтах) сообщения для записи в почтовый объект. Сообщение любого размера указывается значением 0.

[in] ReadTimeout

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

Значение Значение
0 Возвращает немедленно, если сообщение отсутствует.
-1 Вечное ожидание сообщения.

[in, optional] DriverContext

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

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

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

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

Комментарии

Функция FltCreateMailslotFile позволяет драйверам минифильтра создавать или открывать экземпляры mailslot. Это полезно для создания виртуальных почтовых слоотов или для создания группы mailslots, которая распространяется на несколько других почтовых слоотов.

Параметр Instance имеет значение NULL или задается ранее путем вложения в том почтового объекта. Указатель тома получается путем передачи "\Device\Mailslot" в качестве имени тома в FltGetVolumeFromName.

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

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

Требования

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

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

FltAllocateExtraCreateParameterList

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext