WMI_QUERY_REGINFO_CALLBACK funzione di callback (wmilib.h)

Articolo
02/07/2025

La routine DpWmiQueryReginfo fornisce informazioni sui blocchi di dati e sui blocchi eventi da registrare da un driver. Questa routine è obbligatoria.

Sintassi

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

Parametri

[in] DeviceObject

Puntatore alla struttura DEVICE_OBJECT WDM del driver.

[out] RegFlags

Questo parametro indica le caratteristiche comuni di tutti i blocchi registrati. Qualsiasi flag impostato in RegFlags viene applicato a tutti i blocchi. Un driver può integrare RegFlags per un determinato blocco impostando flag nella struttura WMIGUIDREGINFO del blocco. Ad esempio, un driver potrebbe cancellare WMIREG_FLAG_EXPENSIVE in RegFlags, ma impostarlo in Flag per registrare un determinato blocco come costoso da raccogliere.

Il driver imposta uno dei flag seguenti in RegFlags:

WMIREG_FLAG_INSTANCE_BASENAME

Richiede a WMI di generare nomi di istanza statici da un nome di base fornito dal driver in InstanceName. WMI genera nomi di istanza aggiungendo un contatore al nome di base.

WMIREG_FLAG_INSTANCE_PDO

Richiede a WMI di generare nomi di istanza statici dall'ID istanza del dispositivo per il PDO. Se il driver imposta questo flag, deve anche impostare Pdo sul PDO passato alla routine AddDevice del driver. WMI genera nomi di istanza dal percorso dell'istanza del dispositivo del PDO. L'uso del percorso dell'istanza del dispositivo come base per i nomi di istanza statici è efficiente perché tali nomi sono sicuramente univoci. WMI fornisce automaticamente un nome "descrittivo" per l'istanza come elemento in un blocco di dati su cui è possibile eseguire query da parte dei consumer di dati.

Un driver può anche impostare uno o più dei flag seguenti in RegFlags, ma più in genere vengono impostati in Flag della struttura WMIGUIDREGINFO di un blocco:

WMIREG_FLAG_EVENT_ONLY_GUID

I blocchi possono essere abilitati o disabilitati solo come eventi e non possono essere sottoposti a query o impostati. Se questo flag è chiaro, è anche possibile eseguire query o impostare i blocchi.

WMIREG_FLAG_EXPENSIVE

Richiede a WMI di inviare una richiesta di IRP_MN_ENABLE_COLLECTION la prima volta che un consumer di dati apre un blocco di dati e una richiesta di IRP_MN_DISABLE_COLLECTION quando l'ultimo consumer di dati chiude il blocco di dati. Questa operazione è consigliata se la raccolta di tali dati influisce sulle prestazioni, perché un driver non deve raccogliere i dati fino a quando un consumer di dati non lo richiede esplicitamente aprendo il blocco.

WMIREG_FLAG_REMOVE_GUID

Richiede a WMI di rimuovere il supporto per i blocchi. Questo flag è valido solo in risposta a una richiesta di aggiornamento delle informazioni di registrazione (IRP_MN_REGINFO o IRP_MN_REGINFO_EX con Parameters.WMI.DataPath impostato su WMIUPDATE).

[out] InstanceName

Puntatore a una singola stringa Unicode con conteggiata che funge da nome di base per tutte le istanze di tutti i blocchi da registrare dal driver. WMI libera la stringa con ExFreePool. Se WMIREG_FLAG_INSTANCE_BASENAME è chiaro, InstanceName viene ignorato.

[out] RegistryPath

Puntatore a un puntatore a una stringa Unicode con conteggiata che specifica il percorso del Registro di sistema passato alla routine DriverEntry del driver.

[out] MofResourceName

Puntatore a una singola stringa Unicode con conteggiata che indica il nome della risorsa MOF collegata al file di immagine binario del driver. In genere questa stringa è un valore statico definito dal driver. WMI crea una copia di questa stringa dopo che il driver viene restituito da questa routine. Questa stringa può essere allocata dinamicamente dal driver. Nel caso di una stringa allocata, il driver è responsabile della liberazione della stringa che deve essere eseguita dopo che WmiSystemControl restituisce. Se il driver non dispone di una risorsa MOF collegata, può lasciare MofResourceName invariato.

[out] Pdo

Puntatore all'oggetto dispositivo fisico (PDO) passato alla routine AddDevice del driver. Se WMIREG_FLAG_INSTANCE_PDO è impostato, WMI usa il percorso dell'istanza del dispositivo di questo PDO come base da cui generare nomi di istanza statici. Se WMIREG_FLAG_INSTANCE_PDO è chiaro, WMI ignora Pdo.

Valore restituito

DpWmiQueryReginfo restituisce sempre STATUS_SUCCESS.

Osservazioni

WMI chiama la routine DpWmiQueryReginfo di un driver dopo che il driver chiama WmiSystemControl in risposta a una richiesta di IRP_MN_REGINFO o IRP_MN_REGINFO_EX. Il driver deve inserire l'indirizzo del relativo DpWmiQueryReginfo routine nella struttura WMILIB_CONTEXT che passa a WmiSystemControl.

WMI invia l'IRP dopo che un driver chiama IoWMIRegistrationControl con WMIREG_ACTION_REGISTER, WMIREG_ACTION_REREGISTER o WMIREG_ACTION_UPDATE. WMI gestisce in modo trasparente le differenze tra IRP_MN_REGINFO e IRP_MN_REGINFO_EX per conto del driver.

WMI non invia una richiesta di IRP_MN_REGINFO o IRP_MN_REGINFO_EX dopo che un driver chiama IoWMIRegistrationControl con WMIREG_ACTION_DEREGISTER, perché WMI non richiede ulteriori informazioni dal driver. Un driver in genere annulla la registrazione dei blocchi in risposta a una richiesta di IRP_MN_REMOVE_DEVICE.

Il driver fornisce informazioni di registrazione nuove o aggiornate sui singoli blocchi o indica i blocchi da rimuovere, nella struttura WMILIB_CONTEXT passa a WmiSystemControl. Dopo la chiamata iniziale, che stabilisce il percorso del Registro di sistema e il nome della risorsa MOF del driver, il DpWmiQueryReginfo routine può modificare i flag comuni a tutti i blocchi di un driver, fornire una stringa del nome di base diversa usata per generare nomi di istanza o modificare la base per i nomi di istanza da una stringa al percorso dell'istanza del PDO.

Il driver non deve restituire STATUS_PENDING o bloccare la richiesta. Il driver non deve completare la richiesta chiamando WmiCompleteRequest dal relativo DpWmiQueryReginfo routine o chiamando IoCompleteRequest dopo WmiSystemControl.

Questa routine può essere visualizzabile a pagina.

Per altre informazioni sull'implementazione di questa routine, vedere Calling WmiSystemControl to Handle WMI IRPs.