Função FltSendMessage (fltkernel.h)

FltSendMessage envia uma mensagem para um aplicativo de modo de usuário em espera em nome de um driver de minifiltro ou uma instância de driver de minifiltro.

Sintaxe

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

Parâmetros

[in] Filter

Ponteiro de filtro opaco para o chamador. Esse parâmetro é necessário e não pode ser NULL.

[in] ClientPort

Ponteiro para uma variável que contém o ponteiro de porta do cliente opaco para a porta de conexão entre o aplicativo do modo de usuário e o driver de minifiltro no modo kernel. Para obter mais informações sobre o ponteiro da porta do cliente, consulte a descrição do parâmetro ConnectNotifyCallback na entrada de referência de FltCreateCommunicationPort.

[in] SenderBuffer

Ponteiro para um buffer alocado pelo chamador que contém a mensagem a ser enviada para o aplicativo de modo de usuário. Esse parâmetro é necessário e não pode ser NULL.

[in] SenderBufferLength

Tamanho, em bytes, do buffer para o qual SenderBuffer aponta. Confira Comentários para obter mais informações.

[out, optional] ReplyBuffer

Ponteiro para um buffer alocado pelo chamador que recebe a resposta, se houver, do aplicativo. Esse parâmetro é opcional e pode ser NULL.

[in, out] ReplyLength

Tamanho, em bytes, do buffer para o qual ReplyBuffer aponta. Esse parâmetro é opcional, mas deve ser não NULL quando ReplyBuffer não for NULL.

[in, optional] Timeout

Um ponteiro para um valor de tempo limite que especifica o tempo total absoluto ou relativo, em unidades de 100 nanossegundos, para o qual o chamador pode ser colocado em um estado de espera até que a mensagem seja recebida pelo aplicativo de modo de usuário e até receber uma resposta (se for esperado).

Um valor positivo especifica uma hora absoluta em relação a 1º de janeiro de 1601. Um valor negativo especifica um intervalo relativo à hora atual. Defina como NULL se o chamador puder ser colocado em um estado de espera indefinidamente.

Retornar valor

FltSendMessage retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	FltSendMessage encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_PORT_DISCONNECTED	A porta de comunicação foi desconectada. Este é um código de erro.
STATUS_THREAD_IS_TERMINATING	A espera foi interrompida porque o thread foi encerrado por um aplicativo ou usuário.
STATUS_TIMEOUT	O intervalo de tempo limite expirou antes que a mensagem pudesse ser entregue ou antes de uma resposta ser recebida. Esse é um código de êxito.

Comentários

FltSendMessage envia uma mensagem para um aplicativo de modo de usuário em nome de um driver de minifiltro ou de uma instância de driver de minifiltro.

Se o aplicativo chamar FilterGetMessage para obter a mensagem antes que o driver de minifiltro chame FltSendMessage para enviá-la, a mensagem será entregue imediatamente. Normalmente, esse é o caso quando o aplicativo chama FilterGetMessage de dentro de um loop de mensagem.

Caso contrário, se um aplicativo não tiver chamado para receber uma mensagem, o driver de minifiltro será colocado em um estado de espera da seguinte maneira:

• Se Timeout não for zero e o aplicativo chamar FilterGetMessage antes do intervalo de tempo limite expirar, a mensagem será entregue.

• Se Timeout não for zero e o aplicativo não chamar FilterGetMessage antes do intervalo de tempo limite expirar, a mensagem não será entregue e FltSendMessage retornará STATUS_TIMEOUT. (Observação: STATUS_TIMEOUT é um código de êxito.)

• Se Timeout for zero, o driver de minifiltro será colocado em um estado de espera indefinidamente. Quando o aplicativo chama FilterGetMessage, a mensagem é entregue.

Depois que a mensagem for entregue, se ReplyBuffer for NULL, FltSendMessage retornará STATUS_SUCCESS.

Caso contrário, se ReplyBuffer não for NULL, o driver de minifiltro será colocado em um estado de espera da seguinte maneira:

• Se Timeout não for zero e o aplicativo chamar FilterReplyMessage antes do intervalo de tempo limite expirar, o driver de minifiltro receberá a resposta e FltSendMessage retornará STATUS_SUCCESS.

• Se Timeout não for zero e o driver de minifiltro não receber uma resposta antes do intervalo de tempo limite expirar, FltSendMessage retornará STATUS_TIMEOUT. (Observação: STATUS_TIMEOUT é um código de êxito.)

• Se Timeout for zero quando o driver de minifiltro estiver aguardando a resposta, o driver de minifiltro será colocado em um estado de espera indefinidamente. Quando o aplicativo chama FilterReplyMessage, o driver de minifiltro recebe a resposta e FltSendMessage retorna STATUS_SUCCESS.

Observação

 Devido aos requisitos de preenchimento de estrutura (específicos do sistema), a precisão é necessária quando você define o tamanho dos buffers associados a FltSendMessage e FilterReplyMessage. Por exemplo, suponha que os dados devem ser enviados por meio de FilterReplyMessage para um minifiltro. O componente do modo de usuário pode declarar a seguinte estrutura para fazer isso:

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

Dada essa estrutura, pode parecer óbvio que o chamador de FilterReplyMessage definiria dwReplyBufferSize como sizeof(REPLY_STRUCT)e definiria o parâmetro ReplyLength de FltSendMessage como o mesmo valor. No entanto, devido a idiossincrasias de preenchimento de estrutura, sizeof(REPLY_STRUCT) pode ser maior que sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). Se esse for o caso, FltSendMessage retornará STATUS_BUFFER_OVERFLOW.

Portanto, é recomendável que você chame FilterReplyMessage e FltSendMessage (aproveitando o exemplo acima) definindo dwReplyBufferSize e ReplyLength como sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) em vez de sizeof(REPLY_STRUCT). Isso garante que qualquer preenchimento extra no final da estrutura REPLY_STRUCT seja ignorado.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Pacote cumulativo de atualizações do Microsoft Windows 2000 1 para SP4, Windows XP SP2, Windows Server 2003 SP1 e sistemas operacionais posteriores.
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua FltKernel.h)
Biblioteca	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL

Confira também

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort