WMI_SET_DATAITEM_CALLBACK fonction de rappel (wmilib.h)

Article
02/07/2025

La routine DpWmiSetDataItem modifie un élément de données unique dans une instance d’un bloc de données. Cette routine est facultative.

Syntaxe

WMI_SET_DATAITEM_CALLBACK WmiSetDataitemCallback;

NTSTATUS WmiSetDataitemCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] ULONG InstanceIndex,
  [in] ULONG DataItemId,
  [in] ULONG BufferSize,
  [in] 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 le bloc spécifié par guidIndex a plusieurs instances, InstanceIndex est une valeur de base zéro qui spécifie l’instance.

[in] DataItemId

Spécifie l’ID de l’élément de données à définir.

[in] BufferSize

Spécifie la taille en octets de la mémoire tampon à tampon.

[in] Buffer

Pointeur vers une mémoire tampon qui contient la nouvelle valeur de l’élément de données.

Valeur de retour

DpWmiSetDataItem retourne STATUS_SUCCESS ou un code d’erreur approprié, par exemple :

Remarques

WMI appelle la routine DpWmiSetDataItem d’un pilote après que le pilote appelle WmiSystemControl en réponse à une demande de IRP_MN_CHANGE_SINGLE_ITEM.

N’implémentez pas DpWmiSetDataItem, sauf si vous êtes sûr qu’un composant en mode utilisateur fourni par le système nécessite cette fonctionnalité. Si vous implémentez une routine DpWmiSetDataItem, le pilote doit placer l’adresse de la routine dans le membre SetWmiDataItem de la structure WMILIB_CONTEXT qu’elle passe à WmiSystemControl. Si vous n’implémentez pas de routine DpWmiSetDataItem, le pilote doit définir SetWmiDataItem sur NULL. Dans ce dernier cas, WMI retourne STATUS_READ_ONLY à l’appelant.

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 de WMIREG_FLAG_REMOVE_GUID dans un WMIGUIDREGINFO structure contenue dans une structure WMILIB_CONTEXT, il est possible qu’une demande définie arrive avant la suppression.
Vérifiez que la valeur InstanceIndex se trouve dans la plage d’index d’instance pris en charge par le pilote pour le bloc de données.
Vérifiez que la valeur DataItemId se trouve dans la plage d’identificateurs d’élément de données pris en charge par le pilote pour le bloc de données.
Vérifiez que tampon et BufferSize décrivent un élément de données de taille valide et que le contenu de la mémoire tampon est valide pour l’élément de données.
Vérifiez que l’élément de données spécifié est un pour lequel le pilote autorise les modifications initiées par l’appelant. En d’autres termes, le pilote ne doit pas autoriser les modifications apportées aux éléments de données que vous souhaitiez être en lecture seule.

Ne partez pas du principe que le contexte de thread est celui de l’application en mode utilisateur initial, un pilote de niveau supérieur peut l’avoir modifié.

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.

Exigences

Exigence	Valeur
plateforme cible	Bureau
d’en-tête	wmilib.h (include Wmilib.h)
IRQL	Appelé à PASSIVE_LEVEL.

Voir aussi

IRP_MN_CHANGE_SINGLE_ITEM

WMILIB_CONTEXT

WmiSystemControl

Partager via