Função GetNames

Artigo
05/10/2023

Recupera um subconjunto ou todos os nomes das propriedades de um objeto.

Observação

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

Sintaxe

HRESULT GetNames (
   [in] int                 vFunc,
   [in] IWbemClassObject*   ptr,
   [in] LPCWSTR             wszQualifierName,
   [in] LONG                lFlags,
   [in] VARIANT*            pQualifierValue,
   [out] SAFEARRAY (BSTR)** pstrNames
);

Parâmetros

vFunc
[in] Esse parâmetro não está em uso.

ptr
[in] Um ponteiro para uma instância IWbemClassObject.

wszQualifierName
[in] Um ponteiro para um LPCWSTR válido que especifica um nome qualificador que opera como parte de um filtro. Para obter mais informações, consulte a seção Comentários. Esse parâmetro pode ser null.

lFlags
[in] Uma combinação de campos de bits. Para obter mais informações, consulte a seção Comentários.

pQualifierValue [in] Um ponteiro para uma estrutura válida VARIANT inicializada para um valor de filtro. Esse parâmetro pode ser null.

pstrNames
[out] Uma estrutura SAFEARRAY que contém nomes de propriedade. Na entrada, esse parâmetro deve ser sempre um ponteiro para null. Consulte a seção Comentários 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_FAILED`	0x80041001	Houve uma falha geral.
`WBEM_E_INVALID_PARAMETER`	0x80041008	Um ou mais parâmetros não são válidos ou uma combinação incorreta de sinalizadores e parâmetros foi especificada.
`WBEM_E_OUT_OF_MEMORY`	0x80041006	Não há memória disponível suficiente para concluir a operação.
`WBEM_S_NO_ERROR`	0	A chamada de função foi bem-sucedida.

Comentários

Essa função encapsula uma chamada para o método IWbemClassObject::GetNames.

Os nomeados retornados são controlados por uma combinação de sinalizadores e parâmetros. Por exemplo, a função pode retornar os nomes de todas as propriedades ou apenas os nomes das propriedades da chave. O filtro primário é especificado no parâmetro lFlags e os outros parâmetros variam dependendo dele.

Os valores de sinalizador em lFlags são campos de bit

Os sinalizadores que podem ser passados como o argumento lEnumFlags são são campos de bit definidos no arquivo de cabeçalho WbemCli.h ou você pode defini-los como constantes em seu código. Você pode combinar um sinalizador de cada grupo com qualquer sinalizador de qualquer outro grupo. No entanto, os sinalizadores do mesmo grupo são mutuamente exclusivos.

Sinalizadores do grupo 1	Valor	Descrição
`WBEM_FLAG_ALWAYS`	0	Retornar todos os nomes de propriedade. `strQualifierName` e `pQualifierVal` não são utilizados.
`WBEM_FLAG_ONLY_IF_TRUE`	1	Retornam somente propriedades que tenham um qualificador do nome especificado pelo parâmetro `strQualifierName`. Se esse sinalizador for usado, você deverá especificar `strQualifierName`.
`WBEM_FLAG_ONLY_IF_FALSE`	2	Retornam somente propriedades que não tenham um qualificador do nome especificado pelo parâmetro `strQualifierName`. Se esse sinalizador for usado, você deverá especificar `strQualifierName`.
`WBEM_FLAG_ONLY_IF_IDENTICAL`	3	Retornam somente propriedades que têm um qualificador do nome especificado pelo parâmetro `wszQualifierName` e também têm um valor idêntico ao especificado pela estrutura `pQualifierVal`. Se esse sinalizador for usado, você deverá especificar um `wszQualifierName` e um `pQualifierValue`.

Sinalizadores do grupo 2	Valor	Descrição
`WBEM_FLAG_KEYS_ONLY`	0x4	Retornam apenas os nomes das propriedades que definem as chaves.
`WBEM_FLAG_REFS_ONLY`	0x8	Retornam apenas nomes de propriedade que são referências de objeto.

Sinalizadores do grupo 3	Valor	Descrição
`WBEM_FLAG_LOCAL_ONLY`	0x10	Retornam apenas nomes de propriedade que pertencem à classe mais derivada. Excluem propriedades das classes pai.
`WBEM_FLAG_PROPAGATED_ONLY`	0x20	Retornam apenas nomes de propriedade que pertencem às classes pai.
`WBEM_FLAG_SYSTEM_ONLY`	0x30	Retornam somente os nomes das propriedades do sistema.
`WBEM_FLAG_NONSYSTEM_ONLY`	0x40	Retornam somente os nomes das propriedades que não são do sistema.

A função sempre aloca um novo SAFEARRAY se retornar WBEM_S_NO_ERROR, e pstrNames sempre é definida para apontar para ela. A matriz retornada poderá ter 0 elementos se nenhuma propriedade corresponder aos filtros especificados. Se a função retornar um valor diferente de WBM_S_NO_ERROR, uma nova estrutura SAFEARRAY não será retornada.

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