IWbemServices ::P utInstance, méthode (wbemcli.h)

La méthode IWbemServices ::P utInstance crée ou met à jour un instance d’une classe existante. L’instance est écrite dans le référentiel WMI.

Syntaxe

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

Paramètres

[in] pInst

Pointeur vers le instance à écrire. L’appelant ne peut pas faire d’hypothèses sur le nombre de références à la fin de cet appel.

[in] lFlags

Une ou plusieurs des valeurs suivantes peuvent être définies.

WBEM_FLAG_CREATE_OR_UPDATE

Cet indicateur entraîne la création du instance s’il n’existe pas ou le remplacement s’il existe déjà.

WBEM_FLAG_UPDATE_ONLY

Cet indicateur entraîne la mise à jour de cet appel. Pour que l’appel réussisse, l’instance doit exister.

WBEM_FLAG_CREATE_ONLY

Cet indicateur est utilisé uniquement pour la création. L’appel échoue si l’instance existe.

WBEM_FLAG_RETURN_IMMEDIATELY

Cet indicateur fait qu’il s’agit d’un appel semi-synchronisé. Pour plus d’informations, consultez Appel d’une méthode.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Si cet indicateur est défini, WMI ne stocke aucun qualificateur avec la saveur Modifiée . Si cet indicateur n’est pas défini, il est supposé que cet objet n’est pas localisé et que tous les qualificateurs sont stockés avec cette instance.

[in] pCtx

Généralement NULL, indiquant que chaque propriété du instance doit être mise à jour. Sinon, il s’agit d’un pointeur vers un objet IWbemContext contenant plus d’informations sur le instance. Les données de l’objet de contexte doivent être documentées par le fournisseur responsable du instance. Un objet IWbemContext non NULL peut indiquer si la prise en charge des mises à jour partielles instance existe.

Pour plus d’informations sur la prise en charge des mises à jour complètes et partielles instance, consultez IWbemServices ::P utInstanceAsync. Pour plus d’informations sur la demande d’une opération de mise à jour instance complète ou partielle, consultez Modification d’une propriété d’instance.

[out] ppCallResult

Si la valeur est NULL, ce paramètre n’est pas utilisé. Si le paramètre lFlags contient WBEM_FLAG_RETURN_IMMEDIATELY, cet appel retourne immédiatement avec WBEM_S_NO_ERROR. Le paramètre ppCallResult reçoit ensuite un pointeur vers un nouvel objet IWbemCallResult , qui peut être interrogé avec IWbemCallResult ::GetCallStatus pour obtenir le résultat.

Valeur retournée

Cette méthode retourne une valeur HRESULT qui indique le statut de l'appel de méthode. La liste suivante répertorie la valeur contenue dans un HRESULT.

Des codes d’erreur spécifiques à COM peuvent également être retournés si des problèmes réseau vous font perdre la connexion à distance à Windows Management.

Remarques

Les applications et les fournisseurs appellent PutInstance pour créer ou mettre à jour un instance d’une classe existante. Selon la façon dont le paramètre pCtx est défini, tout ou partie des propriétés du instance sont mises à jour. Pour plus d’informations sur la prise en charge de la mise à jour partielle des instance, consultez IWbemServices ::P utInstanceAsync. Pour plus d’informations sur la demande d’une mise à jour partielle instance, consultez Modification d’une propriété d’instance.

La méthode PutInstance prend uniquement en charge la création d’instances et la mise à jour d’instances. Il ne prend pas en charge le déplacement d’instances. Autrement dit, un appelant ne peut pas définir le paramètre pInst sur un instance qui a une clé identique à celle d’une autre instance dans une classe frère. Par exemple, supposons que ClassA est la classe de base de ClassB et ClassC. La classe ClassA définit la propriété KeyProp comme sa clé et ClassB a un instance qui a KeyProp défini sur 1. Pour créer un instance de ClassC avec KeyProp défini sur 1, une application doit d’abord supprimer le instance ClassBen appelant DeleteInstance, puis enregistrer le instance ClassC avec PutInstance.

Lorsque le instance pointé par pInst appartient à une sous-classe, Windows Management appelle tous les fournisseurs responsables des classes dont dérive la sous-classe. Tous ces fournisseurs doivent réussir pour que la demande PutInstance d’origine 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 se poursuit de haut en bas jusqu’à ce que Windows Management atteigne le fournisseur pour la classe propriétaire de la instance pointée par pInst.

Windows Management n’appelle les fournisseurs pour aucune classe enfant d’une instance. Par conséquent, si une application souhaite modifier les valeurs des propriétés héritées, l’application doit appeler PutInstance sur la instance complète de la classe enfant plutôt qu’une instance correspondante de la classe parente.

Lorsqu’une application doit mettre à jour un instance qui appartient à une hiérarchie de classes, le paramètre pInst doit pointer vers le 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 modifier la valeur de PropA dans le instance ClassB, elle doit définir pInst sur cette instance plutôt qu’une instance de ClassA.

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

Configuration requise

Voir aussi

Création d'une instance

IWbemCallResult

IWbemServices

IWbemServices::PutInstanceAsync

Récupération d’un code d’erreur