Expand Minimize

FltSendMessage function

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

Syntax


NTSTATUS FltSendMessage(
  _In_       PFLT_FILTER Filter,
  _In_       PFLT_PORT *ClientPort,
  _In_       PVOID SenderBuffer,
  _In_       ULONG SenderBufferLength,
  _Out_opt_  PVOID ReplyBuffer,
  _Inout_    PULONG ReplyLength,
  _In_opt_   PLARGE_INTEGER Timeout
);

Parameters

Filter [in]

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

ClientPort [in]

A 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.

SenderBuffer [in]

A 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.

SenderBufferLength [in]

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

ReplyBuffer [out, optional]

A pointer to a caller-allocated buffer that receives the reply (if any) from the application. This parameter is optional and can be NULL.

ReplyLength [in, out]

Size, in bytes, of the buffer that ReplyBuffer points to.

Timeout [in, optional]

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). 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 codeDescription
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_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 Timeout is nonzero, the minifilter driver is put into a wait state as follows:

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

  • Otherwise, the message is not delivered, and FltSendMessage returns STATUS_TIMEOUT. (Note: STATUS_TIMEOUT is a success code.)

If Timeout is zero when the message is being sent, 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 Timeout is nonzero, the minifilter driver is put into a wait state as follows:

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

  • Otherwise, the minifilter driver does not receive a reply, and 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.

Important   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_STRUCTURE 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 the dwReplyBufferSize parameter to sizeof(REPLY_STRUCT) and 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, we recommend 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

Version

Available in Microsoft Windows 2000 Update Rollup 1 for SP4, Windows XP SP2, Windows Server 2003 SP1, and later operating systems. Not available in Windows 2000 SP4 and earlier operating systems.

Header

Fltkernel.h (include FltKernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL

See also

FilterGetMessage
FilterSendMessage
FilterReplyMessage
FltCreateCommunicationPort

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft