Compartilhar via

Função ExecQueryWmi

  • Artigo

Executa uma consulta para recuperar objetos.

Observação

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

Sintaxe

HRESULT ExecQueryWmi (
   [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 de sinalizadores que afetam o comportamento dessa função. Os seguintes 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_USE_AMENDED_QUALIFIERS 0x20000 Se definida, a função recuperará os qualificadores alterados armazenados no namespace localizado da localidade da conexão atual.
Se não estiver definida, a função recuperará apenas os qualificadores armazenados no namespace imediato.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 O sinalizador causa uma chamada de método semissíncrono.
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.
WBEM_FLAG_BIDIRECTIONAL 0 O WMI retém ponteiros para objetos na enumeração até que eles sejam lançados.
WBEM_FLAG_ENSURE_LOCATABLE 0x100 Garante que todos os objetos retornados tenham informações suficientes para que as propriedades do sistema, como __PATH, __RELPATH e __SERVER, não sejam null.
WBEM_FLAG_PROTOTYPE 2 Este sinalizador é usado para criação de protótipos. Ele não executa a consulta e, em vez disso, retorna um objeto que se parece com um objeto de resultado típico.
WBEM_FLAG_DIRECT_READ 0x200 Causa acesso direto ao provedor para a classe especificada sem considerar sua classe pai ou quaisquer subclasses.

Os sinalizadores recomendados são WBEM_FLAG_RETURN_IMMEDIATELY e WBEM_FLAG_FORWARD_ONLY para melhor desempenho.

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 as classes solicitadas.

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. A consulta pode ter um conjunto de resultados sem instâncias. 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_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_NOT_FOUND 0x80041002 A consulta especifica uma classe que não existe.
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::ExecQuery.

Essa função processa a consulta especificada no parâmetro strQuery e cria um enumerador por meio do qual o chamador pode acessar os resultados da consulta. O enumerador é um ponteiro para uma interface IEnumWbemClassObject. Os resultados da consulta são instâncias de objetos de classe disponibilizados por meio da interface IWbemClassObject.

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