Funzione FltSendMessage (fltkernel.h)
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 |