Método SWbemServices.ExecMethodAsync
O método ExecMethodAsync do objeto SWbemServices executa um método 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. Informações e status são retornados ao chamador por meio de eventos entregues ao coletor especificado em objWbemSink. O provedor, em vez de Windows Instrumentação de Gerenciamento (WMI), implementa o método.
O método é chamado no modo assíncrono. Para obter mais informações, consulte Chamar um método.
Para obter mais informações e uma explicação dessa sintaxe, consulte Convenções de Documento para a API de Scripts.
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. Coletor de objetos que recebe o resultado da chamada do 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. Lembre-se de que SWbemSink.OnCompleted não recebe o código de retorno do método 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 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 é executado. Para obter mais informações, consulte Descrevendo o local de um objeto 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 executado. Por padrão, esse parâmetro é indefinido. Para obter mais informações, consulte 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 para o manipulador de eventos OnProgress para o coletor de objetos.
-
wbemFlagDontSendStatus (0 (0x0))
-
Impede que chamadas assíncronas enviem atualizações de status para o manipulador de eventos OnProgress para o coletor de objetos.
objWbemNamedValueSet [opcional]
Normalmente, isso é indefinido. Caso contrário, esse é 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 retorna ao coletor de objetos para identificar a origem da chamada assíncrona original. Use esse parâmetro se você 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 identifica a chamada assíncrona que você está fazendo. Esse objeto SWbemNamedValueSet é retornado ao coletor de objetos e a origem da chamada pode ser extraída usando o método SWbemNamedValueSet.Item . Para obter mais informações, consulte Como fazer uma chamada assíncrona com o VBScript.
Valor retornado
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 de retorno para o método que está sendo executado. Para obter mais informações, consulte Como construir objetos InParameters e analisar objetos OutParameters.
Códigos do Erro
Após a conclusão do método ExecMethodAsync , o objeto Err pode conter um dos códigos de erro listados 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)
-
Memória insuficiente 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 deverá ser o mesmo que a descrição nos tópicos Objetos InParameters de Construção e Análise de 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, use-o com uma linguagem de script que não dá suporte a 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, consulte Manipulando 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 retorna 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 objWbemSink. Evento 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, consulte Configurando 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á em execução Bloco de notas. Ele mostra a configuração de um objeto InParameters e como obter resultados de um objeto OutParameters . Para obter um script que mostra as mesmas operações executadas de forma síncrona, consulte SWbemServices.ExecMethod. Para obter um exemplo de como usar o acesso direto, consulte Criar Método na classe Win32_Process. Para obter um exemplo da mesma operação usando SWbemObject, consulte 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 |
|
Biblioteca de tipos |
|
DLL |
|
CLSID |
CLSID_SWbemServices |
IID |
IID_ISWbemServices |