Funzione FltSendMessage (fltkernel.h)
FltSendMessage invia un messaggio a un'applicazione in modalità utente in attesa per conto di un driver minifiltro o di un'istanza del driver minifiltro.
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 SenderBuffer punta. Per altre informazioni, vedere osservazioni.
[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 punta ReplyBuffer. Questo parametro è facoltativo, ma deve essere diverso daNULL quando ReplyBuffer non è NULL.
[in, optional] Timeout
Puntatore a un valore di timeout che specifica la durata totale assoluta o relativa, in unità di 100 nanosecondi, per cui il chiamante può essere inserito in uno stato di attesa fino a quando il messaggio non viene ricevuto dall'applicazione in modalità utente e fino a quando 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 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. |
Osservazioni
FltSendMessage invia un messaggio a un'applicazione in modalità utente per conto di un driver minifiltro o di un'istanza del driver minifiltro.
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 di operazione riuscita.
Se timeout è zero, il driver del minifiltro 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 minifiltro 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 del minifiltro 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 di operazione riuscita.
Se timeout è zero quando il driver del minifiltro è in attesa della risposta, il driver minifiltro viene inserito in uno stato di attesa illimitato. Quando l'applicazione chiama FilterReplyMessage, il driver minifiltro 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 minifiltro. A tale scopo, il componente in modalità utente potrebbe dichiarare la struttura seguente:
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 impostare dwReplyBufferSize su sizeof(REPLY_STRUCT)e impostare il parametro ReplyLength di FltSendMessage sullo stesso valore. Tuttavia, a causa della spaziatura interna della struttura, sizeof(REPLY_STRUCT) potrebbe essere maggiore 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 sia su sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) anziché su sizeof(REPLY_STRUCT). In questo modo, qualsiasi spaziatura interna aggiuntiva alla fine della struttura REPLY_STRUCT viene ignorata.
Fabbisogno
| 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 |