WMI_QUERY_DATABLOCK_CALLBACK funzione di callback (wmilib.h)

Articolo
08/08/2023

La routine DpWmiQueryDataBlock restituisce una singola istanza o tutte le istanze di un blocco di dati. Questa routine è necessaria.

Sintassi

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

Parametri

[in] DeviceObject

Puntatore alla struttura WDM del driver DEVICE_OBJECT.

[in] Irp

Puntatore all'IRP.

[in] GuidIndex

Specifica il blocco di dati specificando un indice in base zero nell'elenco di GUID forniti dal driver nella struttura WMILIB_CONTEXT passata a WmiSystemControl.

[in] InstanceIndex

Se DpWmiQueryDataBlock viene chiamato in risposta a una richiesta di IRP_MN_QUERY_SINGLE_INSTANCE , InstanceIndex specifica un indice in base zero che indica l'istanza del blocco di dati specificato da eseguire query. Se DpWmiQueryDataBlock viene chiamato in risposta a una richiesta di IRP_MN_QUERY_ALL_DATA , InstanceIndex è zero.

[in] InstanceCount

Se DpWmiQueryDataBlock viene chiamato in risposta a una richiesta di IRP_MN_QUERY_SINGLE_INSTANCE , InstanceCount è 1. Se DpWmiQueryDataBlock viene chiamato in risposta a una richiesta di IRP_MN_QUERY_ALL_DATA , InstanceCount è il numero di istanze da restituire.

[in, out] InstanceLengthArray

Puntatore a una matrice fornita dal chiamante, InstanceCount-size di elementi ULONG. Il driver riempie ogni elemento della matrice per indicare la lunghezza di ogni istanza restituita. Se BufferAvail è zero, InstanceLengthArray è NULL.

[in] BufferAvail

Specifica il numero massimo di byte disponibili per ricevere i dati nel buffer in Buffer. Se questo valore è zero, il chiamante richiede che il driver specifichi le dimensioni del buffer necessarie nella chiamata a WmiCompleteRequest. Per altre informazioni, vedere la sezione Osservazioni.

[out] Buffer

Puntatore al buffer per ricevere i dati dell'istanza. Se il buffer è abbastanza grande per ricevere tutti i dati, il driver scrive i dati dell'istanza nel buffer con ogni istanza allineata a un limite di 8 byte. Se il buffer è troppo piccolo per ricevere tutti i dati, il driver chiama WmiCompleteRequest con BufferUsed impostato sulle dimensioni necessarie.

Valore restituito

DpWmiQueryDataBlock restituisce STATUS_SUCCESS o uno stato di errore, ad esempio quanto segue:

Se il driver non riesce a completare immediatamente la richiesta, può restituire STATUS_PENDING.

Commenti

WMI chiama la routine DpWmiQueryDataBlock di un driver dopo che il driver chiama WmiSystemControl in risposta a una richiesta di IRP_MN_QUERY_SINGLE_INSTANCE o IRP_MN_QUERY_ALL_DATA . Il driver deve inserire l'indirizzo della routine DpWmiQueryDataBlock nella struttura WMILIB_CONTEXT che passa a WmiSystemControl.

Il driver è responsabile della convalida di tutti gli argomenti di input. In particolare, il driver deve eseguire le operazioni seguenti:

Verificare che il valore GuidIndex sia compreso tra zero e GuidCount-1, in base al membro GuidCount della struttura WMILIB_CONTEXT .
Verificare che il driver non abbia contrassegnato il blocco di dati specificato per la rimozione. Se il driver ha specificato di recente il flag WMIREG_FLAG_REMOVE_GUID in una struttura WMIGUIDREGINFO contenuta in una struttura WMILIB_CONTEXT , è possibile che una query venga visualizzata prima che si verifichi la rimozione.
Verificare che i valori InstanceIndex e InstanceCount , insieme, specificano un numero di istanze del blocco di dati all'interno dell'intervallo supportato dal driver per il blocco dati. Se InstanceIndex è diverso da zero, InstanceCount deve essere 1. Se InstanceIndex è 0, InstanceCount non deve essere maggiore del numero di istanze supportate.
Verificare che il buffer descritto da Buffer e BufferAvail sia sufficiente per contenere tutte le istanze richieste del blocco di dati. Ogni istanza deve iniziare su un limite di 8 byte e un riempimento aggiuntivo potrebbe esistere tra elementi di dati all'interno di ogni istanza.

Dopo aver scritto i dati dell'istanza nel buffer, il driver chiama WmiCompleteRequest per completare la richiesta. Se il buffer descritto da Buffer e BufferAvail è zero o è troppo piccolo per ricevere tutti i dati richiesti, la chiamata a WmiCompleteRequest deve specificare STATUS_BUFFER_TOO_SMALL per il parametro Status e le dimensioni del buffer necessarie per il parametro BufferUsed .

Questa routine può essere paginabile.

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