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

O método IWbemServices::ExecMethodAsync executa de forma assíncrona um método exportado por um objeto CIM. A chamada retorna imediatamente ao cliente enquanto os parâmetros de entrada são encaminhados para o provedor apropriado em que ele é executado. Informações e status são retornados ao chamador por meio do coletor de objeto fornecido.

Os métodos não são implementados diretamente pelo Gerenciamento do Windows, mas são exportados por provedores de método. Para qualquer classe CIM específica, os métodos disponíveis e seus parâmetros fazem parte da documentação do provedor em questão.

Sintaxe

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

Parâmetros

[in] strObjectPath

BSTR válido que contém o caminho do objeto para o qual o método deve ser executado. Você pode invocar um método estático usando um nome de classe ou um caminho de objeto para uma instância. O provedor de método pode analisar o parâmetro de caminho do objeto para determinar a classe e a instância que contêm a definição do método.

[in] strMethodName

Nome do método para o objeto.

[in] lFlags

WBEM_FLAG_SEND_STATUS registra no Gerenciamento do Windows uma solicitação para receber relatórios intermediários status por meio da implementação de clientes de IWbemObjectSink::SetStatus. A implementação do provedor deve dar suporte a relatórios de status intermediários para que esse sinalizador altere o comportamento. Observe que o sinalizador WBEM_FLAG_USE_AMENDED_QUALIFIERS não pode ser usado aqui.

[in] pCtx

Normalmente NULL; caso contrário, esse é um ponteiro para um objeto IWbemContext que pode ser usado pelo provedor que executa o método . Os valores no objeto de contexto devem ser especificados na documentação do provedor em questão. Para obter mais informações sobre esse parâmetro, consulte Fazendo chamadas para WMI.

[in] pInParams

Pode ser NULL se nenhum parâmetro de entrada for necessário para executar o método. Caso contrário, isso aponta para um objeto IWbemClassObject que contém as propriedades que atuam como parâmetros de entrada para a execução do método. O conteúdo do objeto é específico do método e faz parte da especificação do provedor em questão. No entanto, o objeto mais comum é uma instância da classe do sistema __Parameters . Para cada parâmetro de entrada para o método a ser chamado, há uma propriedade que não é do sistema. Os provedores de método ignoram os qualificadores de ID anexados a cada parâmetro no método , que normalmente são usados apenas por navegadores e aplicativos semelhantes.

[in] pResponseHandler

Não pode ser NULL. O coletor de objeto recebe o resultado da chamada de método. Os parâmetros de saída são enviados para IWbemObjectSink::Indicate. O objeto retornado mais comum é uma instância da classe do sistema __Parameters . Para obter mais informações sobre códigos de retorno, consulte a seção Comentários. Ao implementar um provedor de método, você deve chamar Indicate para retornar informações de parâmetro de saída antes de chamar IWbemObjectSink::SetStatus para relatar o status final.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista o valor contido em um HRESULT.

Em caso de falha, você pode obter todas as informações disponíveis da função COM GetErrorInfo.

Outros erros são relatados de forma assíncrona para o coletor de objetos fornecido no parâmetro pReponseHandler .

Códigos de erro específicos de COM também poderão ser retornados se problemas de rede fizerem com que você perca a conexão remota com o WMI.

Comentários

Um provedor de método único pode fornecer métodos para várias classes e instâncias. Os provedores de método precisam lidar com um máximo de três valores retornados.

O método IWbemObjectSink::SetStatus é chamado para indicar o final do conjunto de resultados. Ele também pode ser chamado sem chamadas intermediárias para IWbemObjectSink::Indicar se ocorrem condições de erro.

Como o retorno de chamada pode não ser retornado no mesmo nível de autenticação exigido pelo cliente, é recomendável que você use a comunicação semissíncrona em vez de assíncrona. Se você precisar de comunicação assíncrona, consulte Chamando um método.

Exemplos

O exemplo C++ a seguir mostra como implementar o método IWbemServices::ExecMethodAsync para o método Echo da classe TestMeth . A classe TestMeth dá suporte a um método que tem um parâmetro de entrada e um parâmetro de saída e que retorna um inteiro de 32 bits sem sinal. A implementação pressupõe que haja apenas um método chamado Echo e uma classe que o contenha. Para fins de brevidade, não há verificação de erros ou análise de caminho de objeto.

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;
}

Requisitos

Confira também

Como chamar um método

IWbemCallResult::GetResultObject

IWbemServices

IWbemServices::ExecMethodAsync