IWbemServices::ExecMethodAsync, méthode (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 alors que les paramètres entrants sont transférés au fournisseur approprié où il s’exécute. Les informations et l’état sont retournés à l’appelant par le biais du récepteur d’objets fourni.

Les méthodes ne sont pas implémentées directement par Windows Management, mais sont exportées par des fournisseurs de méthodes. Pour toute 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’accès d’objet à une 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 l’instance qui contiennent la définition de la méthode.

[in] strMethodName

Nom de la méthode de l’objet.

[in] lFlags

WBEM_FLAG_SEND_STATUS s’inscrit auprès de Windows Management pour recevoir des rapports d’état intermédiaires via l’implémentation des clients iWbemObjectSink::SetStatus. L’implémentation du fournisseur doit prendre en charge les rapports d’état intermédiaires pour que cet indicateur change de 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 comme 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 une 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 une instance de la classe système __Parameters . Pour plus d’informations sur les codes de retour, consultez la section Notes. Lors de l’implémentation d’un fournisseur de méthodes, vous devez appeler Indiquer pour retourner les informations de paramètre de sortie avant d’appeler IWbemObjectSink::SetStatus pour signaler l’état final.

Valeur retournée

Cette méthode retourne un HRESULT indiquant l’état 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 .

Les codes d’erreur spécifiques à COM peuvent également être retournés si des problèmes réseau vous provoquent la perte de la connexion à distance à WMI.

Notes

Un fournisseur de méthodes unique peut fournir des méthodes pour de nombreuses classes et instances. Les fournisseurs de méthodes doivent traiter 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 appels intermédiaires à 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 le client nécessite, il est recommandé d’utiliser des semi-synchronisations au lieu d’une communication asynchrone. Si vous avez besoin d’une communication asynchrone, consultez Appel d’une méthode.

Valeurs retournées Description
ExecMethodAsync (obligatoire) Indique si les paramètres d’entrée de la méthode pointant vers le paramètre pInParams sont valides ou non.
Méthode appelée (facultatif) Dépendant de la méthode. La valeur de retour est placée dans la propriété ReturnValue de l’instance __PARAMETERS représentant les paramètres sortants et retournée par le biais d’un appel à Indiquer.
Paramètres de sortie de méthode appelées (facultatif) Dépendant de la méthode. Les paramètres sortants sont placés dans des propriétés non système d’une instance de __PARAMETERS et retournés par le biais d’Indiquer.
 

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 d’erreur ou d’analyse de chemin d’accès d’objet.

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

   
Client minimal pris en charge Windows Vista
Serveur minimal pris en charge Windows Server 2008
Plateforme cible Windows
En-tête wbemcli.h (include 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

Voir aussi

Appel d’une méthode

IWbemCallResult::GetResultObject

IWbemServices

IWbemServices::ExecMethodAsync