Função ExecNotificationQueryWmi

Artigo
05/10/2023

Executa uma consulta para receber eventos. A chamada retorna imediatamente e o chamador pode sondar o enumerador retornado para eventos conforme eles chegam. A liberação do enumerador retornado cancela a consulta.

Observação

Esta API é somente para uso interno. Ela não é destinada ao uso do código do desenvolvedor.

Sintaxe

HRESULT ExecNotificationQueryWmi (
   [in] BSTR                    strQueryLanguage,
   [in] BSTR                    strQuery,
   [in] long                    lFlags,
   [in] IWbemContext*           pCtx,
   [out] IEnumWbemClassObject** ppEnum,
   [in] DWORD                   authLevel,
   [in] DWORD                   impLevel,
   [in] IWbemServices*          pCurrentNamespace,
   [in] BSTR                    strUser,
   [in] BSTR                    strPassword,
   [in] BSTR                    strAuthority
);

Parâmetros

strQueryLanguage
[in] Uma cadeia de caracteres com a linguagem de consulta válida compatível com o Gerenciamento do Windows. Ela deve ter "WQL", o acrônimo para a linguagem de consulta WMI.

strQuery
[in] O texto da consulta. O parâmetro não pode ser null.

lFlags
[in] Uma combinação dos dois sinalizadores a seguir que afetam o comportamento dessa função. Esses valores são definidos no arquivo de cabeçalho WbemCli.h ou você pode defini-los como constantes em seu código.

Constante	Valor	Descrição
`WBEM_FLAG_RETURN_IMMEDIATELY`	0x10	O sinalizador causa uma chamada de método semissíncrono. Se esse sinalizador não estiver definido, a chamada falhará. Isso ocorre porque os eventos são recebidos continuamente, o que significa que o usuário deve sondar o enumerador retornado. Bloquear essa chamada indefinidamente torna isso impossível.
`WBEM_FLAG_FORWARD_ONLY`	0x20	A função retorna um enumerador apenas para encaminhamento. Normalmente, os enumeradores apenas para encaminhamento são mais rápidos e usam menos memória do que os enumeradores convencionais, mas eles não permitem chamadas para Clonar.

pCtx
[in] Normalmente, esse valor é null. Caso contrário, ele é um ponteiro para uma instância IWbemContext que pode ser usada pelo provedor que está fornecendo os eventos solicitados.

ppEnum
[out] Se nenhum erro ocorrer, receberá o ponteiro para o enumerador que permite que o chamador recupere as instâncias no conjunto de resultados da consulta. Consulte a seção Comentários para obter mais informações.

authLevel
[in] O nível de autorização.

impLevel
[in] O nível de representação.

pCurrentNamespace
[in] Um ponteiro para um objeto IWbemServices que representa o namespace atual.

strUser
[in] O nome do usuário. Confira a função ConnectServerWmi para obter mais informações.

strPassword
[in] A senha. Confira a função ConnectServerWmi para obter mais informações.

strAuthority
[in] O nome de domínio do usuário. Confira a função ConnectServerWmi para obter mais informações.

Valor retornado

Os seguintes valores retornados por essa função são definidos no arquivo de cabeçalho WbemCli.h, ou você pode defini-los como constantes em seu código:

Constante	Valor	Descrição
`WBEM_E_ACCESS_DENIED`	0x80041003	O usuário não tem permissão para exibir uma ou mais das classes que a função pode retornar.
`WBEM_E_FAILED`	0x80041001	Ocorreu um erro não especificado.
`WBEM_E_INVALID_PARAMETER`	0x80041008	Um parâmetro não é válido.
`WBEM_E_INVALID_CLASS`	0x80041010	A consulta especifica uma classe que não existe.
`WBEMESS_E_REGISTRATION_TOO_PRECISE`	0x80042002	Muita precisão na entrega de eventos foi solicitada. Uma tolerância maior à sondagem deve ser especificada.
`WBEMESS_E_REGISTRATION_TOO_BROAD`	0x80042001	A consulta solicita mais informações do que o Gerenciamento do Windows pode fornecer. Esse `HRESULT` é retornado quando uma consulta de evento resulta em uma solicitação para sondar todos os objetos em um namespace.
`WBEM_E_INVALID_QUERY`	0x80041017	A consulta teve um erro de sintaxe.
`WBEM_E_INVALID_QUERY_TYPE`	0x80041018	O idioma de consulta solicitado não tem suporte.
`WBEM_E_QUOTA_VIOLATION`	0x8004106c	A consulta é muito complexa.
`WBEM_E_OUT_OF_MEMORY`	0x80041006	Não há memória disponível suficiente para concluir a operação.
`WBEM_E_SHUTTING_DOWN`	0x80041033	O WMI provavelmente foi interrompido e reiniciado. Chame ConnectServerWmi novamente.
`WBEM_E_TRANSPORT_FAILURE`	0x80041015	Falha no link da RPC (chamada de procedimento remoto) entre o processo atual e o WMI.
`WBEM_E_UNPARSABLE_QUERY`	0x80041058	A consulta não pode ser analisada.
`WBEM_S_NO_ERROR`	0	A chamada de função foi bem-sucedida.

Comentários

Essa função faz o encapsulamento de uma chamada para o método IWbemServices::ExecNotificationQuery.

Depois que a função é retornada, o chamador passa periodicamente o objeto ppEnum retornado para a função Next para ver se algum evento está disponível.

Existem limites para o número de palavras-chave AND e OR que podem ser usadas em 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 (ou 0x8004106c) como um valor HRESULT. O limite de palavras-chave WQL depende da complexidade da consulta.

Se a chamada de função falhar, você pode obter informações de erro adicionais chamando a função GetErrorInfo.

Requisitos

Plataformas: confira Requisitos do sistema.

Header: WMINet_Utils.idl

Versões do .NET Framework: Disponível desde 4.7.2

Confira também

WMI e Contadores de Desempenho (Referência de API Não Gerenciada)

Compartilhar via