FltSendMessage-Funktion (fltkernel.h)
FltSendMessage sendet eine Nachricht im Namen eines Minifiltertreibers oder eines Minifiltertreibers instance an eine wartende Anwendung im Benutzermodus.
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 darf 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 ConnectNotifyCallback-Parameters im Referenzeintrag für FltCreateCommunicationPort.
[in] SenderBuffer
Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Nachricht enthält, die an die Benutzermodusanwendung gesendet werden soll. Dieser Parameter ist erforderlich und darf nicht NULL sein.
[in] SenderBufferLength
Größe des Puffers, auf den SenderBuffer verweist, in Byte. Weitere Informationen finden Sie unter Hinweise .
[out, optional] ReplyBuffer
Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der ggf. die Antwort von der Anwendung empfängt. Dieser Parameter ist optional und kann NULL sein.
[in, out] ReplyLength
Größe des Puffers, auf den ReplyBuffer zeigt, in Bytes. 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 in einen Wartezustand versetzt werden kann, bis die Nachricht von der Benutzermodusanwendung empfangen wird und bis sie eine Antwort erhält (sofern erwartet).
Ein positiver Wert gibt eine absolute Zeit im Verhältnis zum 1. Januar 1601 an. Ein negativer Wert gibt ein Intervall relativ zur aktuellen Zeit an. Legen Sie auf NULL fest, wenn der Aufrufer unbegrenzt in einen Wartezustand versetzt werden kann.
Rückgabewert
FltSendMessage gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Bei FltSendMessage ist ein Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode. |
| STATUS_PORT_DISCONNECTED | Der Kommunikationsport wurde getrennt. Dies ist ein Fehlercode. |
| STATUS_THREAD_IS_TERMINATING | Die Wartezeit wurde unterbrochen, weil der Thread von einer Anwendung oder einem Benutzer beendet wurde. |
| STATUS_TIMEOUT | Das Timeoutintervall ist abgelaufen, bevor die Nachricht zugestellt werden konnte oder bevor eine Antwort empfangen wurde. Dies ist ein Erfolgscode. |
Hinweise
FltSendMessage sendet eine Nachricht an eine Anwendung im Benutzermodus im Namen eines Minifiltertreibers oder eines Minifiltertreibers instance.
Wenn die Anwendung FilterGetMessage aufruft, um die Nachricht abzurufen, bevor der Minifiltertreiber FltSendMessage aufruft , um sie zu senden, wird die Nachricht sofort zugestellt. Dies ist in der Regel der Fall, wenn die Anwendung FilterGetMessage aus einer Nachrichtenschleife aufruft.
Andernfalls wird der Minifiltertreiber wie folgt in einen Wartezustand versetzt, wenn eine Anwendung nicht aufgerufen wurde, um eine Nachricht zu erhalten:
Wenn Timeout ungleich null ist und die Anwendung FilterGetMessage aufruft, bevor das Timeoutintervall abläuft, wird die Nachricht übermittelt.
Wenn Timeout ungleich null ist und die Anwendung FilterGetMessage nicht aufruft, bevor das Timeoutintervall abläuft, wird die Nachricht nicht übermittelt, und FltSendMessage gibt STATUS_TIMEOUT zurück. (Hinweis: STATUS_TIMEOUT ist ein Erfolgscode.)
Wenn Timeout null ist, wird der Minifiltertreiber unbegrenzt in einen Wartezustand versetzt. Wenn die Anwendung FilterGetMessage aufruft, wird die Nachricht übermittelt.
Wenn ReplyBuffer nach der Übermittlung der Nachricht NULL ist, gibt FltSendMessage STATUS_SUCCESS zurück.
Andernfalls wird der Minifiltertreiber wie folgt in einen Wartezustand versetzt, wenn ReplyBuffer nicht NULL ist:
Wenn Timeout ungleich null ist und die Anwendung FilterReplyMessage aufruft, bevor das Timeoutintervall abläuft, empfängt der Minifiltertreiber die Antwort, und FltSendMessage gibt STATUS_SUCCESS zurück.
Wenn Timeout ungleich null ist und der Minifiltertreiber vor Ablauf des Timeoutintervalls keine Antwort empfängt, gibt FltSendMessage STATUS_TIMEOUT zurück. (Hinweis: STATUS_TIMEOUT ist ein Erfolgscode.)
Wenn timeout null ist, wenn der Minifiltertreiber auf die Antwort wartet, wird der Minifiltertreiber unbegrenzt in einen Wartezustand versetzt. Wenn die Anwendung FilterReplyMessage aufruft, empfängt der Minifiltertreiber die Antwort, und FltSendMessage gibt STATUS_SUCCESS zurück.
Hinweis
Aufgrund von (systemspezifischen) Strukturabstandsanforderungen ist Genauigkeit erforderlich, wenn Sie die Größe der Puffer festlegen, die FltSendMessage und FilterReplyMessage zugeordnet sind. Angenommen, Daten müssen über FilterReplyMessage an einen Minifilter gesendet werden. Die Benutzermoduskomponente kann dazu die folgende Struktur deklarieren:
typedef struct _REPLY_STRUCT
{
FILTER_REPLY_HEADER Header;
MY_STRUCT Data; // The structure to be sent to the minifilter
} REPLY_STRUCT, *PREPLY_STRUCT;
Angesichts dieser Struktur mag es offensichtlich erscheinen, dass der Aufrufer von FilterReplyMessagedwReplyBufferSize auf sizeof(REPLY_STRUCT)und den ReplyLength-Parameter von FltSendMessage auf den gleichen Wert festlegen würde. Aufgrund der Strukturfüllung sizeof(REPLY_STRUCT) kann jedoch größer als sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT)sein. In diesem Fall gibt FltSendMessage STATUS_BUFFER_OVERFLOW zurück.
Daher wird empfohlen, FilterReplyMessage und FltSendMessage (unter Verwendung des obigen Beispiels) aufzurufen, indem Sie dwReplyBufferSize und ReplyLength auf sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) anstelle von sizeof(REPLY_STRUCT)festlegen. Dadurch wird sichergestellt, dass alle zusätzlichen Abstände am Ende der REPLY_STRUCT-Struktur ignoriert werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Microsoft Windows 2000 Updaterollup 1 für SP4, Windows XP SP2, Windows Server 2003 SP1 und höher. |
| Zielplattform | Universell |
| Header | fltkernel.h (fltKernel.h einschließen) |
| Bibliothek | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |