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-werden.
[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
Zeigen Sie auf einen vom Aufrufer zugewiesenen Puffer, der die Nachricht enthält, die an die Benutzermodusanwendung gesendet werden soll. Dieser Parameter ist erforderlich und kann nicht NULL-werden.
[in] SenderBufferLength
Größe des Puffers in Bytes, auf den SenderBuffer verweist. Weitere Informationen finden Sie in Anmerkungen.
[out, optional] ReplyBuffer
Zeigen Sie auf einen vom Aufrufer zugewiesenen Puffer, der die Antwort (sofern vorhanden) von der Anwendung empfängt. Dieser Parameter ist optional und kann NULL-werden.
[in, out] ReplyLength
Größe des Puffers, auf den "ReplyBuffer" in Bytes verweist. Dieser Parameter ist optional, muss jedoch nichtNULL- sein, wenn ReplyBuffer- nicht NULL-ist.
[in, optional] Timeout
Ein Zeiger auf einen Timeoutwert, der die 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 Anwendung für den Benutzermodus empfangen wird und bis sie eine Antwort empfängt (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 Uhrzeit an. Wird auf NULL- festgelegt, 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 | FltSendMessage ein Poolzuordnungsfehler aufgetreten ist. Dies ist ein Fehlercode. |
| STATUS_PORT_DISCONNECTED | Der Kommunikationsport wurde getrennt. Dies ist ein Fehlercode. |
| STATUS_THREAD_IS_TERMINATING | Die Wartezeit wurde unterbrochen, da der Thread von einer Anwendung oder einem Benutzer beendet wurde. |
| STATUS_TIMEOUT | Das Timeout Intervall abgelaufen, bevor die Nachricht übermittelt werden konnte oder bevor eine Antwort empfangen wurde. Dies ist ein Erfolgscode. |
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 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 zum Abrufen einer Nachricht aufgerufen wurde:
Wenn Timeout- nicht null ist und die Anwendung FilterGetMessage- aufruft, bevor das Timeout Intervall abläuft, wird die Nachricht zugestellt.
Wenn Timeout- ungleich Null ist und die Anwendung FilterGetMessage- nicht aufruft, bevor das Timeout Intervall 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 auf unbestimmte Zeit in einen Wartezustand versetzt. Wenn die Anwendung FilterGetMessage-aufruft, wird die Nachricht zugestellt.
Wenn ReplyBufferNULL-ist, gibt FltSendMessage STATUS_SUCCESS zurück.
Andernfalls, wenn ReplyBuffer nicht NULL-ist, wird der Minifiltertreiber wie folgt in einen Wartezustand versetzt:
Wenn Timeout- nicht null ist und die Anwendung FilterReplyMessage- aufruft, bevor das Timeout Intervall abläuft, empfängt der Minifiltertreiber die Antwort, und FltSendMessage gibt STATUS_SUCCESS zurück.
Wenn Timeout- nicht null ist und der Minifiltertreiber keine Antwort empfängt, bevor das Timeout Intervall abläuft, 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.
Anmerkung
Aufgrund (systemspezifischer) Strukturabstandsanforderungen ist die Genauigkeit erforderlich, wenn Sie die Größe von Puffern festlegen, die FltSendMessage und FilterReplyMessage-zugeordnet sind. Nehmen wir beispielsweise an, dass Daten über FilterReplyMessage- an einen Minifilter gesendet werden müssen. Die Benutzermoduskomponente deklariert möglicherweise die folgende Struktur, um dies zu tun:
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 scheint es offensichtlich, dass der Aufrufer von FilterReplyMessage-dwReplyBufferSize auf sizeof(REPLY_STRUCT)festlegen und den ReplyLength Parameter von FltSendMessage auf denselben Wert festlegen würde. Aufgrund von Strukturabstands-Idiosyncrasien kann sizeof(REPLY_STRUCT) jedoch größer als sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT)sein. Wenn dies der Fall ist, gibt FltSendMessage STATUS_BUFFER_OVERFLOW zurück.
Daher wird empfohlen, FilterReplyMessage- und FltSendMessage- (unter Verwendung des obigen Beispiels) aufzurufen, indem Sie dwReplyBufferSize- und ReplyLength sowohl sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) als auch sizeof(REPLY_STRUCT)festlegen. Dadurch wird sichergestellt, dass alle zusätzlichen Abstände am Ende der REPLY_STRUCT Struktur ignoriert werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Microsoft Windows 2000 UpdateRollup 1 für SP4, Windows XP SP2, Windows Server 2003 SP1 und höhere Betriebssysteme. |
| Zielplattform- | Universal |
| Header- | fltkernel.h (include FltKernel.h) |
| Library | FltMgr.lib |
| DLL- | Fltmgr.sys |
| IRQL- | <= APC_LEVEL |