FltSendMessage function (fltkernel.h)

FltSendMessage sends a message to a waiting user-mode application on behalf of a minifilter driver or a minifilter driver instance.

Syntax

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
);

Parameters

[in] Filter

Opaque filter pointer for the caller. This parameter is required and cannot be NULL.

[in] ClientPort

Pointer to a variable that contains the opaque client port pointer for the connection port between the user-mode application and the kernel-mode minifilter driver. For more information about the client port pointer, see the description of the ConnectNotifyCallback parameter in the reference entry for FltCreateCommunicationPort.

[in] SenderBuffer

Pointer to a caller-allocated buffer containing the message to be sent to the user-mode application. This parameter is required and cannot be NULL.

[in] SenderBufferLength

Size, in bytes, of the buffer that SenderBuffer points to. See Remarks for more information.

[out, optional] ReplyBuffer

Pointer to a caller-allocated buffer that receives the reply, if any, from the application. This parameter is optional and can be NULL.

[in, out] ReplyLength

Size, in bytes, of the buffer that ReplyBuffer points to. This parameter is optional, but must be non-NULL when ReplyBuffer is not NULL.

[in, optional] Timeout

A pointer to a timeout value that specifies the total absolute or relative length of time, in units of 100 nanoseconds, for which the caller can be put into a wait state until the message is received by the user-mode application and until it receives a reply (if one is expected).

A positive value specifies an absolute time, relative to January 1, 1601. A negative value specifies an interval relative to the current time. Set to NULL if the caller can be put into a wait state indefinitely.

Return value

FltSendMessage returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return code Description
STATUS_INSUFFICIENT_RESOURCES FltSendMessage encountered a pool allocation failure. This is an error code.
STATUS_PORT_DISCONNECTED The communication port has been disconnected. This is an error code.
STATUS_THREAD_IS_TERMINATING The wait was interrupted because the thread has been terminated by an application or user.
STATUS_TIMEOUT The Timeout interval expired before the message could be delivered or before a reply was received. This is a success code.

Remarks

FltSendMessage sends a message to a user-mode application on behalf of a minifilter driver or a minifilter driver instance.

If the application calls FilterGetMessage to get the message before the minifilter driver calls FltSendMessage to send it, the message is delivered immediately. This is typically the case when the application calls FilterGetMessage from inside a message loop.

Otherwise, if an application has not called to get a message, the minifilter driver is put into a wait state as follows:

  • If Timeout is nonzero and the application calls FilterGetMessage before the Timeout interval expires, the message is delivered.

  • If Timeout is nonzero and the application doesn't call FilterGetMessage before the Timeout interval expires, the message is not delivered, and FltSendMessage returns STATUS_TIMEOUT. (Note: STATUS_TIMEOUT is a success code.)

  • If Timeout is zero, the minifilter driver is put into a wait state indefinitely. When the application calls FilterGetMessage, the message is delivered.

After the message is delivered, if ReplyBuffer is NULL, FltSendMessage returns STATUS_SUCCESS.

Otherwise, if ReplyBuffer is not NULL, the minifilter driver is put into a wait state as follows:

  • If Timeout is nonzero and the application calls FilterReplyMessage before the Timeout interval expires, the minifilter driver receives the reply, and FltSendMessage returns STATUS_SUCCESS.

  • If Timeout is nonzero and the minifilter driver does not receive a reply before the Timeout interval expires, FltSendMessage returns STATUS_TIMEOUT. (Note: STATUS_TIMEOUT is a success code.)

  • If Timeout is zero when the minifilter driver is waiting for the reply, the minifilter driver is put into a wait state indefinitely. When the application calls FilterReplyMessage, the minifilter driver receives the reply, and FltSendMessage returns STATUS_SUCCESS.

Note

 Due to (system-specific) structure padding requirements, accuracy is required when you set the size of buffers that are associated with FltSendMessage and FilterReplyMessage. As an example, assume data must be sent via FilterReplyMessage to a minifilter. The user-mode component might declare the following structure to do so:

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

Given this structure, it might seem obvious that the caller of FilterReplyMessage would set dwReplyBufferSize to sizeof(REPLY_STRUCT), and set the ReplyLength parameter of FltSendMessage to the same value. However, because of structure padding idiosyncrasies, sizeof(REPLY_STRUCT) might be larger than sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). If this is the case, FltSendMessage returns STATUS_BUFFER_OVERFLOW.

Therefore, it is recommended that you call FilterReplyMessage and FltSendMessage (leveraging the above example) by setting dwReplyBufferSize and ReplyLength both to sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) instead of sizeof(REPLY_STRUCT). This ensures that any extra padding at the end of the REPLY_STRUCT structure is ignored.

Requirements

Requirement Value
Minimum supported client Microsoft Windows 2000 Update Rollup 1 for SP4, Windows XP SP2, Windows Server 2003 SP1, and later operating systems.
Target Platform Universal
Header fltkernel.h (include FltKernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

See also

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort