Méthode IWbemServices ::ExecMethodAsync (wbemcli.h)

La méthode IWbemServices ::ExecMethodAsync exécute de façon asynchrone une méthode exportée par un objet CIM. L’appel retourne immédiatement au client tandis que les paramètres entrants sont transférés au fournisseur approprié où il s’exécute. Les informations et les status sont retournées à l’appelant via le récepteur d’objets fourni.

Les méthodes ne sont pas implémentées directement par Windows Management, mais sont exportées par les fournisseurs de méthodes. Pour une classe CIM donnée, les méthodes disponibles et leurs paramètres font partie de la documentation du fournisseur en question.

Syntaxe

HRESULT ExecMethodAsync(
  [in] const BSTR       strObjectPath,
  [in] const BSTR       strMethodName,
  [in] long             lFlags,
  [in] IWbemContext     *pCtx,
  [in] IWbemClassObject *pInParams,
  [in] IWbemObjectSink  *pResponseHandler
);

Paramètres

[in] strObjectPath

BSTR valide contenant le chemin d’accès de l’objet pour lequel la méthode doit être exécutée. Vous pouvez appeler une méthode statique à l’aide d’un nom de classe ou d’un chemin d’objet vers un instance. Le fournisseur de méthodes peut analyser le paramètre de chemin d’accès de l’objet pour déterminer la classe et les instance qui contiennent la définition de méthode.

[in] strMethodName

Nom de la méthode pour l'objet.

[in] lFlags

WBEM_FLAG_SEND_STATUS inscrit auprès de Windows Management une demande de réception de rapports status intermédiaires via l’implémentation cliente d’IWbemObjectSink ::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports intermédiaires status pour que cet indicateur modifie le comportement. Notez que l’indicateur WBEM_FLAG_USE_AMENDED_QUALIFIERS ne peut pas être utilisé ici.

[in] pCtx

Généralement NULL ; sinon, il s’agit d’un pointeur vers un objet IWbemContext qui peut être utilisé par le fournisseur exécutant la méthode . 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] pInParams

Peut être NULL si aucun paramètre entrant n’est requis pour exécuter la méthode. Sinon, cela pointe vers un objet IWbemClassObject qui contient les propriétés agissant en tant que paramètres entrants pour l’exécution de la méthode. Le contenu de l’objet est spécifique à la méthode et fait partie de la spécification du fournisseur en question. Toutefois, l’objet le plus courant est un instance de la classe système __Parameters. Pour chaque paramètre d’entrée de la méthode à appeler, il existe une propriété non système. Les fournisseurs de méthodes ignorent les qualificateurs d’ID attachés à chaque paramètre de la méthode, qui sont généralement utilisés uniquement par les navigateurs et les applications similaires.

[in] pResponseHandler

Ne peut pas être NULL. Le récepteur d’objets reçoit le résultat de l’appel de méthode. Les paramètres sortants sont envoyés à IWbemObjectSink ::Indicate. L’objet retourné le plus courant est un instance de la classe système __Parameters. Pour plus d’informations sur les codes de retour, consultez la section Remarques. Lors de l’implémentation d’un fournisseur de méthodes, vous devez appeler Indique pour retourner des informations de paramètre de sortie avant d’appeler IWbemObjectSink ::SetStatus pour signaler la status finale.

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.

En cas d’échec, vous pouvez obtenir toutes les informations disponibles à partir de la fonction COM GetErrorInfo.

D’autres erreurs sont signalées de manière asynchrone au récepteur d’objets fourni dans 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 à WMI.

Remarques

Un fournisseur de méthodes unique peut fournir des méthodes pour de nombreuses classes et instances. Les fournisseurs de méthodes doivent gérer un maximum de trois valeurs de retour.

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.

Exemples

L’exemple C++ suivant montre comment implémenter la méthode IWbemServices ::ExecMethodAsync pour la méthode Echo de la classe TestMeth . La classe TestMeth prend en charge une méthode qui a un paramètre d’entrée et un paramètre de sortie et qui retourne un entier 32 bits non signé. L’implémentation suppose qu’il n’existe qu’une seule méthode appelée Echo et une classe qui la contient. Par souci de concision, il n’y a pas de vérification des erreurs ou d’analyse du chemin d’accès aux objets.

STDMETHODIMP CMyMethodProvider::ExecMethodAsync(BSTR ObjectPath, 
    BSTR MethodName, long lFlags, IWbemContext* pCtx, 
    IWbemClassObject* pInParams, IWbemObjectSink* pResultSink)
{
    HRESULT hr;
    IWbemClassObject * pClass = NULL;
    IWbemClassObject * pOutClass = NULL;
    IWbemClassObject* pOutParams;

    // Allocate some BSTRs.

    BSTR ClassName = SysAllocString(L"TestMeth");    
    BSTR InputArgName = SysAllocString(L"sInArg");
    BSTR OutputArgName = SysAllocString(L"sOutArg");
    BSTR retValName = SysAllocString(L"ReturnValue");

    // Get the class object; this is hard-coded and matches the class
    // in the MOF.  A more sophisticated example would parse 
    // ObjectPath to determine the class and possibly the instance.
    // The m_pWbemSvcs pointer is of type IWbemServices*
    hr = m_pWbemSvcs->GetObject(ClassName, 0, pCtx, &pClass, NULL);

    // This method returns values, and so creates an instance of the
    // output argument class.

    hr = pClass->GetMethod(MethodName, 0, NULL, &pOutClass);
    pOutClass->SpawnInstance(0, &pOutParams);

    // Copy the input argument into the output object.

    VARIANT var;
    VariantInit(&var);

    // Get the input argument.
    pInParams->Get(InputArgName, 0, &var, NULL, NULL);   

    // Put it into the output object.
    pOutParams->Put(OutputArgName , 0, &var, 0);      

    long lLen = wcslen(var.bstrVal);
    VariantClear(&var);
    var.vt = VT_I4;
    var.lVal = lLen;
    // Special name for the return value.
    pOutParams->Put(retValName , 0, &var, 0); 

    // Send the output object back to the client by the sink. Then 
    // release the pointers and free the strings.

    hr = pResultSink->Indicate(1, &pOutParams);
    pOutParams->Release();
    pOutClass->Release();
    pClass->Release();
    SysFreeString(ClassName);
    SysFreeString(InputArgName);
    SysFreeString(OutputArgName);
    SysFreeString(retValName);
 
    // All done; now set the status.

    hr = pResultSink->SetStatus(0,WBEM_S_NO_ERROR,NULL,NULL);
    return WBEM_S_NO_ERROR;
}

Configuration requise

Voir aussi

Appel d’une méthode

IWbemCallResult::GetResultObject

IWbemServices

IWbemServices::ExecMethodAsync