Funzione FltSendMessage (fltkernel.h)

  • Articolo

FltSendMessage invia un messaggio a un'applicazione in modalità utente in attesa per conto di un driver minifilter o di un'istanza del driver minifilter.

Sintassi

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

Parametri

[in] Filter

Puntatore di filtro opaco per il chiamante. Questo parametro è obbligatorio e non può essere NULL.

[in] ClientPort

Puntatore a una variabile che contiene il puntatore alla porta client opaca per la porta di connessione tra l'applicazione in modalità utente e il driver minifilter in modalità kernel. Per altre informazioni sul puntatore alla porta client, vedere la descrizione del parametro ConnectNotifyCallback nella voce di riferimento per FltCreateCommunicationPort.

[in] SenderBuffer

Puntatore a un buffer allocato dal chiamante contenente il messaggio da inviare all'applicazione in modalità utente. Questo parametro è obbligatorio e non può essere NULL.

[in] SenderBufferLength

Dimensioni, in byte, del buffer a cui punta SenderBuffer . Vedere osservazioni Per ulteriori informazioni.

[out, optional] ReplyBuffer

Puntatore a un buffer allocato dal chiamante che riceve la risposta, se presente, dall'applicazione. Questo parametro è facoltativo e può essere NULL.

[in, out] ReplyLength

Dimensioni, in byte, del buffer a cui ReplyBuffer punta. Questo parametro è facoltativo, ma deve essere diverso da NULL quando ReplyBuffer non è NULL.

[in, optional] Timeout

Puntatore a un valore di timeout che specifica il tempo totale assoluto o relativo, in unità di 100 nanosecondi, per il quale il chiamante può essere inserito in uno stato di attesa fino a quando il messaggio non viene ricevuto dall'applicazione in modalità utente e finché non riceve una risposta (se previsto).

Un valore positivo specifica un'ora assoluta, rispetto al 1° gennaio 1601. Un valore negativo specifica un intervallo relativo all'ora corrente. Impostare su NULL se il chiamante può essere inserito in uno stato di attesa illimitato.

Valore restituito

FltSendMessage restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito Descrizione
STATUS_INSUFFICIENT_RESOURCES FltSendMessage ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_PORT_DISCONNECTED La porta di comunicazione è stata disconnessa. Si tratta di un codice di errore.
STATUS_THREAD_IS_TERMINATING L'attesa è stata interrotta perché il thread è stato terminato da un'applicazione o da un utente.
STATUS_TIMEOUT Intervallo di timeout scaduto prima del recapito del messaggio o prima della ricezione di una risposta. Si tratta di un codice di operazione riuscita.

Commenti

FltSendMessage invia un messaggio a un'applicazione in modalità utente per conto di un driver minifilter o di un'istanza del driver minifilter.

Se l'applicazione chiama FilterGetMessage per ottenere il messaggio prima che il driver minifilter chiami FltSendMessage per inviarlo, il messaggio viene recapitato immediatamente. Questo è in genere il caso in cui l'applicazione chiama FilterGetMessage dall'interno di un ciclo di messaggi.

In caso contrario, se un'applicazione non ha chiamato per ottenere un messaggio, il driver minifilter viene inserito in uno stato di attesa come indicato di seguito:

  • Se Timeout è diverso da zero e l'applicazione chiama FilterGetMessage prima della scadenza dell'intervallo di timeout , il messaggio viene recapitato.

  • Se Timeout è diverso da zero e l'applicazione non chiama FilterGetMessage prima della scadenza dell'intervallo di timeout , il messaggio non viene recapitato e FltSendMessage restituisce STATUS_TIMEOUT. Nota: STATUS_TIMEOUT è un codice riuscito.

  • Se Timeout è zero, il driver minifilter viene inserito in uno stato di attesa illimitato. Quando l'applicazione chiama FilterGetMessage, il messaggio viene recapitato.

Dopo il recapito del messaggio, se ReplyBuffer è NULL, FltSendMessage restituisce STATUS_SUCCESS.

In caso contrario, se ReplyBuffer non è NULL, il driver minifilter viene inserito in uno stato di attesa come indicato di seguito:

  • Se Timeout è diverso da zero e l'applicazione chiama FilterReplyMessage prima della scadenza dell'intervallo di timeout , il driver minifilter riceve la risposta e FltSendMessage restituisce STATUS_SUCCESS.

  • Se Timeout è diverso da zero e il driver minifilter non riceve una risposta prima della scadenza dell'intervallo di timeout , FltSendMessage restituisce STATUS_TIMEOUT. Nota: STATUS_TIMEOUT è un codice riuscito.

  • Se timeout è zero quando il driver minifilter è in attesa della risposta, il driver minifilter viene inserito in uno stato di attesa illimitato. Quando l'applicazione chiama FilterReplyMessage, il driver minifilter riceve la risposta e FltSendMessage restituisce STATUS_SUCCESS.

Nota

 A causa dei requisiti di riempimento della struttura (specifici del sistema), l'accuratezza è necessaria quando si impostano le dimensioni dei buffer associati a FltSendMessage e FilterReplyMessage. Si supponga, ad esempio, che i dati debbano essere inviati tramite FilterReplyMessage a un minifilter. Il componente in modalità utente potrebbe dichiarare la struttura seguente a tale scopo:

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

Data questa struttura, potrebbe sembrare ovvio che il chiamante di FilterReplyMessage imposta dwReplyBufferSize su sizeof(REPLY_STRUCT)e imposta il parametro ReplyLength di FltSendMessage sullo stesso valore. Tuttavia, a causa della spaziatura interna della struttura, le idioincrone sizeof(REPLY_STRUCT) potrebbero essere maggiori di sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). In questo caso, FltSendMessage restituisce STATUS_BUFFER_OVERFLOW.

È quindi consigliabile chiamare FilterReplyMessage e FltSendMessage (sfruttando l'esempio precedente) impostando dwReplyBufferSize e ReplyLength entrambi su anziché sizeof(REPLY_STRUCT)su sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) . In questo modo si garantisce che qualsiasi spaziatura interna aggiuntiva alla fine della struttura REPLY_STRUCT venga ignorata.

Requisiti

Requisito Valore
Client minimo supportato Microsoft Windows 2000 Update Rollup 1 per SP4, Windows XP SP2, Windows Server 2003 SP1 e sistemi operativi successivi.
Piattaforma di destinazione Universale
Intestazione fltkernel.h (include FltKernel.h)
Libreria FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Vedi anche

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort