Méthode IWbemServices::P utInstanceAsync (wbemcli.h)

Article
08/27/2023

La méthode IWbemServices::P utInstanceAsync crée ou met à jour de manière asynchrone un instance d’une classe existante. La confirmation de mise à jour ou le rapport d’erreurs est fourni via l’interface IWbemObjectSink implémentée par l’appelant.

Syntaxe

HRESULT PutInstanceAsync(
  [in] IWbemClassObject *pInst,
  [in] long             lFlags,
  [in] IWbemContext     *pCtx,
  [in] IWbemObjectSink  *pResponseHandler
);

Paramètres

[in] pInst

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

[in] lFlags

Spécifie si l’appelant souhaite que le instance créé si le instance n’existe pas actuellement.

Lorsque vous implémentez un fournisseur de instance, vous pouvez choisir de prendre en charge un nombre limité d’indicateurs dans lFlags en retournant WBEM_E_PROVIDER_NOT_CAPABLE.

Cette propriété peut avoir une ou plusieurs des valeurs suivantes.

WBEM_FLAG_CREATE_OR_UPDATE

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

WBEM_FLAG_UPDATE_ONLY

Mises à jour un instance existant.

WBEM_FLAG_CREATE_ONLY

Cet indicateur est destiné à instance création uniquement. L’appel échoue si la classe existe déjà.

WBEM_FLAG_SEND_STATUS

Cet indicateur enregistre auprès de Windows Management une demande de réception de rapports status intermédiaires via l’implémentation cliente de IWbemObjectSink::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports intermédiaires status pour que cet indicateur modifie le comportement.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Si cet indicateur est défini, WMI ne stocke aucun qualificateur avec la version 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

Pointeur décrivant si le client demande une mise à jour partielle instance ou une mise à jour instance complète. Une mise à jour de instance partielle modifie un sous-ensemble des propriétés du instance. En revanche, une mise à jour instance complète modifie toutes les propriétés. Si la valeur est NULL, ce paramètre indique que l’application appelante demande une mise à jour instance complète. Sinon, il s’agit d’un pointeur vers un objet IWbemContext requis par le fournisseur de classes dynamiques qui produit les instances de classe. Pour plus d’informations sur ce paramètre, consultez Effectuer des appels à WMI.

[in] pResponseHandler

Pointeur vers l’implémentation de IWbemObjectSink par l’appelant. Ce gestionnaire reçoit le status de cet appel lorsqu’il devient disponible à l’aide de la méthode IWbemObjectSink::SetStatus. Si un code d’erreur est retourné, le pointeur IWbemObjectSink fourni n’est pas utilisé. Si WBEM_S_NO_ERROR est retourné, l’implémentation IWbemObjectSink de l’utilisateur est appelée pour indiquer le résultat de l’opération. Windows Management appelle uniquement AddRef sur le pointeur dans les cas où WBEM_S_NO_ERROR retourne. Dans les cas où un code d’erreur est retourné, le nombre de références est le même que lors de l’entrée. Pour plus d’informations sur la façon d’effectuer des appels asynchrones, consultez Appel d’une méthode.

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.

Notez que si PutInstanceAsync retourne WBEM_S_NO_ERROR, WMI attend un résultat de la méthode SetStatus du gestionnaire de réponses. WMI attend indéfiniment sur une connexion locale ou jusqu’à ce qu’un délai d’expiration de connexion à distance se produise.

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 clients qui appellent PutInstanceAsync doivent toujours s’attendre à ce que les résultats de l’appel soient signalés à l’aide de leur méthode IWbemObjectSink::Indicate .

Lorsque le instance pointé par pInst appartient à une classe dérivée d’autres classes, la réussite de PutInstanceAsync dépend de la réussite des fournisseurs responsables des classes parentes. Par exemple, si pInst appartient à ClassB et que ClassB dérive de ClassA, un appel à la méthode PutInstanceAsync implémentée par le fournisseur pour ClassA doit réussir pour que l’opération de mise à jour sur ClassB réussisse. Pour plus d’informations, consultez Remarques dans IWbemServices::P utInstance.

Lors de l’implémentation d’un fournisseur de instance, si la instance a une propriété de clé définie sur NULL, PutInstanceAsync doit choisir une valeur garantie unique dans la classe . Lorsque WMI traite une demande de mise à jour d’un instance avec une propriété de clé NULL, il génère en interne un GUID et l’affecte à la propriété de clé. En outre, lorsque la instance en cours de mise à jour appartient à une classe enfant, la réussite de l’opération dépend de la réussite d’un appel PutInstanceAsync à chacun des fournisseurs responsables des classes supérieures dans la hiérarchie. Ne retournez pas WBEM_S_NO_ERROR tant que vous n’êtes pas sûr que tous les autres fournisseurs ont réussi. Pour plus d’informations, consultez IWbemServices::P utInstance.

Les fournisseurs d’instances prenant en charge une mise à jour partielle doivent case activée pour l’existence de la valeur de contexte __PUT_EXTENSIONS. Une valeur de contexte système est une valeur définie par WMI pour avoir des significations spécifiques, est définie par l’application cliente et est prise en charge par un fournisseur de instance. L’interface IWbemContext permet d’accéder aux valeurs de contexte système et à d’autres valeurs de contexte spécifiques au fournisseur. La liste suivante répertorie les valeurs de contexte qui prennent en charge les opérations de mise à jour de instance partielle.

La méthode IWbemObjectSink::SetStatus est appelée pour indiquer la fin du jeu de résultats. Il peut également être appelé sans appel intermédiaire à IWbemObjectSink::Indique si des conditions d’erreur se produisent.

Étant donné que le rappel peut ne pas être retourné au même niveau d’authentification que celui requis par le client, il est recommandé d’utiliser des semi-synchrones au lieu d’une communication asynchrone. Si vous avez besoin d’une communication asynchrone, consultez Appel d’une méthode.

Pour plus d’informations sur l’utilisation de méthodes semi-synchronisées, consultez IWbemServices::P utInstance et Appel d’une méthode.

Valeur de contexte système	Description
__PUT_EXTENSIONS (VT_BOOL)	L’application cliente a défini une ou plusieurs des autres valeurs de contexte système pour fournir plus d’informations sur l’opération de mise à jour.
__PUT_EXT_STRICT_NULLS (VT_BOOL)	Le fournisseur de instance doit forcer le paramètre des propriétés à VT_NULL le cas échéant et générer une erreur en cas d’échec.
__PUT_EXT_PROPERTIES (VT_ARRAY \| VT_BSTR)	Contient une liste des propriétés à mettre à jour. Le fournisseur de instance doit ignorer toutes les autres propriétés.
__PUT_EXT_ATOMIC (VT_BOOL)	Toutes les mises à jour doivent réussir ou le fournisseur de instance doit revenir en arrière. Il ne peut y avoir de réussite partielle.

Lorsque vous implémentez un fournisseur de instance, vous devez répondre à une propriété NULL dans pCtx de la manière suivante :

Si le type de propriété est VT_NULL, le fournisseur peut ignorer la propriété sans apporter de modification ou échouer l’opération.
Si le type de propriété n’est pas VT_NULL et que la propriété ne peut pas être mise à jour, le fournisseur doit retourner une erreur, car le fournisseur est obligé de mettre à jour la propriété avec la nouvelle valeur.

Si pCtx n’est pas NULL et pointe vers des informations de contexte valides, l’application appelante demande une mise à jour partielle instance. Comme précédemment, un fournisseur de instance qui ne prend pas en charge la mise à jour partielle instance doit échouer l’opération en retournant WBEM_E_PROVIDER_NOT_CAPABLE.

Lors de l’implémentation d’une opération asynchrone, l’opération asynchrone n’est pas terminée tant que vous n’avez pas libéré les AddRef que vous avez effectués sur pResponseHandler. C’est le cas même si vous appelez SetStatus sur pResponseHander. Si pResponseHandler est divulgué, les clients de synchronisation ou de semi-synchronisation ne se terminent pas non plus et peuvent cesser de répondre, en fonction de votre implémentation.

Même dans les cas catastrophiques, vous devez libérer les références pour les fournisseurs découplés. En effet, dans les cas de synchronisation et de semi-synchronisation, le service WMI est propriétaire de l’implémentation de pResponseHandler : même si le processus de votre fournisseur découplé se ferme, les clients ne répondent toujours pas.

Exemples

L’exemple suivant décrit comment structurer PutInstanceAsync.

HRESULT CStdProvider::PutInstanceAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pInst,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
   // You must implement the InstanceIsValid method
   // to check to see if the instance in the pInst variable
   // is valid.
   if (InstanceIsValid(lFlags, pInst)) 
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

Configuration requise


Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	wbemcli.h (inclure Wbemidl.h)
Bibliothèque	Wbemuuid.lib
DLL	Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll