通过

fltSendMessage 函数 (fltkernel.h)

  • 项目

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

指向变量的指针，该变量包含用户模式应用程序和内核模式微筛选器驱动程序之间的连接端口的不透明客户端端口指针。 有关客户端端口指针的详细信息，请参阅 FltCreateCommunicationPort 参考条目中的 ConnectNotifyCallback 参数的说明。

[in] SenderBuffer

指向调用方分配的缓冲区的指针，该缓冲区包含要发送到用户模式应用程序的消息。 此参数是必需的，不能为 NULL。

[in] SenderBufferLength

SenderBuffer 指向的缓冲区的大小（以字节为单位）。 有关详细信息，请参阅注解。

[out, optional] ReplyBuffer

指向调用方分配的缓冲区的指针，该缓冲区从应用程序接收回复（如果有）。 此参数是可选的，可以为 NULL。

[in, out] ReplyLength

ReplyBuffer 指向的缓冲区的大小（以字节为单位）。 此参数是可选的，但当 ReplyBuffer 不为 NULL 时，此参数必须为非 NULL。

[in, optional] Timeout

指向超时值的指针，该值指定总绝对时间或相对时间长度（以 100 纳秒为单位），调用方可以将其置于等待状态，直到用户模式应用程序收到消息，直到收到回复 (如果预期) 。

正值指定相对于 1601 年 1 月 1 日绝对时间。 负值指定相对于当前时间的间隔。 如果调用方可以无限期地进入等待状态，则设置为 NULL 。

返回值

FltSendMessage 返回STATUS_SUCCESS或适当的 NTSTATUS 值，例如以下值之一：

返回代码 说明
STATUS_INSUFFICIENT_RESOURCES FltSendMessage 遇到池分配失败。 这是错误代码。
STATUS_PORT_DISCONNECTED 通信端口已断开连接。 这是错误代码。
STATUS_THREAD_IS_TERMINATING 等待已中断，因为线程已被应用程序或用户终止。
STATUS_TIMEOUT 超时间隔在可以传递消息之前或收到回复之前过期。 这是一个成功代码。

注解

FltSendMessage 代表微筛选器驱动程序或微筛选器驱动程序实例将消息发送到用户模式应用程序。

如果应用程序在微筛选器驱动程序调用 FltSendMessage 发送消息之前调用 FilterGetMessage 获取消息，则会立即传递该消息。 当应用程序从消息循环内部调用 FilterGetMessage 时，通常就是这种情况。

否则，如果应用程序尚未调用 来获取消息，则会将微筛选器驱动程序置于等待状态，如下所示：

  • 如果 Timeout 为非零值，并且应用程序在超时间隔到期前调用 FilterGetMessage，则会传递消息。

  • 如果 Timeout 为非零值，并且应用程序在超时间隔到期前未调用 FilterGetMessage，则消息不会传递，FltSendMessage 将返回STATUS_TIMEOUT。 (注意：STATUS_TIMEOUT是成功代码。)

  • 如果 Timeout 为零，则微筛选器驱动程序将无限期地进入等待状态。 当应用程序调用 FilterGetMessage 时，将传递消息。

传递消息后，如果 ReplyBuffer 为 NULL， 则 FltSendMessage 将返回STATUS_SUCCESS。

否则，如果 ReplyBuffer 不为 NULL，则微筛选器驱动程序将进入等待状态，如下所示：

  • 如果 Timeout 为非零值，并且应用程序在超时间隔到期前调用 FilterReplyMessage，则微筛选器驱动程序将收到答复，FltSendMessage 返回STATUS_SUCCESS。

  • 如果 Timeout 为非零值，并且微筛选器驱动程序在 超时 间隔到期前未收到回复， 则 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)，并将 FltSendMessage 的 ReplyLength 参数设置为相同的值。 但是，由于结构填充特性， sizeof(REPLY_STRUCT) 可能大于 sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT)。 如果是这种情况， FltSendMessage 将返回STATUS_BUFFER_OVERFLOW。

因此，建议调用 FilterReplyMessage 和 FltSendMessage (利用上述示例) ，方法是将 dwReplyBufferSize 和 ReplyLength 都设置为 sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) 而不是 sizeof(REPLY_STRUCT)。 这可确保忽略REPLY_STRUCT结构末尾的任何额外填充。

要求

要求 值
最低受支持的客户端 适用于 SP4、Windows XP SP2、Windows Server 2003 SP1 及更高版本的操作系统的 Microsoft Windows 2000 更新汇总 1。
目标平台 通用
标头 fltkernel.h (包括 FltKernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

另请参阅

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort