WMI_QUERY_DATABLOCK_CALLBACK fonction de rappel (wmilib.h)

Article
02/07/2025

La routine DpWmiQueryDataBlock retourne une instance unique ou toutes les instances d’un bloc de données. Cette routine est requise.

Syntaxe

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
)
{...}

Paramètres

[in] DeviceObject

Pointeur vers la structure de DEVICE_OBJECT WDM du pilote.

[in] Irp

Pointeur vers l’IRP.

[in] GuidIndex

Spécifie le bloc de données en fournissant un index de base zéro dans la liste des GUID fournis par le pilote fourni dans la structure WMILIB_CONTEXT passée à WmiSystemControl.

[in] InstanceIndex

Si DpWmiQueryDataBlock est appelé en réponse à une requête IRP_MN_QUERY_SINGLE_INSTANCE, InstanceIndex spécifie un index de base zéro qui indique l’instance du bloc de données spécifié à interroger. Si dpWmiQueryDataBlock est appelé en réponse à une demande de IRP_MN_QUERY_ALL_DATA, InstanceIndex est égal à zéro.

[in] InstanceCount

Si dpWmiQueryDataBlock est appelé en réponse à une demande de IRP_MN_QUERY_SINGLE_INSTANCE, InstanceCount est 1. Si dpWmiQueryDataBlock est appelé en réponse à une demande de IRP_MN_QUERY_ALL_DATA, InstanceCount correspond au nombre d’instances à retourner.

[in, out] InstanceLengthArray

Pointeur vers un tableau d’éléments ULONG fourni par l’appelant, InstanceCount. Le pilote renseigne chaque élément de tableau pour indiquer la longueur de chaque instance retournée. Si bufferAvail est égal à zéro, InstanceLengthArray est NULL.

[in] BufferAvail

Spécifie le nombre maximal d’octets disponibles pour recevoir des données dans la mémoire tampon à tampon. Si cette valeur est égale à zéro, l’appelant demande que le pilote spécifie la taille de mémoire tampon requise dans son appel à WmiCompleteRequest. Pour plus d’informations, consultez la section Remarques.

[out] Buffer

Pointeur vers la mémoire tampon pour recevoir des données d’instance. Si la mémoire tampon est suffisamment grande pour recevoir toutes les données, le pilote écrit les données d’instance dans la mémoire tampon avec chaque instance alignée sur une limite de 8 octets. Si la mémoire tampon est trop petite pour recevoir toutes les données, le pilote appelle WmiCompleteRequest avec BufferUsed défini sur la taille requise.

Valeur de retour

DpWmiQueryDataBlock retourne STATUS_SUCCESS ou un état d’erreur tel que le suivant :

Si le pilote ne peut pas terminer la requête immédiatement, il peut retourner STATUS_PENDING.

Remarques

WMI appelle la routine DpWmiQueryDataBlock d’un pilote après que le pilote appelle WmiSystemControl en réponse à une demande de IRP_MN_QUERY_SINGLE_INSTANCE ou de IRP_MN_QUERY_ALL_DATA. Le pilote doit placer l’adresse de son dpWmiQueryDataBlock routine dans la structure WMILIB_CONTEXT qu’il passe à WmiSystemControl.

Le pilote est chargé de valider tous les arguments d’entrée. Plus précisément, le pilote doit effectuer les opérations suivantes :

Vérifiez que la valeur GuidIndex est comprise entre zéro et GuidCount-1, en fonction du membre GuidCount de la structure WMILIB_CONTEXT.
Vérifiez que le pilote n’a pas marqué le bloc de données spécifié pour la suppression. Si le pilote a récemment spécifié l’indicateur WMIREG_FLAG_REMOVE_GUID dans un WMIGUIDREGINFO structure contenue dans une structure WMILIB_CONTEXT, il est possible qu’une requête arrive avant la suppression.
Vérifiez que les valeurs InstanceIndex et InstanceCount, ensemble, spécifiez un certain nombre d’instances de bloc de données qui se trouvent dans la plage prise en charge par le pilote pour le bloc de données. Si InstanceIndex n’est pas zéro, InstanceCount doit être 1. Si InstanceIndex est 0, InstanceCount ne doit pas être supérieur au nombre d’instances prises en charge.
Vérifiez que la mémoire tampon décrite par tampon et BufferAvail est suffisamment grande pour contenir toutes les instances demandées du bloc de données. Chaque instance doit commencer sur une limite de 8 octets et un remplissage supplémentaire peut exister entre les éléments de données de chaque instance.

Après avoir écrit des données d’instance dans la mémoire tampon, le pilote appelle WmiCompleteRequest pour terminer la requête. Si la mémoire tampon décrite par tampon et bufferAvail est égale à zéro ou est trop petite pour recevoir toutes les données demandées, l’appel à WmiCompleteRequest doit spécifier STATUS_BUFFER_TOO_SMALL pour le paramètre Status et la taille de mémoire tampon requise pour le paramètre BufferUsed .

Cette routine peut être paginable.

Pour plus d’informations sur l’implémentation de cette routine, consultez Appel de WmiSystemControl pour gérer les runtimes d’intégration WMI.