Método IWbemServices::ExecQuery (wbemcli.h)

O método IWbemServices::ExecQuery executa uma consulta para recuperar objetos.

Para obter os tipos válidos de consultas que podem ser executadas, consulte Consultando com WQL.

Sintaxe

HRESULT ExecQuery(
  [in]  const BSTR           strQueryLanguage,
  [in]  const BSTR           strQuery,
  [in]  long                 lFlags,
  [in]  IWbemContext         *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parâmetros

[in] strQueryLanguage

BSTR válido que contém um dos idiomas de consulta compatíveis com o Gerenciamento do Windows. Deve ser "WQL", o acrônimo para Linguagem de Consulta WMI.

[in] strQuery

BSTR válido que contém o texto da consulta. Esse parâmetro não pode ser NULL. 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.

[in] lFlags

Os sinalizadores a seguir afetam o comportamento desse método. O valor sugerido para esse parâmetro é WBEM_FLAG_RETURN_IMMEDIATELY e WBEM_FLAG_FORWARD_ONLY para melhor desempenho.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se esse sinalizador for definido, o WMI recuperará os qualificadores alterados armazenados no namespace localizado da localidade da conexão atual. Se não estiver definido, somente os qualificadores armazenados no namespace imediato serão recuperados.

WBEM_FLAG_FORWARD_ONLY

Esse sinalizador faz com que um enumerador somente de encaminhamento seja retornado. Os enumeradores somente de encaminhamento geralmente são muito mais rápidos e usam menos memória do que os enumeradores convencionais, mas não permitem chamadas para Clonar ou Redefinir.

WBEM_FLAG_BIDIRECTIONAL

Esse sinalizador faz com que o Gerenciamento do Windows mantenha ponteiros para objetos da enumeração até que o cliente libere o enumerador.

WBEM_FLAG_RETURN_IMMEDIATELY

Esse sinalizador faz com que essa seja uma chamada semissíncrona. Para obter mais informações, confira Como chamar um método.

WBEM_FLAG_ENSURE_LOCATABLE

Esse sinalizador 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

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

Esse sinalizador causa acesso direto ao provedor para a classe especificada sem qualquer relação com sua classe pai ou subclasses.

[in] pCtx

Normalmente NULL. Caso contrário, esse é um ponteiro para um objeto IWbemContext que pode ser usado pelo provedor que está fornecendo as classes ou instâncias solicitadas. Os valores no objeto de contexto devem ser especificados na documentação do provedor em questão. Para obter mais informações sobre esse parâmetro, consulte Fazendo chamadas para WMI.

[out] ppEnum

Se nenhum erro ocorrer, isso receberá o enumerador que permite que o chamador recupere as instâncias no conjunto de resultados da consulta. Não é um erro a consulta ter um conjunto de resultados com 0 instâncias. Isso é determinado apenas pela tentativa de iterar por meio das instâncias. Esse objeto retorna com uma contagem de referência positiva. O chamador deve chamar Release quando o objeto não for mais necessário.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista o valor contido em um HRESULT.

Em caso de falha, você pode obter todas as informações disponíveis da função COM GetErrorInfo.

Códigos de erro específicos do COM também poderão ser retornados se problemas de rede fizerem com que você perca a conexão remota com o Gerenciamento do Windows.

Comentários

O método IWbemServices::ExecQuery 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.

Há 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 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.

Requisitos

Confira também

IWbemServices

IWbemServices::ExecQueryAsync

Como consultar com WQL