FilterGetMessage-Funktion (fltuser.h)

Artikel
08/23/2023

Die FilterGetMessage-Funktion ruft eine Nachricht von einem Minifilter im Kernelmodus ab.

Syntax

HRESULT FilterGetMessage(
  [in]      HANDLE                 hPort,
  [out]     PFILTER_MESSAGE_HEADER lpMessageBuffer,
  [in]      DWORD                  dwMessageBufferSize,
  [in, out] LPOVERLAPPED           lpOverlapped
);

Parameter

[in] hPort

Kommunikationsporthandle, das von einem vorherigen Aufruf von FilterConnectCommunicationPort zurückgegeben wurde. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[out] lpMessageBuffer

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Nachricht vom Minifilter empfängt. Die Nachricht muss eine FILTER_MESSAGE_HEADER-Struktur enthalten, andernfalls ist ihr Format vom Aufrufer definiert. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] dwMessageBufferSize

Größe des Puffers, auf den der lpMessageBuffer-Parameter verweist, in Bytes.

[in, out] lpOverlapped

Zeiger auf eine OVERLAPPED-Struktur. Dieser Parameter ist optional und kann NULL sein. Wenn es nicht NULL ist, muss der Aufrufer den hEvent-Member der OVERLAPPED-Struktur mit einem gültigen Ereignishandle oder NULL initialisieren.

Rückgabewert

FilterGetMessage gibt bei erfolgreicher Ausführung S_OK zurück. Andernfalls wird ein Fehlerwert zurückgegeben.

Hinweise

Die FilterGetMessage-Funktion ist sowohl für synchrone als auch für asynchrone (überlappende) Vorgänge konzipiert.

Wenn lpOverlappedNULL ist und eine Meldung verfügbar ist, wird FilterGetMessage sofort zurückgegeben. Andernfalls wird der Aufrufer in einen Wartezustand versetzt, bis eine Nachricht empfangen wird.

Wenn lpOverlapped nicht NULL ist, gibt FilterGetMessage ERROR_IO_PENDING zurück. In diesem Fall wird das Ereignisobjekt in der lpOverlapped-Struktur auf den nicht signalierten Zustand festgelegt, bevor FilterGetMessage zurückgegeben wird. Wenn die Nachricht übermittelt wird, wird dieses Ereignis auf den Signalzustand festgelegt.

Nachdem die Nachricht vom Minifilter empfangen wurde, kann der Aufrufer eine Antwort senden, indem er FilterReplyMessage aufruft.

Ein Minifilter oder instance sendet eine Nachricht an eine Anwendung im Benutzermodus, indem FltSendMessage aufgerufen wird.