Função GetNames

  • Artigo

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