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

La méthode IWbemServices ::P utClassAsync crée une classe ou met à jour une classe existante. La classe spécifiée par le paramètre pObject doit être correctement initialisée avec toutes les valeurs de propriété requises. L’appel retourne immédiatement. La réussite ou l’échec est fournie au récepteur d’objets spécifié par le paramètre pResponseHandler .

Syntaxe

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

Paramètres

[in] pObject

Pointeur vers l’objet contenant la définition de classe.

[in] lFlags

Une ou plusieurs des valeurs suivantes sont valides.

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.

WBEM_FLAG_CREATE_OR_UPDATE

Cet indicateur entraîne la création de cette classe si elle n’existe pas ou est remplacée si elle existe déjà.

WBEM_FLAG_UPDATE_ONLY

Mises à jour une classe existante.

WBEM_FLAG_CREATE_ONLY

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

WBEM_FLAG_SEND_STATUS

Cet indicateur inscrit auprès de Windows Management une demande de réception de rapports status intermédiaires par le biais de l’implémentation par le client 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_OWNER_UPDATE

Les fournisseurs push doivent spécifier cet indicateur lors de l’appel de PutClassAsync pour indiquer que cette classe a changé.

WBEM_FLAG_UPDATE_COMPATIBLE

Cet indicateur permet de mettre à jour une classe s’il n’y a pas de classes dérivées et s’il n’y a pas d’instances pour cette classe. Il autorise également les mises à jour dans tous les cas si la modification concerne uniquement des qualificateurs non importants (par exemple, le qualificateur Description ). Il s’agit du comportement par défaut pour cet appel et est utilisé pour la compatibilité avec les versions précédentes de Windows Management. Si la classe comprend des instances ou si les modifications ont été apportées à des qualificateurs importants, la mise à jour échouera.

WBEM_FLAG_UPDATE_SAFE_MODE

Cet indicateur autorise les mises à jour des classes même s’il existe des classes enfants, tant que la modification n’entraîne pas de conflits avec les classes enfants. Un exemple de mise à jour que cet indicateur autoriserait serait d’ajouter une nouvelle propriété à la classe de base qui n’a pas été mentionnée précédemment dans l’une des classes enfants. Si la classe comprend des instances, la mise à jour échouera.

WBEM_FLAG_UPDATE_FORCE_MODE

Cet indicateur force les mises à jour des classes quand il existe des classes enfants en conflit. Un exemple de mise à jour forcée de cet indicateur serait si un qualificateur de classe était défini dans une classe enfant et que la classe de base tentait d’ajouter le même qualificateur qui était en conflit avec l’existant. En mode force, ce conflit est résolu en supprimant le qualificateur en conflit dans la classe enfant.

[in] pCtx

Généralement NULL. Sinon, il s’agit d’un pointeur vers un objet IWbemContext qui peut être utilisé par le fournisseur qui reçoit la classe demandée. Les valeurs de l’objet de contexte doivent être spécifiées dans la documentation du fournisseur en question. 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 la status de la requête Put lorsque le status devient disponible à l’aide de la méthode 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 au 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 obtenir une explication détaillée de ce paramètre, 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.

D’autres codes status ou d’erreur sont signalés au récepteur d’objets spécifié par le paramètre pReponseHandler.

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.

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.

Étant donné que le retour d’WBEM_E_FAILED empêche d’autres fournisseurs de créer la classe, elle ne doit être retournée que lorsque le fournisseur de classe a échoué d’une manière susceptible de réussir ultérieurement.

Remarques

Si plusieurs fournisseurs de classes sont installés pour une classe particulière, WMI ne reconnaît pas le fournisseur de classes capable de créer cette classe.

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 semi-synchrone des méthodes, consultez IWbemServices ::P utClass et Appel d’une méthode.

Exemples

L’exemple de code suivant décrit une implémentation simple de PutClassAsync.

HRESULT CStdProvider::PutClassAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pObject,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    // You must implement the ClassIsValid function yourself to
    // determine if the class contains a valid instance
   if (ClassIsValid(lFlags, pObject))
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

Configuration requise

Voir aussi

Appel d’une méthode

Création d’une classe

IWbemServices

IWbemServices::PutClass