Método SWbemServices.ExecNotificationQueryAsync
O método ExecNotificationQueryAsync do objeto SWbemServices executa uma consulta para receber eventos. Essa chamada retorna imediatamente e os resultados e o status são retornados ao chamador por meio de eventos entregues ao coletor especificado no objWbemSink.
Os eventos especificados na consulta podem ser eventos intrínsecos da WMI (Instrumentação de Gerenciamento do Windows), como __InstanceCreationEvent ou eventos extrínsecos, como Win32_IP4RouteTableEvent ou RegistryKeyChangeEvent. Para obter mais informações, confira Determinar o tipo de evento a receber.
O método é chamado no modo assíncrono. Para obter mais informações, confira Como chamar um método.
Para conferir uma explicação dessa sintaxe, confira Convenções de documentação para API de script.
Sintaxe
SWbemServices.ExecNotificationQueryAsync( _
ByVal objWbemSink, _
ByVal strQuery, _
[ ByVal strQueryLanguage ], _
[ ByVal iFlags ], _
[ ByVal objwbemNamedValueSet ], _
[ ByVal objWbemAsyncContext ] _
)
Parâmetros
-
objWbemSink
-
Obrigatórios. Coletor de objetos que recebe a notificação de eventos de maneira assíncrona. Crie um objeto SWbemSink para receber os objetos.
-
strQuery
-
Obrigatórios. Cadeia de caracteres que contém o texto da consulta relacionada a eventos. Este parâmetro não pode ficar em branco. Para obter mais informações sobre como criar cadeias de caracteres de consulta do WMI, veja Como consultar com WQL e a referência da WQL.
-
strQueryLanguage [opcional]
-
Cadeia de caracteres que contém a linguagem de consulta a ser usada. Se especificado, esse valor deverá ser "WQL".
-
iFlags [opcional]
-
Inteiro que determina o comportamento da consulta. Este parâmetro pode ser definido como 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 atende à 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]
Este é um objeto SWbemNamedValueSet que é retornado ao coletor de objetos para identificar a origem da chamada assíncrona original. Utilize esse parâmetro para fazer 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. O 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 Chamar um método.
Retornar valor
Esse método não retorna um valor. Se tiver êxito, o coletor receberá um evento OnObjectReady por instância. Após a última instância, o coletor de objetos receberá um evento OnCompleted.
Códigos do Erro
Após a conclusão do método ExecNotificationQueryAsync, o objeto Err pode conter um dos códigos de erro identificados na lista a seguir.
-
wbemErrAccessDenied – 2147749891 (0x80041003)
-
O usuário atual não está autorizado a exibir o conjunto de resultados.
-
wbemErrFailed – 2147749889 (0x80041001)
-
Erro não especificado.
-
wbemErrInvalidParameter – 2147749896 (0x80041008)
-
Parâmetro inválido especificado.
-
wbemErrInvalidQuery – 2147749911 (0x80041017)
-
A sintaxe da consulta não é válida.
-
wbemErrInvalidQueryType - 2147749912 (0x80041018)
-
Não há suporte para a linguagem de consulta solicitada.
-
wbemErrOutOfMemory – 2147749894 (0x80041006)
-
Não há memória suficiente para concluir a operação.
Comentários
O método ExecNotificationQueryAsync retorna objetos de tipo de evento gerados por eventos futuros. Os objetos de evento que ExecNotificationQueryAsync solicita podem ser intrínsecos (por exemplo, __InstanceCreationEvent) ou extrínsecos (por exemplo, RegistryKeyChangeEvent ou eventos do SNMP). Para obter mais informações, confira Determinar o tipo de evento a receber.
A chamada para ExecNotificationQueryAsync retorna imediatamente. Os objetos solicitados e o status são retornados ao chamador por meio de retornos de chamada entregues ao coletor especificado no objWbemSink. Para processar cada objeto quando ele é retornado, crie uma sub-rotina de evento objWbemSink.OnObjectReady. Depois que todos os objetos forem retornados, execute o processamento final para implementar 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 eliminar os riscos, consulte Configurar a segurança em uma chamada assíncrona.
Existem limites no número de palavras-chave AND e OR que podem ser usadas nas consultas WQL. Um grande número de palavras-chave da WQL usadas em uma consulta complexa pode fazer com que o WMI retorne o código de erro WBEM_E_QUOTA_VIOLATION como um valor HRESULT. O limite de palavras-chave WQL depende da complexidade da consulta.
Exemplos
O exemplo de código VBScript a seguir mostra um script que está aguardando uma notificação de evento do WMI que indica que um processo foi encerrado. Ele está aguardando um evento intrínseco do WMI, uma instância da classe de evento __InstanceDeletionEvent. O __InstanceDeletionEvent deve representar a exclusão de uma instância de Win32_Process. Para obter mais informações sobre eventos intrínsecos do WMI, confira Determinar o tipo de evento a ser recebido.
O script a seguir é executado indefinidamente até que o computador seja reinicializado, o WMI seja interrompido ou o script seja parado. Para interromper o script manualmente, use o Gerenciador de Tarefas e pare o processo. Para interrompê-lo programaticamente, use o método Terminate na classe Win32_Process.
strComputer = "."
Set objWMIService = GetObject("winmgmts:\\" & _strComputer & "\root\CIMV2")
Set MySink = WScript.CreateObject("WbemScripting.SWbemSink","SINK_")
objWMIservice.ExecNotificationQueryAsync MySink, "SELECT * FROM __InstanceCreationEvent WITHIN 1 " _
& "WHERE TargetInstance ISA 'Win32_Process'"
WScript.Echo "Waiting for events..."
While (True)
Wscript.Sleep(1000)
Wend
Sub SINK_OnObjectReady(objObject, objAsyncContext)
WScript.Echo "Event occurred."
End Sub
Sub SINK_OnCompleted(objObject, objAsyncContext)
WScript.Echo "Event call complete."
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 |