FilterGetMessage function (fltuser.h)

Article
02/22/2024

The FilterGetMessage function gets a message from a kernel-mode minifilter.

Syntax

HRESULT FilterGetMessage(
  [in]      HANDLE                 hPort,
  [out]     PFILTER_MESSAGE_HEADER lpMessageBuffer,
  [in]      DWORD                  dwMessageBufferSize,
  [in, out] LPOVERLAPPED           lpOverlapped
);

Parameters

[in] hPort

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

[out] lpMessageBuffer

Pointer to a caller-allocated buffer that receives the message from the minifilter. The message must contain a FILTER_MESSAGE_HEADER structure, but otherwise its format is caller-defined. This parameter is required and cannot be NULL.

[in] dwMessageBufferSize

Size, in bytes, of the buffer that the lpMessageBuffer parameter points to.

[in, out] lpOverlapped

Pointer to an OVERLAPPED structure. This parameter is optional and can be NULL. If it is not NULL, the caller must initialize the hEvent member of the OVERLAPPED structure to a valid event handle or NULL.

Return value

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

Remarks

The FilterGetMessage function is designed for both synchronous and asynchronous (overlapped) operation.

When lpOverlapped is NULL, and a message is available, FilterGetMessage returns immediately. Otherwise, the caller is put into a wait state until a message is received.

If lpOverlapped is not NULL, FilterGetMessage returns ERROR_IO_PENDING. In this situation, the event object in the lpOverlapped structure is set to the nonsignaled state before FilterGetMessage returns. When the message is delivered, this event is set to the signaled state.

After receiving the message from the minifilter, the caller can send a reply by calling FilterReplyMessage.

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

Requirements

Requirement	Value
Target Platform	Universal
Header	fltuser.h (include Fltuser.h)
Library	FltLib.lib
DLL	FltLib.dll