Função FilterGetMessage (fltuser.h)

Artigo
08/23/2023

A função FilterGetMessage obtém uma mensagem de um minifiltro no modo kernel.

Sintaxe

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

Parâmetros

[in] hPort

Identificador de porta de comunicação retornado por uma chamada anterior para FilterConnectCommunicationPort. Esse parâmetro é necessário e não pode ser NULL.

[out] lpMessageBuffer

Ponteiro para um buffer alocado pelo chamador que recebe a mensagem do minifiltro. A mensagem deve conter uma estrutura FILTER_MESSAGE_HEADER , mas caso contrário, seu formato é definido pelo chamador. Esse parâmetro é necessário e não pode ser NULL.

[in] dwMessageBufferSize

Tamanho, em bytes, do buffer para o qual o parâmetro lpMessageBuffer aponta.

[in, out] lpOverlapped

Ponteiro para uma estrutura OVERLAPPED. Esse parâmetro é opcional e pode ser NULL. Se não for NULL, o chamador deverá inicializar o membro hEvent da estrutura OVERLAPPED para um identificador de evento válido ou NULL.

Valor retornado

FilterGetMessage retornará S_OK se tiver êxito. Caso contrário, ele retornará um valor de erro.

Comentários

A função FilterGetMessage foi projetada para a operação síncrona e assíncrona (sobreposta).

Quando lpOverlapped é NULL e uma mensagem está disponível, FilterGetMessage retorna imediatamente. Caso contrário, o chamador será colocado em um estado de espera até que uma mensagem seja recebida.

Se lpOverlapped não for NULL, FilterGetMessage retornará ERROR_IO_PENDING. Nessa situação, o objeto de evento na estrutura lpOverlapped é definido como o estado não atribuído antes de FilterGetMessage retornar. Quando a mensagem é entregue, esse evento é definido como o estado sinalizado.

Depois de receber a mensagem do minifiltro, o chamador pode enviar uma resposta chamando FilterReplyMessage.

Um minifiltro ou instância envia uma mensagem para um aplicativo de modo de usuário chamando FltSendMessage.