FilterReplyMessage function (fltuser.h)

Article
02/22/2024

The FilterReplyMessage function replies to a message from a kernel-mode minifilter.

Syntax

HRESULT FilterReplyMessage(
  [in] HANDLE               hPort,
  [in] PFILTER_REPLY_HEADER lpReplyBuffer,
  [in] DWORD                dwReplyBufferSize
);

Parameters

[in] hPort

Communication port handle returned by a previous call to FilterConnectCommunicationPort. This parameter is required and cannot be NULL.

[in] lpReplyBuffer

A pointer to a caller-allocated buffer containing the reply to be sent to the minifilter. The reply must contain a FILTER_REPLY_HEADER structure, but otherwise, its format is caller-defined. This parameter is required and cannot be NULL.

[in] dwReplyBufferSize

Size, in bytes, of the buffer that the lpReplyBuffer parameter points to. See the Remarks section.

Return value

FilterReplyMessage returns S_OK if successful. Otherwise, it returns an error value.

Remarks

A user-mode application calls the FilterReplyMessage function to reply to a message received from a kernel-mode minifilter.

To get a message from a minifilter, call FilterGetMessage.

To send a message to a minifilter, call FilterSendMessage.

A minifilter sends a message to a user-mode application by calling FltSendMessage.

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

Requirement	Value
Minimum supported client	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.
Target Platform	Universal
Header	fltuser.h (include FltUser.h)
Library	FltLib.lib
DLL	FltLib.dll