Partager via

PutInstanceWmi, fonction

  • Article

Crée ou met à jour une instance d’une classe existante. L’instance est écrite dans le référentiel WMI.

Notes

Cette API est destinée à un usage interne uniquement. Elle n’est pas destinée à être utilisée dans le code du développeur.

Syntaxe

HRESULT PutInstanceWmi (
   [in] IWbemClassObject*    pInst,
   [in] long                 lFlags,
   [in] IWbemContext*        pCtx,
   [out] IWbemCallResult**   ppCallResult
);

Paramètres

pInst
[in] Pointeur vers l’instance à écrire.

lFlags
[in] Combinaison d’indicateurs qui affectent le comportement de cette fonction. Les valeurs suivantes sont définies dans le fichier d’en-tête WbemCli.h, ou vous pouvez les définir comme constantes dans votre code :

Constant Valeur Description
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x20000 Si la valeur est définie, WMI ne stocke aucun qualificateur avec la saveur Amended.
Si elle n’est pas définie, il est supposé que cet objet n’est pas localisé, et que tous les qualificateurs sont stockés avec cette instance.
WBEM_FLAG_CREATE_OR_UPDATE 0 Créer l’instance si elle n’existe pas, ou la remplacer si elle existe.
WBEM_FLAG_UPDATE_ONLY 1 Mettre à jour l’instance. Pour que l’appel réussisse, l’instance doit exister.
WBEM_FLAG_CREATE_ONLY 2 Créez l'instance. L’appel échoue si l’instance existe.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 L’indicateur provoque un appel semi-synchrone.

pCtx
[in] En règle générale, cette valeur est null. Sinon, il s’agit d’un pointeur vers une instance IWbemContext utilisable par le fournisseur des classes demandées.

ppCallResult
[out] Si la valeur est null, ce paramètre n’est pas utilisé. Si lFlags contient WBEM_FLAG_RETURN_IMMEDIATELY, la fonction retourne immédiatement WBEM_S_NO_ERROR. Le paramètre ppCallResult reçoit un pointeur vers un nouvel objet IWbemCallResult.

Valeur retournée

Les valeurs suivantes renvoyées par cette fonction sont définies dans le fichier d’en-tête WbemCli.h, ou vous pouvez les définir comme constantes dans votre code :

Constant Valeur Description
WBEM_E_ACCESS_DENIED 0x80041003 L’utilisateur n’a pas l’autorisation de mettre à jour une instance de la classe spécifiée.
WBEM_E_FAILED 0x80041001 Une erreur inconnue s’est produite.
WBEM_E_INVALID_CLASS 0x80041010 La classe prenant en charge cette instance n’est pas valide.
WBEM_E_ILLEGAL_NULL 0x80041028 La valeur null a été spécifiée pour une propriété qui ne peut pas être null, telle une propriété marquée par un qualificateur Indexed ou Not_Null.
WBEM_E_INVALID_OBJECT 0x8004100f L'instance spécifiée n'est pas valide. (Par exemple, l’appel de PutInstanceWmi avec une classe retourne cette valeur.)
WBEM_E_INVALID_PARAMETER 0x80041008 Un paramètre n'est pas valide.
WBEM_E_ALREADY_EXISTS 0x80041019 L’indicateur WBEM_FLAG_CREATE_ONLY a été spécifié, mais l’instance existe déjà.
WBEM_E_NOT_FOUND 0x80041002 WBEM_FLAG_UPDATE_ONLY a été spécifié dans lFlags, mais l’instance n’existe pas.
WBEM_E_OUT_OF_MEMORY 0x80041006 La mémoire n'est pas suffisante pour terminer cette opération.
WBEM_E_SHUTTING_DOWN 0x80041033 WMI a probablement été arrêté et est en cours de redémarrage. Appelez de nouveau ConnectServerWmi.
WBEM_E_TRANSPORT_FAILURE 0x80041015 Le lien d’appel de procédure distante (RPC) entre le processus actuel et WMI a échoué.
WBEM_S_NO_ERROR 0 L’appel de fonction a abouti.

Notes

Cette fonction encapsule un appel à la méthode IWbemServices::PutInstance.

La fonction PutInstanceWmi ne prend en charge que la création d’instances et la mise à jour d’instances de classes existantes. Selon la façon dont le paramètre pCtx est défini, certaines ou toutes les propriétés de l’instance sont mises à jour.

Lorsque l’instance sur laquelle pointe pInst appartient à une sous-classe, Windows Management appelle tous les fournisseurs responsables des classes dont la sous-classe dérive. Tous ces fournisseurs doivent réussir pour que la requête d’origine PutInstanceWmi réussisse. Le fournisseur prenant en charge la classe la plus haute dans la hiérarchie est appelé en premier. L’ordre d’appel continue avec la sous-classe de la classe la plus haute, et poursuit de haut en bas jusqu’à ce que Windows Management atteigne le fournisseur pour la classe propriétaire de l’instance vers laquelle pointe pInst. Windows Management n’appelle les fournisseurs pour aucune classe enfant d’une instance.

Lorsqu’une application doit mettre à jour une instance appartenant à une hiérarchie de classes, le paramètre pInst doit pointer vers l’instance contenant les propriétés à modifier. Autrement dit, considérons une instance cible appartenant à ClassB. L’instance ClassB dérive de ClassA, et ClassA définit la propriété PropA. Si une application souhaite apporter une modification à la valeur de PropA dans l’instance ClassB, elle doit définir pInst sur cette instance plutôt qu’une instance de ClassA.

L’appel de PutInstanceWmi sur une instance d’une classe abstraite n’est pas autorisé.

Si l’appel de fonction échoue, vous pouvez obtenir des informations d’erreur supplémentaires en appelant la fonction GetErrorInfo.

Spécifications

Plateformes : Consultez Configuration requise.

En-tête : WMINet_Utils.idl

Versions de .NET Framework : disponibles depuis la version 4.7.2

Voir aussi