Função CreateInstanceEnumWmi

Artigo
05/10/2023

Retorna um enumerador que retorna as instâncias de uma classe especificada que atendem aos critérios de seleção selecionados.

Observação

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

Sintaxe

HRESULT CreateInstanceEnumWmi (
   [in] BSTR                    strFilter,
   [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

strFilter
[in] O nome da classe para a qual as instâncias são desejadas. 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_DEEP`	0	A enumeração inclui essa e todas as subclasses na hierarquia.
`WBEM_FLAG_SHALLOW`	1	A enumeração inclui apenas instâncias puras dessa classe e exclui todas as instâncias de subclasses que fornecem propriedades não encontradas nessa classe.
`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.

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 instâncias solicitadas.

ppEnum
[out] Recebe o ponteiro para o enumerador.

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 ver instâncias da classe especificada.
`WBEM_E_FAILED`	0x80041001	Ocorreu um erro não especificado.
`WBEM_E_INVALID_CLASS`	0x80041010	`strFilter` não existe.
`WBEM_E_INVALID_PARAMETER`	0x80041008	Um parâmetro não é válido.
`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_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::CreateClassEnum.

Observe que o enumerador retornado pode ter zero elementos.

Se a chamada de função falhar, você poderá obter informações de erro adicionais se chamar 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