Método SWbemServices.ExecMethodAsync

O método ExecMethodAsync do objeto SWbemServices executa um método que é exportado por um provedor de métodos. A chamada retorna imediatamente ao cliente, enquanto os parâmetros de entrada são encaminhados para o provedor apropriado em que o método é executado. As informações e o status são retornados ao chamador por meio de eventos entregues ao coletor especificado no objWbemSink. O provedor, em vez do WMI (Instrumentação de Gerenciamento do Windows), implementa o método.

O método é chamado no modo assíncrono. Para obter mais informações, confira Como chamar um método.

Para obter mais informações e uma explicação dessa sintaxe, confira Convenções de documentação para a API de Script.

Sintaxe

SWbemServices.ExecMethodAsync( _
  ByVal objWbemSink, _
  ByVal strObjectPath, _
  ByVal strMethodName, _
  [ ByVal objWbemInParams ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parâmetros

objWbemSink

Obrigatórios. Crie um objeto SWbemSink para receber os objetos. O coletor de objeto que recebe o resultado da chamada de método. Os parâmetros de saída são enviados para o evento SWbemSink.OnObjectReady do coletor de objeto fornecido. Os resultados do mecanismo de chamada são enviados para o evento SWbemSink.OnCompleted do coletor de objeto fornecido. Esteja ciente de que SWbemSink.OnCompleted não recebe o código de retorno do método do WMI. No entanto, ele recebe o código de retorno do mecanismo de retorno de chamada real e só é útil para verificar se a chamada ocorreu ou se ela falhou por motivos mecânicos. O código de resultado retornado do método do WMI é retornado no objeto de parâmetro de saída fornecido a SWbemSink.OnObjectReady. Se algum código de erro for retornado, o objeto IWbemObjectSink fornecido não será usado. Se a chamada for bem-sucedida, a implementação IWbemObjectSink do usuário será chamada para indicar o resultado da operação.

strObjectPath

Obrigatórios. Uma cadeia de caracteres que contém o caminho do objeto para o qual o método será executado. Para obter mais informações, confira Como descrever o local de um objeto do WMI.

strMethodName

Obrigatórios. O nome do método a ser executado.

objWbemInParams [opcional]

Um objeto SWbemObject que contém os parâmetros de entrada para o método que está sendo executado. Por padrão, esse parâmetro é indefinido. Para obter mais informações, confira Como construir objetos InParameters e Analisar objetos OutParameters.

iFlags [opcional]

Inteiro que determina o comportamento da chamada. Esse parâmetro pode aceitar os valores a seguir.

wbemFlagSendStatus (128 (0x80))

Faz com que chamadas assíncronas enviem atualizações de status ao manipulador de eventos OnProgress para o coletor de objetos.

wbemFlagDontSendStatus (0 (0x0))

Evita que chamadas assíncronas enviem atualizações de status ao manipulador de eventos OnProgress do coletor de objetos.

objWbemNamedValueSet [opcional]

Normalmente, isso é indefinido. Caso contrário, esse será um objeto SWbemNamedValueSet cujos elementos representam as informações de contexto que podem ser usadas pelo provedor que está atendendo à solicitação. Um provedor que dê suporte ou exija essas informações deve documentar os nomes de valor reconhecidos, o tipo de dados do valor, os valores permitidos e a semântica.

objWbemAsyncContext [opcional]

Um objeto SWbemNamedValueSet que é retornado ao coletor de objetos para identificar a origem da chamada assíncrona original. Use esse parâmetro se estiver fazendo várias chamadas assíncronas usando o mesmo coletor de objetos. Para usar esse parâmetro, crie um objeto SWbemNamedValueSet e use o método SWbemNamedValueSet.Add para adicionar um valor que identifique a chamada assíncrona que você está fazendo. Esse objeto SWbemNamedValueSet é retornado ao coletor de objeto, e a origem da chamada pode ser extraída usando o método SWbemNamedValueSet.Item. Para saber mais, confira Como fazer uma chamada assíncrona com VBScript.

Retornar valor

Esse método não retorna um valor. Se a chamada for bem-sucedida, um objeto OutParameters, que também é um SWbemObject, será fornecido ao coletor especificado em objWbemSink. O objeto OutParameters retornado contém os parâmetros de saída e o valor retornado para o método que está sendo executado. Para obter mais informações, confira Como construir objetos InParameters e Analisar objetos OutParameters.

Códigos do Erro

Após a conclusão do método ExecMethodAsync_, o objeto Err poderá conter um dos códigos de erro encontrados na lista a seguir.

wbemErrFailed – 2147749889 (0x80041001)

Erro não especificado.

wbemErrInvalidClass – 2147749904 (0x80041010)

A classe especificada não era válida.

wbemErrInvalidParameter – 2147749896 (0x80041008)

Um parâmetro especificado não é válido.

wbemErrOutOfMemory – 2147749894 (0x80041006)

Não há memória suficiente para concluir a operação.

wbemErrInvalidMethod – 2147749934 (0x8004102E)

O método solicitado não estava disponível.

wbemErrAccessDenied – 2147749891 (0x80041003)

O usuário atual não estava autorizado a executar o método.

Comentários

Se o método executado tiver parâmetros de entrada, o objeto InParameters no parâmetro objWbemInParam deve ser o mesmo descrito nos tópicos Como construir objetos InParameters e Como analisar objetos OutParameters.

Use SWbemServices.ExecMethodAsync como uma alternativa ao acesso direto para executar um método de provedor quando não for possível executar um método diretamente. Por exemplo, você usaria isso com uma linguagem de script que não dá suporte para parâmetros de saída, ou seja, se o método tiver parâmetros OUT. Caso contrário, é recomendável que você use o acesso direto para invocar um método. Para obter mais informações, confira Como manipular informações de classe e instância.

O método SWbemServices.ExecMethodAsync requer um caminho de objeto. Se o script já contiver um objeto SWbemObject, você poderá chamar SWbemObject.ExecMethodAsync.

Essa chamada é retornada imediatamente. As informações de status são retornadas ao chamador por meio de retornos de chamada entregues ao coletor especificado em objWbemSink. Para continuar o processamento quando a chamada for concluída, implemente uma sub-rotina para o evento objWbemSink.OnCompleted.

Um retorno de chamada assíncrono permite que um usuário não autenticado forneça dados ao coletor. Isso representa riscos de segurança para seus scripts e aplicativos. Para obter mais informações sobre como eliminar os riscos, confira Como configurar a segurança em uma chamada assíncrona.

Use o parâmetro objWbemAsyncContext para verificar a origem de uma chamada.

Exemplos

O exemplo de código a seguir mostra o método ExecMethodAsync. O script cria um objeto Win32_Process que representa um processo que está executando o Bloco de notas. Ele mostra a configuração de um objeto InParameters e como obter resultados de um objeto OutParameters. Para ver um script que mostra as mesmas operações executadas de maneira síncrona, confira SWbemServices.ExecMethod. Para ver um exemplo de como usar o acesso direto, confira Criar método na classe Win32_Process. Para ver um exemplo da mesma operação usando SWbemObject, veja SWbemObject.ExecMethodAsync.

' Connect to WMI.
set Services = getobject("winmgmts:root\cimv2")

' Obtain the class definition object
' of a Win32_Process object.
Set oProcess = Services.Get("Win32_Process")

' Create the SWbemMethod.InParameters object
' to hold the input parameter required
' for the Win32_Process.Create method call.
' The oProcess.Methods_("Create") call
' obtains a class object that defines
' the correct input parameters
' for the Win32_Process.Create call.
' The InParameters object is an 
' SWbemObject object, so SWbemObject.SpawnInstance_ 
' can be called to create it.

Set oInParams = oProcess.Methods_("Create"). _
    InParameters.SpawnInstance_
oInParams.CommandLine = "Notepad.exe"

' Create sink to receive event resulting
' from the ExecMethodAsync call.
set Sink = wscript.CreateObject( _
    "WbemScripting.SWbemSink","Sink_")

' Call SWbemServices.ExecMethodAsync
' with the WMI path Win32_Process.

bDone = false
Services.ExecMethodAsync Sink, _
     "Win32_Process", "Create", oInParams

' Call the Win32_Process.Create method asynchronously.
' Set up a wait so the results of the method
' execution can be returned to 
' the sink subroutines.

while not bDone    
    wscript.sleep 1000  
wend

' Sink subroutines
sub Sink_OnObjectReady(oOutParams, oContext)
    wscript.echo "Sink_OnObjectReady subroutine " _ 
        &VBCR & "ReturnValue = " _
        & oOutParams.ReturnValue &VBCR & _
        "ProcessId = " & oOutParams.ProcessId
end sub

sub Sink_OnCompleted(HResult, LastErrorObj, oContext)
    wscript.echo "Sink_OnCompleted subroutine, hresult = " _
        & hex(HResult)
    bdone = true
end sub

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Cabeçalho	Wbemdisp.h
Biblioteca de tipos	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemServices
IID	IID_ISWbemServices

Confira também

SWbemServices

SWbemObject.ExecMethod_

SWbemObject.ExecMethodAsync_

SWbemServices.ExecMethod

Como chamar um método de provedor

Como manipular informações de classe e instância