FltSendMessage-Funktion (fltkernel.h)

FltSendMessage eine Nachricht an eine wartende Benutzermodusanwendung im Auftrag eines Minifiltertreibers oder einer Minifiltertreiberinstanz sendet.

Syntax

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

Parameter

[in] Filter

Undurchsichtiger Filterzeiger für den Aufrufer. Dieser Parameter ist erforderlich und kann nicht NULL sein.

[in] ClientPort

Zeiger auf eine Variable, die den undurchsichtigen Clientportzeiger für den Verbindungsport zwischen der Benutzermodusanwendung und dem Kernelmodus-Minifiltertreiber enthält. Weitere Informationen zum Clientportzeiger finden Sie in der Beschreibung des Parameters ConnectNotifyCallback im Referenzeintrag für FltCreateCommunicationPort.

[in] SenderBuffer

Zeiger auf einen vom Minifilter zugeordneten Puffer, der die Nachricht enthält, die an die Anwendung im Benutzermodus gesendet werden soll. Dieser Parameter ist erforderlich und kann nicht NULL sein.

[in] SenderBufferLength

Größe des Puffers in Bytes, auf den SenderBuffer verweist. Weitere Informationen finden Sie in Anmerkungen.

[out, optional] ReplyBuffer

Zeiger auf einen von einem Miniport zugeordneten Puffer, der ggf. eine Antwort von der Anwendung empfängt. Dieser Parameter ist optional und kann NULL sein.

[in, out] ReplyLength

Größe des Puffers, auf den "ReplyBuffer" in Bytes verweist. Dieser Parameter ist optional, muss aber nicht NULL sein, wenn ReplyBuffer nicht NULL ist.

[in, optional] Timeout

Ein Zeiger auf einen Timeoutwert, der die gesamte absolute oder relative Zeitdauer in Einheiten von 100 Nanosekunden angibt, für die der Aufrufer (Miniport) in einen Wartezustand versetzt werden kann, bis die Nachricht von der Anwendung im Benutzermodus empfangen wird und bis eine Antwort empfangen wird, wenn eine Antwort erwartet wird.

Ein positiver Wert gibt eine absolute Zeit im Verhältnis zum 1. Januar 1601 an. Ein negativer Wert gibt ein Intervall relativ zur aktuellen Uhrzeit an. Legen Sie Timeout auf NULL fest, wenn der Aufrufer auf unbestimmte Zeit in einen Wartezustand versetzt werden kann.

Rückgabewert

FltSendMessage gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden:

Bemerkungen

FltSendMessage sendet eine Nachricht im Auftrag eines Minifiltertreibers oder einer Minifiltertreiberinstanz an eine Benutzermodusanwendung.

Wenn die Anwendung FilterGetMessage aufruft, um die Nachricht abzurufen, bevor der Minifiltertreiber FltSendMessage aufruft, um sie zu senden, wird die Nachricht, auf die SendBuffer zeigt, sofort übermittelt, wenn FltSendMessage aufgerufen wird. Dies ist in der Regel der Fall, wenn die Anwendung FilterGetMessage- aus einer Nachrichtenschleife aufruft.

Wenn eine Anwendung nicht aufgerufen hat, um eine Nachricht abzurufen, versetzt FltMgr den Minifilter wie folgt in einen Wartezustand:

• Wenn Timeout auf einen Wert ungleich Null verweist und die Anwendung FilterGetMessage aufruft, bevor das Timeout-Intervall abläuft, wird die Nachricht übermittelt.

• Wenn Timeout auf einen Wert ungleich Null verweist und die Anwendung FilterGetMessage nicht vor Ablauf des Timeout-Intervalls aufruft, wird die Nachricht nicht übermittelt, und FltSendMessage gibt STATUS_TIMEOUT als Erfolgscode zurück.

• Wenn Timeout auf null (*Timeout == 0) zeigt, wird FltSendMessage ohne Wartezeit zurückgegeben.

• Wenn Timeout NULL (Timeout == NULL) ist, wird der Minifilter auf unbestimmte Zeit in einen Wartezustand versetzt. Wenn die Anwendung FilterGetMessage-aufruft, wird die Nachricht zugestellt.

Wenn ReplyBuffer nach dem Übermitteln der Nachricht NULL ist, gibt FltSendMessage STATUS_SUCCESS zurück.

Andernfalls wird der Minifilter wie folgt in einen Wartezustand versetzt, wenn ReplyBuffer nicht NULL ist:

• Wenn Timeout ungleich Null ist und die Anwendung FilterReplyMessage aufruft, bevor das Timeout-Intervall abläuft, empfängt der Minifilter die Antwort, und FltSendMessage gibt STATUS_SUCCESS zurück.

• Wenn Timeout ungleich Null ist und der Minifilter vor Ablauf des Timeout-Intervalls keine Antwort erhält, gibt FltSendMessage STATUS_TIMEOUT als Erfolgscode zurück.

• Wenn Timeout auf null (*Timeout == 0) zeigt, wird FltSendMessage ohne Wartezeit zurückgegeben.

• Wenn Timeout null ist, während der Minifilter auf die Antwort wartet, wird der Minifilter auf unbestimmte Zeit in einen Wartezustand versetzt. Wenn die Anwendung FilterReplyMessage aufruft, empfängt der Minifilter die Antwort, und FltSendMessage gibt STATUS_SUCCESS zurück.

Abstand und Puffergröße

Probleme können auftreten, wenn der Aufrufer den systemspezifischen Strukturabstand nicht ordnungsgemäß berücksichtigt, der auftreten kann.

Angenommen, ein Minifilter deklariert die folgende Struktur, in der eine Antwort empfangen werden soll, und übergibt einen Zeiger darauf in 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 muss mit ausreichend Platz zugewiesen werden, um die gesamte Struktur einschließlich des Abstands zu halten. Daher sollte ReplyLength auf sizeof(REPLY_STRUCT), nicht sizeof(FILTER_REPLY_HEADER) + sizeof(REPLY_DATA)auf .

Wenn "ReplyLengthsizeof(FILTER_REPLY_HEADER) + sizeof(REPLY_DATA)" auf "Padding" festgelegt wird, werden die Elemente "Header" und "Data" möglicherweise nicht berücksichtigt. Dies kann dazu führen, dass FltSendMessage STATUS_BUFFER_OVERFLOW zurückgibt, auch wenn der Puffer groß genug ist, um beide Strukturen zu halten.

Nachdem FltSendMessage erfolgreich zurückgegeben wurde, verwenden Sie die Verwendung offsetof(REPLY_STRUCT, Data) , um den Anfang der Datenstruktur innerhalb von ReplyBuffer zu finden, und überprüfen Sie den ReplyLength-Ausgabewert , um die tatsächliche Anzahl von Bytes zu ermitteln, die von der Benutzermodusanwendung geschrieben wurden.

Anforderungen

Siehe auch

FilterGetMessage-

FilterReplyMessage-

FilterSendMessage-

FltCreateCommunicationPort