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

Статья
02/29/2024

FltSendMessage отправляет сообщение в ожидающее приложение в пользовательском режиме от имени драйвера мини-фильтра или экземпляра драйвера минифильтра.

Синтаксис

NTSTATUS FLTAPI FltSendMessage(
  [in]            PFLT_FILTER    Filter,
  [in]            PFLT_PORT      *ClientPort,
  [in]            PVOID          SenderBuffer,
  [in]            ULONG          SenderBufferLength,
  [out, optional] PVOID          ReplyBuffer,
  [in, out]       PULONG         ReplyLength,
  [in, optional]  PLARGE_INTEGER Timeout
);

Параметры

[in] Filter

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

[in] ClientPort

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

[in] SenderBuffer

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

[in] SenderBufferLength

Размер (в байтах) буфера, на который указывает SenderBuffer . Дополнительные сведения см. в примечаниях.

[out, optional] ReplyBuffer

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

[in, out] ReplyLength

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

[in, optional] Timeout

Указатель на значение времени ожидания, указывающее общую абсолютную или относительную продолжительность времени в единицах в 100 наносекунд, для которых вызывающий объект может быть переведен в состояние ожидания, пока сообщение не будет получено приложением пользовательского режима и пока он не получит ответ (если он ожидается).

Положительное значение указывает абсолютное время относительно 1 января 1601 года. Отрицательное значение указывает интервал относительно текущего времени. Установите значение NULL , если вызывающий объект может быть переведен в состояние ожидания на неопределенный срок.

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

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

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	В FltSendMessage произошла ошибка выделения пула. Это код ошибки.
STATUS_PORT_DISCONNECTED	Порт связи отключен. Это код ошибки.
STATUS_THREAD_IS_TERMINATING	Ожидание было прервано, так как поток был прерван приложением или пользователем.
STATUS_TIMEOUT	Интервал времени ожидания истек до доставки сообщения или до получения ответа. Это код успешного выполнения.

Если приложение вызывает FilterGetMessage , чтобы получить сообщение до того, как драйвер мини-фильтра вызовет FltSendMessage для его отправки , сообщение доставляется немедленно. Обычно это происходит, когда приложение вызывает FilterGetMessage из цикла сообщений.

В противном случае, если приложение не вызывало для получения сообщения, драйвер мини-фильтра переводится в состояние ожидания следующим образом:

Если время ожидания не равно нулю и приложение вызывает FilterGetMessage до истечения интервала ожидания , сообщение доставляется.
Если время ожидания не равно нулю и приложение не вызывает FilterGetMessage до истечения интервала времени ожидания , сообщение не доставляется, и FltSendMessage возвращает STATUS_TIMEOUT. (Примечание. STATUS_TIMEOUT — это успешный код.)
Если время ожидания равно нулю, драйвер минифильтра переводится в состояние ожидания на неопределенный срок. Когда приложение вызывает FilterGetMessage, сообщение доставляется.

Если после доставки сообщения ReplyBuffer имеет значение NULL, FltSendMessage возвращает STATUS_SUCCESS.

В противном случае, если replyBuffer не равно NULL, драйвер минифильтра переводится в состояние ожидания следующим образом:

Если время ожидания не равно нулю и приложение вызывает FilterReplyMessage до истечения интервала ожидания , драйвер мини-фильтра получает ответ, а FltSendMessage возвращает STATUS_SUCCESS.
Если время ожидания не равно нулю и драйвер минифильтра не получает ответ до истечения интервала ожидания , FltSendMessage возвращает STATUS_TIMEOUT. (Примечание. STATUS_TIMEOUT — это успешный код.)
Если время ожидания равно нулю, когда драйвер минифильтра ожидает ответа, драйвер минифильтра переводится в состояние ожидания на неопределенный срок. Когда приложение вызывает FilterReplyMessage, драйвер минифильтра получает ответ, а FltSendMessage возвращает STATUS_SUCCESS.

Примечание

Из-за требований к заполнению структуры (для конкретной системы) точность требуется при установке размера буферов, связанных с FltSendMessage и FilterReplyMessage. Например, предположим, что данные должны отправляться через FilterReplyMessage в мини-фильтр. Для этого компонент пользовательского режима может объявить следующую структуру:

typedef struct _REPLY_STRUCT
{
    FILTER_REPLY_HEADER Header;
    MY_STRUCT Data;  // The structure to be sent to the minifilter
} REPLY_STRUCT, *PREPLY_STRUCT;

Учитывая эту структуру, может показаться очевидным, что вызывающий объект FilterReplyMessage присваивает dwReplyBufferSize значение sizeof(REPLY_STRUCT), а параметру ReplyLengthобъекта FltSendMessage присваивается то же значение. Однако из-за особенности sizeof(REPLY_STRUCT) заполнения структуры может быть больше , чем sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). В этом случае Функция FltSendMessage возвращает STATUS_BUFFER_OVERFLOW.

Поэтому рекомендуется вызывать FilterReplyMessage и FltSendMessage (используя приведенный выше пример), задав для dwReplyBufferSizesizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) и ReplyLength значение вместо sizeof(REPLY_STRUCT). Это гарантирует, что любое дополнительное заполнение в конце структуры REPLY_STRUCT игнорируется.

Требования

Требование	Значение
Минимальная версия клиента	Пакет обновления 1 для Microsoft Windows 2000 с пакетом обновления 1 (SP4), Windows XP с пакетом обновления 2 (SP2), Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних версий операционных систем.
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая FltKernel.h)
Библиотека	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL

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

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort

Share via