WMI_QUERY_DATABLOCK_CALLBACK funzione di callback (wmilib.h)

Articolo
02/07/2025

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

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

[in] Irp

Puntatore all'IRP.

[in] GuidIndex

Specifica il blocco di dati specificando un indice in base zero nell'elenco dei GUID forniti dal driver nella struttura WMILIB_CONTEXT passato 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 su cui eseguire una query. Se il DpWmiQueryDataBlock viene chiamato in risposta a una richiesta di IRP_MN_QUERY_ALL_DATA, InstanceIndex è zero.

[in] InstanceCount

Se il 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 un chiamante fornito, InstanceCountmatrice ridimensionata di elementi ULONG. Il driver compila 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 la ricezione dei dati nel buffer in Buffer. Se questo valore è zero, il chiamante richiede che il driver specifichi la dimensione del buffer richiesta 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 è sufficientemente grande da ricevere tutti i dati, il driver scrive i dati dell'istanza nel buffer con ogni istanza allineata su 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 simile al seguente:

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

Osservazioni

WMI chiama 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 del relativo DpWmiQueryDataBlock routine 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 di WMIREG_FLAG_REMOVE_GUID in una struttura WMIGUIDREGINFO contenuta in una struttura WMILIB_CONTEXT, è possibile che una query arrivi prima che si verifichi la rimozione.
Verificare che i valori InstanceIndex e InstanceCount, insieme, specificare una serie di istanze del blocco di dati all'interno dell'intervallo supportato dal driver per il blocco di 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 sufficientemente grande da contenere tutte le istanze richieste del blocco di dati. Ogni istanza deve iniziare su un limite di 8 byte e la spaziatura interna aggiuntiva potrebbe esistere tra gli 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 visualizzabile a pagina.

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