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

Статья
08/07/2023

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

Синтаксис

NTSTATUS FLTAPI FltCreateCommunicationPort(
  [in]           PFLT_FILTER            Filter,
  [out]          PFLT_PORT              *ServerPort,
  [in]           POBJECT_ATTRIBUTES     ObjectAttributes,
  [in, optional] PVOID                  ServerPortCookie,
  [in]           PFLT_CONNECT_NOTIFY    ConnectNotifyCallback,
  [in]           PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
  [in, optional] PFLT_MESSAGE_NOTIFY    MessageNotifyCallback,
  [in]           LONG                   MaxConnections
);

Параметры

[in] Filter

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

[out] ServerPort

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

[in] ObjectAttributes

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

Член	Значение
Длина ULONG	InitializeObjectAttributes задает для этого элемента значение sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Указатель на структуру UNICODE_STRING , содержащую уникальное имя (например, L"\\MyFilterPort") для объекта port.
PSECURITY_DESCRIPTOR SecurityDescriptor	Указатель на дескриптор безопасности (SECURITY_DESCRIPTOR), применяемый к объекту порта. При необходимости можно создать дескриптор безопасности по умолчанию, вызвав FltBuildDefaultSecurityDescriptor.
АтрибутыULONG	Битовая маска флагов, указывающих нужные атрибуты для дескриптора порта. Эти флаги должны включать OBJ_KERNEL_HANDLE. Вызывающий объект также может при необходимости задать флаг OBJ_CASE_INSENSITIVE, который указывает, что код подстановки имени должен игнорировать регистр ObjectName , а не выполнять поиск точного соответствия.

[in, optional] ServerPortCookie

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

[in] ConnectNotifyCallback

Указатель на подпрограмму обратного вызова, предоставляемую вызывающим абонентом. Диспетчер фильтров вызывает эту подпрограмму всякий раз, когда приложение пользовательского режима вызывает FilterConnectCommunicationPort для отправки запроса на подключение к драйверу минифильтра. Этот параметр является обязательным и не может иметь значение NULL. Эта подпрограмма вызывается по адресу IRQL = PASSIVE_LEVEL.

Эта подпрограмма объявляется следующим образом:

typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
      IN PFLT_PORT ClientPort,
      IN PVOID ServerPortCookie,
      IN PVOID ConnectionContext,
      IN ULONG SizeOfContext,
      OUT PVOID *ConnectionPortCookie
      );

ClientPort

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

Драйвер минифильтра должен передать этот дескриптор в качестве параметра ClientPortв FltSendMessage при отправке сообщений на этом клиентском порту и ответе на их сообщения. (Обратите внимание, что это не то же самое, что дескриптор ServerPort , возвращенный FltCreateCommunicationPort.)

Драйвер минифильтра должен в конечном итоге закрыть этот клиентский порт. Порт клиента закрывается путем вызова FltCloseClientPort, обычно из подпрограммы DisconnectNotifyCallback драйвера минифильтра.

ServerPortCookie

Указатель на контекстные сведения, определенные драйвером минифильтра. Эти сведения можно использовать для различения нескольких портов сервера связи, созданных одним и тем же драйвером минифильтра. При создании порта сервера драйвер минифильтра передал этот указатель контекста в качестве параметра в FltCreateCommunicationPort.

ConnectionContext

Указатель контекстной информации, который приложение пользовательского режима передало в параметре lpContextв FilterConnectCommunicationPort.

SizeOfContext

Размер (в байтах) буфера, на который указывает ConnectionContext .

ConnectionPortCookie

Указатель на сведения, которые однозначно идентифицируют этот порт клиента. Эти сведения определяются драйвером минифильтра. Диспетчер фильтров передает этот указатель контекста в качестве параметра в подпрограммы DisconnectNotifyCallback и MessageNotifyCallback драйвера минифильтра.

[in] DisconnectNotifyCallback

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

Эта подпрограмма объявляется следующим образом:

typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
      IN PVOID ConnectionCookie
      );

ConnectionCookie

Указатель на сведения, которые однозначно идентифицируют этот порт клиента. Эти сведения определяются драйвером минифильтра. При создании порта клиента драйвер минифильтра вернул этот указатель контекста в параметре ConnectionPortCookie своей подпрограммы ConnectNotifyCallback .

[in, optional] MessageNotifyCallback

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

Эта подпрограмма объявляется следующим образом:

typedef NTSTATUS
(*PFLT_MESSAGE_NOTIFY) (
      IN PVOID PortCookie,
      IN PVOID InputBuffer OPTIONAL,
      IN ULONG InputBufferLength,
      OUT PVOID OutputBuffer OPTIONAL,
      IN ULONG OutputBufferLength,
      OUT PULONG ReturnOutputBufferLength
      );

PortCookie

InputBuffer

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

Обратите внимание, что InputBuffer — это указатель на необработанный, разблокированный буфер пользовательского режима. Этот указатель действителен только в контексте процесса пользовательского режима и должен быть доступен только из блока try/except .

Диспетчер фильтров вызывает ProbeForRead для проверки этого указателя, но не гарантирует правильность выравнивания буфера. Если буфер содержит структуры, имеющие требования к выравниванию, драйвер минифильтра отвечает за выполнение всех необходимых проверок выравнивания. Для этого драйвер минифильтра может использовать макрос IS_ALIGNED , как показано в примере драйвера минифильтра MiniSpy.

Этот параметр является необязательным и может иметь значение NULL.

InputBufferLength

Размер (в байтах) буфера, на который указывает InputBuffer . Этот параметр игнорируется, если InputBuffer имеет значение NULL.

OutputBuffer

Указатель на буфер, выделенный вызывающим объектом, который получает ответ (при наличии) от драйвера минифильтра.

Обратите внимание, что OutputBuffer — это указатель на необработанный, разблокированный буфер пользовательского режима. Этот указатель действителен только в контексте процесса пользовательского режима и должен быть доступен только из блока try/except .

Диспетчер фильтров вызывает ProbeForWrite для проверки этого указателя, но не гарантирует правильность выравнивания буфера. Если буфер содержит структуры, имеющие требования к выравниванию, драйвер минифильтра отвечает за выполнение всех необходимых проверок выравнивания. Для этого драйвер минифильтра может использовать макрос IS_ALIGNED , как показано в примере драйвера минифильтра MiniSpy.

Этот параметр является необязательным и может иметь значение NULL.

OutputBufferLength

Размер (в байтах) буфера, на который указывает OutputBuffer . Этот параметр игнорируется, если OutputBuffer имеет значение NULL.

ReturnOutputBufferLength

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

[in] MaxConnections

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

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

Функция FltCreateCommunicationPort возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_FLT_DELETING_OBJECT	Указанный фильтр будет снесен. Это код ошибки.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort столкнулся с ошибкой выделения пула. Это код ошибки.
STATUS_OBJECT_NAME_COLLISION	Порт связи драйвера минифильтра с тем же именем уже существует. Имена портов должны быть уникальными. Это код ошибки.

После создания порта сервера приложение пользовательского режима может подключиться к порту, вызвав FilterConnectCommunicationPort. При подключении приложение пользовательского режима может отправлять и получать сообщения, вызывая функции обмена сообщениями в пользовательском режиме, такие как FilterSendMessage, FilterGetMessage и FilterReplyMessage.

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

Любой порт сервера, созданный командой FltCreateCommunicationPort , в конечном итоге должен быть закрыт путем вызова Метода FltCloseCommunicationPort. При закрытии порта сервера новые подключения к порту сервера не допускаются, и все вызовы FilterConnectCommunicationPort завершаются ошибкой . Однако все существующие подключения остаются открытыми до тех пор, пока они не будут закрыты приложением пользовательского режима или драйвером минифильтра или пока драйвер минифильтра не будет выгружен.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL