IO_SESSION_NOTIFICATION_FUNCTION Rückruffunktion (wdm.h)

Artikel
02/27/2024

Der IO_SESSION_NOTIFICATION_FUNCTION Funktionstyp definiert eine Rückrufroutine, über die ein Treiber Benachrichtigungen über Änderungen im Zustand der Benutzersitzungen empfängt, an denen der Treiber interessiert ist.

Syntax

IO_SESSION_NOTIFICATION_FUNCTION IoSessionNotificationFunction;

NTSTATUS IoSessionNotificationFunction(
  [in] PVOID SessionObject,
  [in] PVOID IoObject,
  [in] ULONG Event,
  [in] PVOID Context,
  [in] PVOID NotificationPayload,
  [in] ULONG PayloadLength
)
{...}

Parameter

[in] SessionObject

Zeiger auf ein undurchsichtiges Systemobjekt, das Informationen zur Benutzersitzung enthält. Der Treiber kann diesen Zeigerwert als ContainerObject-Parameterwert an die IoGetContainerInformation-Routine übergeben.

[in] IoObject

Zeiger auf ein E/A-Objekt, das dem Treiber gehört. Dieser Parameter ist der E/A-Objektzeiger, den der Treiber für die IoRegisterContainerNotification-Routine bereitgestellt hat, als sich der Treiber zuvor registriert hat, um Benachrichtigungen über Sitzungsereignisse zu empfangen. Der NotificationInformation-Parameter der IoRegisterContainerNotification-Routine verweist auf eine IO_SESSION_STATE_NOTIFICATION-Struktur, deren IoObject-Member auf das E/A-Objekt verweist.

[in] Event

Eine IO_SESSION_EVENT Enumerationskonstante, die angibt, welches Sitzungsereignis den Benachrichtigungsrückruf verursacht hat.

[in] Context

Der Kontextwert, den der Treiber zuvor für die IoRegisterContainerNotification-Routine bereitgestellt hat, als sich der Treiber registriert hat, um Benachrichtigungen über Sitzungsereignisse zu empfangen. Im IoRegisterContainerNotification-Aufruf hat der Treiber einen Zeiger auf eine IO_SESSION_STATE_NOTIFICATION-Struktur bereitgestellt, deren Context-Member den Kontextwert enthält.

[in] NotificationPayload

Zeiger auf einen Nutzlastpuffer, der eine IO_SESSION_CONNECT_INFO-Struktur enthält.

[in] PayloadLength

Die Größe des Puffers in Bytes, auf die von NotificationPayload verwiesen wird. Die Puffergröße muss nie den konstanten Wert IO_SESSION_MAX_PAYLOAD_SIZE überschreiten, der in der Wdm.h-Headerdatei definiert ist.

Rückgabewert

Wenn die Routine erfolgreich ist, muss sie STATUS_SUCCESS zurückgeben. Andernfalls muss einer der fehler status Werte zurückgegeben werden, die in der Headerdatei "Ntstatus.h" definiert sind.

Hinweise

Ein Kernelmodustreiber implementiert diese Routine. Der E/A-Manager ruft diese Routine auf, um den Treiber über Sitzungsereignisse zu benachrichtigen.

Um Benachrichtigungen über Sitzungsereignisse zu erhalten, ruft ein Treiber die IoRegisterContainerNotification-Routine auf und legt den CallbackFunction-Parameter dieser Routine so fest, dass er auf die IO_SESSION_NOTIFICATION_FUNCTION Routine des Treibers verweist. Das E/A-Objekt, das der Treiber an IoRegisterContainerNotification übergibt, bestimmt, ob der Treiber Benachrichtigungen über Ereignisse in einer bestimmten Benutzersitzung oder über Ereignisse in allen Sitzungen empfängt. Weitere Informationen finden Sie unter IO_SESSION_STATE_NOTIFICATION.

Beispiele

Um eine E/A-Sitzungsbenachrichtigungsroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine E/A-Sitzungsbenachrichtigungsroutine mit dem Namen MyIoSessionNotificationzu definieren, verwenden Sie den typ IO_SESSION_NOTIFICATION_FUNCTION, wie in diesem Codebeispiel gezeigt:

IO_SESSION_NOTIFICATION_FUNCTION MyIoSessionNotification;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyIoSessionNotification(
    PVOID  SessionObject,
    PVOID  IoObject,
    ULONG  Event,
    PVOID  Context,
    PVOID  NotificationPayload,
    ULONG  PayloadLength
    )
  {
      // Function body
  }

Der IO_SESSION_NOTIFICATION_FUNCTION Funktionstyp ist in der Headerdatei Wdm.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den IO_SESSION_NOTIFICATION_FUNCTION Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in Windows 7 und höheren Versionen des Windows-Betriebssystems.
Zielplattform	Desktop
Kopfzeile	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
IRQL	Wird unter IRQL <= APC_LEVEL aufgerufen.