IoRegisterContainerNotification-Funktion (wdm.h)

  • Artikel

Die IoRegisterContainerNotification-Routine registriert einen Kernelmodustreiber, um Benachrichtigungen zu einer bestimmten Ereignisklasse zu empfangen.

Syntax

NTSTATUS
IoRegisterContainerNotification(
    _In_ IO_CONTAINER_NOTIFICATION_CLASS NotificationClass,
    _In_ PIO_CONTAINER_NOTIFICATION_FUNCTION CallbackFunction,
    _In_reads_bytes_opt_(NotificationInformationLength) PVOID NotificationInformation,
    _In_ ULONG NotificationInformationLength,
    _Out_ PVOID * CallbackRegistration
    );

Parameter

[in] NotificationClass

Gibt die Klasse von Ereignissen an, für die der Aufrufer (Treiber) Benachrichtigungen anfordert. Legen Sie diesen Parameter auf den folgenden IO_CONTAINER_NOTIFICATION_CLASS-Enumerationswert fest:

  • IoSessionStateNotification

Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] CallbackFunction

Ein Zeiger auf eine Rückruffunktion, die vom Aufrufer (Treiber) implementiert wird. Der E/A-Manager ruft diese Funktion auf, um den Aufrufer zu benachrichtigen, wenn ein Ereignis der durch NotificationClass angegebenen Klasse auftritt. Für NotificationClass = IoSessionStateNotification ist dieser Parameter ein Zeiger auf eine vom Aufrufer bereitgestellte IO_SESSION_NOTIFICATION_FUNCTION-Funktion . Der Aufrufer sollte diesen Funktionszeiger jedoch in den Typ PIO_CONTAINER_NOTIFICATION_FUNCTION umwandeln, um dem Parametertyp zu entsprechen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] NotificationInformation

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Benachrichtigungsinformationsstruktur für ein Ereignis der durch NotificationClass angegebenen Klasse enthält. Für NotificationClass = IoSessionStateNotification verweist NotificationInformation auf eine IO_SESSION_STATE_NOTIFICATION-Struktur . Der Aufrufer muss diese Struktur ausfüllen, bevor ioRegisterContainerNotification aufgerufen wird. Während dieses Aufrufs kopiert IoRegisterContainerNotification die Daten aus dieser Struktur, und der E/A-Manager greift nicht auf die Treiberkopie der Struktur zu, nachdem der Aufruf zurückgegeben wurde.

[in] NotificationInformationLength

Die Größe der Benachrichtigungsinformationsstruktur in Bytes, die im Puffer enthalten ist, auf den notificationInformation verweist. Legen Sie für NotificationClass = IoSessionStateNotification diesen Parameter auf sizeof(IO_SESSION_STATE_NOTIFICATION) fest.

[out] CallbackRegistration

Ein Zeiger auf einen Speicherort, in den diese Routine die Adresse eines Containerbenachrichtigungsregistrierungsobjekts schreibt. Dieses Objekt ist ein undurchsichtiges Systemobjekt, in dem der E/A-Manager Informationen zur Containerbenachrichtigungsregistrierung des Aufrufers speichert. Wenn keine Benachrichtigungen mehr erforderlich sind, bricht der Aufrufer die Registrierung ab, indem er diesen Objektzeiger an die IoUnregisterContainerNotification-Routine übergibt.

Rückgabewert

IoRegisterContainerNotification gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind:

Rückgabecode Beschreibung
STATUS_INVALID_PARAMETER_1 Parameter NotificationClass ist keine gültige IO_CONTAINER_NOTIFICATION_CLASS Enumerationskonstante.
STATUS_INVALID_PARAMETER_3 Die Informationen in der Struktur, auf die von NotificationInformation verwiesen wird, sind falsch.
STATUS_INVALID_PARAMETER_4 Der NotificationInformationLength-Parameter entspricht nicht der Größe der Benachrichtigungsinformationsstruktur, die für die Verwendung mit dem angegebenen NotificationClass-Parameterwert erforderlich ist.
STATUS_ALREADY_COMMITTED Der Treiber ist bereits registriert, um NotificationClass-Benachrichtigungen über Ereignisse zu erhalten, die dem angegebenen E/A-Objekt zugeordnet sind.
STATUS_INSUFFICIENT_RESOURCES Das Betriebssystem verfügt über unzureichende Ressourcen, um die angeforderte Registrierung zu erstellen.

Hinweise

Diese Routine kann potenziell Benachrichtigungen über Ereignisse in einer Vielzahl von Ereignisklassen unterstützen. In Windows 7 unterstützt diese Routine nur IoSessionStateNotification-Benachrichtigungen, die einen Kernelmodustreiber über Änderungen in der status von Benutzersitzungen benachrichtigen, an denen der Treiber interessiert ist. Bei Anwendungen im Benutzermodus erfüllt die Funktion WTSRegisterSessionNotification eine ähnliche Rolle.

Der Funktionszeigertyp für den Parameter CallbackFunction ist wie folgt definiert:

typedef NTSTATUS
  (*PIO_CONTAINER_NOTIFICATION_FUNCTION)(
    );

Der Aufrufer sollte den Rückruffunktionszeiger auf diesen Typ umwandeln, um dem Parametertyp CallbackFunction zu entsprechen. IoRegisterContainerNotification bestimmt den tatsächlichen Typ des Rückruffunktionszeigers aus dem NotificationClass-Parameter . Für NotificationClass = IoSessionStateNotification verweist CallbackFunction auf eine IO_SESSION_NOTIFICATION_FUNCTION-Funktion .

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Windows 7 und höheren Versionen des Windows-Betriebssystems.
Zielplattform Universell
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

Weitere Informationen

IO_CONTAINER_NOTIFICATION_CLASS

IO_SESSION_NOTIFICATION_FUNCTION

IO_SESSION_STATE_NOTIFICATION

IoUnregisterContainerNotification

WTSRegisterSessionNotification