Funzione IoRegisterContainerNotification (wdm.h)

Articolo
03/08/2023

La routine IoRegisterContainerNotification registra un driver in modalità kernel per ricevere notifiche su una classe specificata di eventi.

Sintassi

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
    );

Parametri

[in] NotificationClass

Specifica la classe di eventi per cui il chiamante (driver) richiede notifiche. Impostare questo parametro sul valore di enumerazione IO_CONTAINER_NOTIFICATION_CLASS seguente:

IoSessionStateNotification

Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] CallbackFunction

Puntatore a una funzione di callback implementata dal chiamante (driver). La gestione I/O chiama questa funzione per notificare al chiamante quando si verifica un evento della classe indicata da NotificationClass . Per NotificationClass = IoSessionStateNotification, questo parametro è un puntatore a una funzione di IO_SESSION_NOTIFICATION_FUNCTION fornita dal chiamante. Tuttavia, il chiamante deve eseguire il cast di questo puntatore alla funzione per digitare PIO_CONTAINER_NOTIFICATION_FUNCTION per corrispondere al tipo di parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] NotificationInformation

Puntatore a un buffer allocato dal chiamante che contiene la struttura delle informazioni di notifica per un evento della classe specificata da NotificationClass. Per NotificationClass = IoSessionStateNotification, NotificationInformation punta a una struttura IO_SESSION_STATE_NOTIFICATION . Il chiamante deve compilare questa struttura prima di chiama IoRegisterContainerNotification. Durante questa chiamata, IoRegisterContainerNotification copia i dati da questa struttura e il gestore I/O non accede alla copia del driver della struttura dopo che la chiamata restituisce.

[in] NotificationInformationLength

Dimensioni, in byte, della struttura delle informazioni di notifica contenuta nel buffer a cui fa riferimento NotificationInformation. Per NotificationClass = IoSessionStateNotification, impostare questo parametro su sizeof(IO_SESSION_STATE_NOTIFICATION).

[out] CallbackRegistration

Puntatore a un percorso in cui questa routine scrive l'indirizzo di un oggetto di registrazione della notifica del contenitore. Questo oggetto è un oggetto di sistema opaco in cui gestione I/O archivia informazioni sulla registrazione della notifica del chiamante del chiamante. Quando le notifiche non sono più necessarie, il chiamante annulla la registrazione passando questo puntatore a oggetti alla routine IoUnregisterContainerNotification .

Valore restituito

IoRegisterContainerNotification restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti degli errori possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER_1	Parameter NotificationClass non è una costante di enumerazione valida IO_CONTAINER_NOTIFICATION_CLASS.
STATUS_INVALID_PARAMETER_3	Le informazioni nella struttura a cui fa riferimento NotificationInformation non sono corrette.
STATUS_INVALID_PARAMETER_4	Parameter NotificationInformationLength non è uguale alla dimensione della struttura delle informazioni di notifica necessaria per l'uso con il valore del parametro NotificationClass specificato.
STATUS_ALREADY_COMMITTED	Il driver è già registrato per ricevere notifiche NotificationClass degli eventi associati all'oggetto I/O specificato.
STATUS_INSUFFICIENT_RESOURCES	Il sistema operativo ha risorse insufficienti per creare la registrazione richiesta.

Commenti

Questa routine può potenzialmente supportare le notifiche degli eventi in diverse classi di eventi. In Windows 7 questa routine supporta solo le notifiche IoSessionStateNotification , che notificano a un driver in modalità kernel le modifiche nello stato delle sessioni utente a cui è interessato il driver. Per le applicazioni in modalità utente, la funzione WTSRegisterSessionNotification riempie un ruolo simile.

Il tipo di puntatore della funzione per il parametro CallbackFunction è definito come segue:

typedef NTSTATUS
  (*PIO_CONTAINER_NOTIFICATION_FUNCTION)(
    );

Il chiamante deve eseguire il cast del puntatore della funzione callback a questo tipo per corrispondere al tipo di parametro CallbackFunction . IoRegisterContainerNotification determina il tipo effettivo del puntatore della funzione di callback dal parametro NotificationClass . Per NotificationClass = IoSessionStateNotification, CallbackFunction punta a una funzione IO_SESSION_NOTIFICATION_FUNCTION .

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Vedi anche

IO_CONTAINER_NOTIFICATION_CLASS

IO_SESSION_NOTIFICATION_FUNCTION

IO_SESSION_STATE_NOTIFICATION

IoUnregisterContainerNotification

WTSRegisterSessionNotification

Condividi tramite