Funzione IoRegisterPlugPlayNotification (wdm.h)

Articolo
02/27/2024

La routine IoRegisterPlugPlayNotification registra una routine di callback di notifica Plug and Play (PnP) da chiamare quando si verifica un evento PnP della categoria specificata.

Sintassi

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

Parametri

[in] EventCategory

Specifica un valore di enumerazione da IO_NOTIFICATION_EVENT_CATEGORY che indica la categoria dell'evento PnP per cui viene registrata la routine di callback.

[in] EventCategoryFlags

Flag bit che modificano l'operazione di registrazione. I valori possibili sono:

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Valido solo con EventCategory di EventCategoryDeviceInterfaceChange. Se impostato, il gestore PnP chiama la routine di callback del driver per ogni istanza dell'interfaccia del dispositivo attualmente registrata e attiva e registra la routine di callback per gli arrivi futuri o le rimozioni delle istanze dell'interfaccia del dispositivo.

[in, optional] EventCategoryData

Puntatore a ulteriori informazioni sugli eventi per i quali viene registrata CallbackRoutine . Le informazioni variano per valori EventCategory diversi:

Quando EventCategory è EventCategoryDeviceInterfaceChange, EventCategoryData deve puntare a un GUID che specifica una classe di interfaccia dispositivo. CallbackRoutine verrà chiamato quando un'interfaccia di tale classe è abilitata o rimossa.
Quando EventCategory è EventCategoryHardwareProfileChange, EventCategoryData deve essere NULL.
Quando EventCategory è EventCategoryTargetDeviceChange, EventCategoryData deve puntare all'oggetto file per cui viene richiesta la notifica PnP.

[in] DriverObject

Puntatore all'oggetto driver del chiamante.

Per assicurarsi che il driver rimanga caricato mentre è registrato per la notifica PnP, questa chiamata incrementa il conteggio dei riferimenti in DriverObject. Il gestore PnP decrementa il conteggio dei riferimenti quando questa registrazione viene rimossa.

Per EventCategoryTargetDeviceChange, DriverObject non deve essere l'oggetto driver del dispositivo di destinazione; deve essere invece l'oggetto driver del driver che implementa CallbackRoutine.

[in] CallbackRoutine

Puntatore alla routine di callback di notifica PnP da chiamare quando si verifica l'evento PnP specificato.

Il prototipo di funzione per questa routine di callback è definito come segue:

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

NotificationStructure della routine di callback è specifico del valore EventCategory, come illustrato nella tabella seguente.

Categoria evento	Struttura delle notifiche
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION Per altre informazioni, vedere Uso della notifica PnP e TARGET_DEVICE_CUSTOM_NOTIFICATION.

Il parametro Context della routine di callback contiene i dati di contesto forniti dal driver durante la registrazione.

Per informazioni sull'inclusione di una dichiarazione di funzione per la routine di callback che soddisfa i requisiti di Static Driver Verifier (SDV), vedere Esempi.

Il gestore PnP chiama routine di callback del driver in IRQL = PASSIVE_LEVEL.

[in, optional] Context

Puntatore a un buffer allocato dal chiamante contenente il contesto che il gestore PnP passa alla routine di callback.

[out] NotificationEntry

Puntatore a un valore opaco restituito da questa chiamata che identifica la registrazione. Passare questo valore alla routine IoUnregisterPlugPlayNotificationEx per rimuovere la registrazione.

Valore restituito

IoRegisterPlugPlayNotification restituisce STATUS_SUCCESS o uno stato di errore appropriato.

Commenti

Un driver esegue la registrazione per una categoria di eventi. Ogni categoria include uno o più tipi di eventi PnP.

Un driver può registrare routine di callback diverse per categorie di eventi diverse o può registrare una singola routine di callback. Una singola routine di callback può eseguire il cast di NotificationStructure a un PLUGPLAY_NOTIFICATION_HEADER e usare il campo Evento per determinare il tipo esatto della struttura di notifica.

Se il chiamante specifica PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES, il sistema operativo potrebbe chiamare due volte la routine di callback di notifica PnP per un singolo evento EventCategoryDeviceInterfaceChange per un'interfaccia esistente. È possibile ignorare in modo sicuro la seconda chiamata al callback. Il sistema operativo non chiamerà il callback più di due volte per un singolo evento.

Le routine di callback delle notifiche PnP devono completare le attività il più rapidamente possibile e restituire il controllo al gestore PnP, per evitare ritardi nella notifica ad altri driver e applicazioni registrati per l'evento.

La gestione PnP non rimuove un riferimento sull'oggetto file quando un driver esegue la registrazione per la notifica di un evento EventCategoryTargetDeviceChange . Se la routine di callback di notifica PnP del driver richiede l'accesso all'oggetto file, il driver deve rimuovere un riferimento aggiuntivo sull'oggetto file prima di chiamare IoRegisterPlugPlayNotification.

In genere, i driver Kernel-Mode Driver Framework (KMDF) devono chiamare IoRegisterPlugPlayNotification dalla funzione di callback EvtDeviceSelfManagedIoInit e devono chiamare IoUnregisterPlugPlayNotification dalla funzione di callback EvtDeviceSelfManagedIoCleanup . Questi driver non devono chiamare IoRegisterPlugPlayNotification dalla funzione di callback EvtDriverDeviceAdd ; in caso contrario, la routine di callback di notifica PnP potrebbe essere chiamata prima che lo stack di driver venga avviato da PnP, nel qual caso il driver non sarà pronto a gestire la notifica.

Per altre informazioni, vedere Uso della notifica PnP.

Esempio

Per definire una routine di callback di notifica PnP, è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback di notifica PnP denominata MyCallbackRoutine, usare il tipo di DRIVER_NOTIFICATION_CALLBACK_ROUTINE, come illustrato nell'esempio di codice seguente:

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

Il tipo di funzione DRIVER_NOTIFICATION_CALLBACK_ROUTINE è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione DRIVER_NOTIFICATION_CALLBACK_ROUTINE nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM. Per informazioni su _Use_decl_annotations_, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)