Método SWbemServices.ExecQueryAsync
O método ExecQueryAsync do objeto SWbemServices executa uma consulta para recuperar objetos. A chamada para esse método retorna imediatamente e os resultados e o status são retornados ao chamador por meio de eventos entregues ao coletor especificado no objWbemSink. Para lidar com cada objeto retornado, crie uma sub-rotina de evento objWbemSink.OnObjectReady.
O método é chamado no modo semissí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
objWbemObjectSet = .ExecQueryAsync( _
[ ByVal objWbemSink ], _
ByVal strQuery, _
[ ByVal strQueryLanguage ], _
[ ByVal iFlags ], _
[ ByVal objwbemNamedValueSet ], _
[ ByVal objWbemAsyncContext ] _
)
Parâmetros
-
objWbemSink [opcional]
-
Coletor de objeto que executa a consulta de forma assíncrona. Crie um objeto SWbemSink para receber os objetos.
-
strQuery
-
Obrigatórios. Cadeia de caracteres que contém o texto da consulta. 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, o valor deverá ser "WQL".
-
iFlags [opcional]
-
Inteiro que determina o comportamento da consulta. 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 para o coletor de objetos.
-
wbemQueryFlagPrototype (2 (0x2))
-
Usado para um protótipo. Isso impede a execução da consulta e, em vez disso, retorna um objeto que se assemelha a um objeto de resultado típico.
-
wbemFlagUseAmendedQualifiers (131072 (0x20000))
-
Faz com que o WMI retorne dados de aditamento da classe com a definição da classe base. Para obter mais informações, consulte Localizar informações de classe WMI.
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 informações de contexto 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. 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. 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, confira Como chamar um método.
Retornar valor
Esse método não tem valores retornados. 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 ExecQueryAsync, o objeto Err pode conter um dos códigos de erro da lista a seguir.
-
wbemErrAccessDenied – 2147749891 (0x80041003)
-
O usuário atual não tem permissão para exibir o conjunto de resultados.
-
wbemErrFailed – 2147749889 (0x80041001)
-
Erro não especificado.
-
wbemErrInvalidParameter – 2147749896 (0x80041008)
-
Foi especificado um parâmetro inválido.
-
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
Essa chamada é retornada 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 retornar, crie uma sub-rotina de evento objWbemSink.OnObjectReady. Depois que todos os objetos forem retornados, execute o processamento final na implementação do 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
O método ExecQueryAsync retorna um conjunto de resultados vazio quando não há objetos que correspondam aos critérios na consulta. Esse método retorna as propriedades de chave independentemente de a propriedade Key ser solicitada ou não no parâmetro strQuery.
Existem limites para o número das palavras-chave AND e OR que podem ser usadas nas consultas WQL. Um grande número de palavras-chave 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.
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 |