WMI_QUERY_DATABLOCK_CALLBACK fonction de rappel (wmilib.h)

Article
08/08/2023

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

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 dans la structure WMILIB_CONTEXT qu’il a transmise à WmiSystemControl.

[in] InstanceIndex

Si DpWmiQueryDataBlock est appelé en réponse à une demande de IRP_MN_QUERY_SINGLE_INSTANCE, InstanceIndex spécifie un index de base zéro qui indique le 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 de taille InstanceCount fourni par l’appelant. Le pilote remplit chaque élément de tableau pour indiquer la longueur de chaque instance retourné. Si BufferAvail est égal à zéro, InstanceLengthArray a la valeur NULL.

[in] BufferAvail

Spécifie le nombre maximal d’octets disponibles pour recevoir des données dans la mémoire tampon dans La mémoire 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 Notes.

[out] Buffer

Pointeur vers la mémoire tampon pour recevoir instance données. Si la mémoire tampon est suffisamment grande pour recevoir toutes les données, le pilote écrit les données 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 retournée

DpWmiQueryDataBlock retourne STATUS_SUCCESS ou une status d’erreur telle que :

Si le pilote ne peut pas exécuter la demande immédiatement, il peut retourner STATUS_PENDING.

Remarques

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

Le pilote est responsable de la validation de 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 une structure WMIGUIDREGINFO 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 spécifient ensemble un certain nombre d’instances de blocs de données qui se trouvent dans la plage prise en charge par le pilote pour le bloc de données. Si InstanceIndex est différent de zéro, InstanceCount doit avoir la valeur 1. Si InstanceIndex a la valeur 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 Buffer 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 au sein de chaque instance.

Après avoir écrit instance données dans la mémoire tampon, le pilote appelle WmiCompleteRequest pour terminer la demande. Si la mémoire tampon décrite par Buffer et BufferAvail est nulle ou 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 IIP WMI.