Função FltSendMessage (fltkernel.h)

FltSendMessage envia uma mensagem para um aplicativo em 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 de 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 para FltCreateCommunicationPort.

[in] SenderBuffer

Ponteiro para um buffer alocado por minifiltro que contém a mensagem a ser enviada para o aplicativo no 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 o SenderBuffer aponta. Consulte Comentários para obter mais informações.

[out, optional] ReplyBuffer

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

[in, out] ReplyLength

Tamanho, em bytes, do buffer para o qual o 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 período de tempo absoluto ou relativo total, em unidades de 100 nanossegundos, para o qual o chamador (miniport) pode ser colocado em um estado de espera até que a mensagem seja recebida pelo aplicativo no modo de usuário e até que ele receba uma resposta se uma resposta for esperada.

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

Valor de retorno

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

Observações

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 para a qual SendBuffer aponta será entregue imediatamente quando FltSendMessage for chamado. 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 FltMgr colocará o minifiltro em um estado de espera da seguinte maneira:

• Se Timeout apontar para um valor diferente de zero e o aplicativo chamar FilterGetMessage antes que o intervalo de Timeout expire, a mensagem será entregue.

• Se Timeout apontar para um valor diferente de zero e o aplicativo não chamar FilterGetMessage antes que o intervalo de Timeout expire, a mensagem não será entregue e FltSendMessage retornará STATUS_TIMEOUT como um código de êxito.

• Se Timeout apontar para zero (*Timeout == 0), FltSendMessage retornará sem esperar.

• Se Timeout for NULL (Timeout == NULL), o 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 minifiltro será colocado em um estado de espera da seguinte maneira:

• Se Timeout for diferente de zero e o aplicativo chamar FilterReplyMessage antes que o intervalo de tempo limite expire, o minifiltro receberá a resposta e FltSendMessage retornará STATUS_SUCCESS.

• Se o tempo limite for diferente de zero e o minifiltro não receber uma resposta antes que o intervalo de tempo limite expire, FltSendMessage retornará STATUS_TIMEOUT como um código de êxito.

• Se Timeout apontar para zero (*Timeout == 0), FltSendMessage retornará sem esperar.

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

Preenchimento e tamanho do buffer

Problemas podem ocorrer quando o chamador não conta corretamente para o preenchimento de estrutura específico do sistema que pode ocorrer.

Por exemplo, digamos que um minifiltro declare a seguinte estrutura na qual receber uma resposta e passe um ponteiro para ela em ReplyBuffer:

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

ReplyBuffer deve ser alocado com espaço suficiente para manter toda a estrutura, incluindo qualquer preenchimento. Portanto, ReplyLength deve ser definido como sizeof(REPLY_STRUCT), não sizeof(FILTER_REPLY_HEADER) + sizeof(REPLY_DATA).

A configuração de ReplyLengthsizeof(FILTER_REPLY_HEADER) + sizeof(REPLY_DATA) não conta para o preenchimento que pode ser inserido entre os membros Cabeçalho e Dados . Isso pode levar o FltSendMessage a retornar STATUS_BUFFER_OVERFLOW mesmo quando o buffer for grande o suficiente para manter ambas as estruturas.

Depois que FltSendMessage retornar com êxito , use offsetof(REPLY_STRUCT, Data) para localizar o início da estrutura de dados no ReplyBuffer e examine o valor de saída ReplyLength para determinar o número real de bytes gravados pelo aplicativo de modo de usuário.

Requisitos

Consulte também

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort