WMI_QUERY_REGINFO_CALLBACK funzione di callback (wmilib.h)

Articolo
08/08/2023

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

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 WDM del driver DEVICE_OBJECT.

[out] RegFlags

Questo parametro indica 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 l'oggetto 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 dell'oggetto PDO. L'uso del percorso dell'istanza del dispositivo come base per i nomi di istanza statici è efficiente perché tali nomi sono garantiti univoci. WMI fornisce automaticamente un nome "descrittivo" per l'istanza come elemento in un blocco di dati che può essere sottoposto a query da parte dei consumer di dati.

Un driver può anche impostare uno o più flag seguenti in RegFlags, ma più in genere li impostano nei 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 impostati o sottoposti a query. Se questo flag è deselezionato, è anche possibile eseguire query o impostare i blocchi.

WMIREG_FLAG_EXPENSIVE

Richiede a WMI di inviare un IRP_MN_ENABLE_COLLECTION richiedere 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 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 in modo esplicito 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 per aggiornare le 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 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 è deselezionata, InstanceName viene ignorato.

[out] RegistryPath

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

[out] MofResourceName

Puntatore a una singola stringa Unicode conteggiata che indica il nome della risorsa MOF collegata al file di immagine binaria del driver. In genere questa stringa è una stringa statica definita dal driver. WMI crea una copia di questa stringa dopo che il driver restituisce 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 la restituzione di WmiSystemControl . Se il driver non ha una risorsa MOF associata, può lasciare invariato MofResourceName .

[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 OGGETTO 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.

Commenti

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 della routine DpWmiQueryReginfo 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 deregista i 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 blocchi da rimuovere, nella struttura WMILIB_CONTEXT passa a WmiSystemControl. Dopo la chiamata iniziale, che stabilisce il percorso del Registro di sistema del driver e il nome della risorsa MOF, la routine DpWmiQueryReginfo di un driver può modificare i flag comuni a tutti i blocchi di un driver, fornire una stringa di 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 dispositivo dell'oggetto PDO.

Il driver non deve restituire STATUS_PENDING o bloccare la richiesta. Il driver non deve completare la richiesta chiamando WmiCompleteRequest dalla routine DpWmiQueryReginfo o chiamando IoCompleteRequest dopo che WmiSystemControl restituisce.

Questa routine può essere paginabile.

Per altre informazioni sull'implementazione di questa routine, vedere Chiamata di WmiSystemControl per gestire i provider di accesso WMI.