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

O método IWbemServices::CreateInstanceEnum cria um enumerador que retorna as instâncias de uma classe especificada de acordo com os critérios de seleção especificados pelo usuário. Esse método dá suporte a consultas WQL simples; consultas mais complexas podem ser processadas usando o método IWbemServices::ExecQuery .

Sintaxe

HRESULT CreateInstanceEnum(
  [in]  const BSTR           strFilter,
  [in]  long                 lFlags,
  [in]  IWbemContext         *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Parâmetros

[in] strFilter

BSTR válido que contém o nome da classe para a qual as instâncias são desejadas. Esse parâmetro não pode ser NULL.

[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 estiver 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_DEEP

Esse sinalizador força a enumeração a incluir essa e todas as subclasses na hierarquia.

WBEM_FLAG_SHALLOW

Esse sinalizador força a enumeração a incluir apenas instâncias puras dessa classe, excluindo todas as instâncias de subclasses que fornecem propriedades não encontradas nessa classe.

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_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. Como os ponteiros de objeto não são liberados imediatamente, esse método pode falhar com um hResult de WBEM_E_OUT_OF_MEMORY se o cliente tentar enumerar um grande número de objetos. Esse sinalizador será implícito por padrão se você definir o parâmetro lFlags como 0 (zero).

WBEM_FLAG_DIRECT_READ

Esse sinalizador faz com que o 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 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

Recebe o ponteiro para o enumerador, que tem uma contagem de referência positiva. O chamador deve chamar IUnknown::Release no ponteiro depois que ele 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 de COM também podem ser retornados se problemas de rede fizerem com que você perca a conexão remota com o Gerenciamento do Windows.

Comentários

Não é um erro para o enumerador retornado ter zero elementos.

Requisitos

Confira também

IWbemServices

IWbemServices::CreateInstanceEnumAsync

Como recuperar um código de erro