Compartir a través de

Función GetNames

  • Artículo

Recupera un subconjunto o todos los nombres de las propiedades de un objeto.

Nota

Esta API es solo para uso interno. No está pensada para usarla desde código del desarrollador.

Sintaxis

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] Este parámetro no se usa.

ptr
[in] El valor de este parámetro se corresponde con un puntero que apunta a una instancia de la interfaz IWbemClassObject.

wszQualifierName
[in] El valor de este parámetro se corresponde con un puntero que apunta a un valor LPCWSTR válido donde se especifica un nombre de calificador, que se usa como parte de un filtro. Para más información, vea la sección Comentarios. Este parámetro puede ser null.

lFlags
[in] El valor de este parámetro se corresponde con una combinación de campos de bits. Para más información, vea la sección Comentarios.

pQualifierValue [in] El valor de este parámetro se corresponde con un puntero que apunta a una estructura VARIANT válida que se inicializa en un valor de filtro. Este parámetro puede ser null.

pstrNames
[out] El valor de este parámetro se corresponde con una estructura SAFEARRAY donde se incluyen nombres de propiedad. En la entrada de esta función, este parámetro siempre debe ser un puntero que apunte a un valor null. Consulte la sección Comentarios para obtener más información.

Valor devuelto

Los siguientes valores que devuelve esta función se definen en el archivo de encabezado WbemCli.h, aunque también puede definirlos como constantes en el código. Puede consultarlos a continuación:

Constante Value Descripción
WBEM_E_FAILED 0x80041001 Si se devuelve este valor, significará que se ha producido un error general.
WBEM_E_INVALID_PARAMETER 0x80041008 Si se devuelve este valor, significará que uno o varios parámetros no fueron válidos o que se especificó una combinación incorrecta de marcas y parámetros.
WBEM_E_OUT_OF_MEMORY 0x80041006 Memoria insuficiente para completar la operación.
WBEM_S_NO_ERROR 0 Si se devuelve este valor, significará que la llamada a la función se realizó correctamente.

Comentarios

Al usar esta función, se ajusta una llamada al método IWbemClassObject::GetNames.

Para controlar los nombres que se devuelven, se usa una combinación de marcas y parámetros. Por ejemplo, la función puede devolver los nombres de todas las propiedades o tan solo los de las propiedades de clave. El filtro principal se especifica en el parámetro lFlags y los demás parámetros varían en función de este.

Los valores de marca del parámetro lFlags son campos de bits.

Las marcas que se pueden pasar en el argumento lEnumFlags constituyen campos de bits que se definen en el archivo de encabezado WbemCli.h, aunque también puede definirlas como constantes en el código. Puede combinar una marca de cada grupo con cualquier marca de cualquier otro grupo. Sin embargo, no es posible combinar marcas que pertenezcan a un mismo grupo.

Marcas del grupo 1 Valor Descripción
WBEM_FLAG_ALWAYS 0 Este valor se usa para obtener todos los nombres de propiedad. En este caso, los valores strQualifierName y pQualifierVal no se usan.
WBEM_FLAG_ONLY_IF_TRUE 1 Este valor se usa para obtener únicamente las propiedades que tengan un calificador del nombre que se especifique en el parámetro strQualifierName. Si se usa esta marca, deberá especificarse el valor strQualifierName.
WBEM_FLAG_ONLY_IF_FALSE 2 Este valor se usa para obtener únicamente las propiedades que no tengan un calificador del nombre que se especifique en el parámetro strQualifierName. Si se usa esta marca, deberá especificarse el valor strQualifierName.
WBEM_FLAG_ONLY_IF_IDENTICAL 3 Este valor se usa para obtener únicamente las propiedades que tengan un calificador del nombre que se especifique en el parámetro wszQualifierName y también tengan un valor idéntico al que se especifica en la estructura pQualifierVal. Si se usa esta marca, deberán especificarse los valores wszQualifierName y pQualifierValue.
Marcas del grupo 2 Valor Descripción
WBEM_FLAG_KEYS_ONLY 0x4 Este valor se usa para obtener únicamente los nombres de las propiedades en las que se definen las claves.
WBEM_FLAG_REFS_ONLY 0x8 Este valor se usa para obtener únicamente los nombres de propiedad que constituyan referencias de objeto.
Marcas del grupo 3 Valor Descripción
WBEM_FLAG_LOCAL_ONLY 0x10 Este valor se usa para obtener únicamente los nombres de propiedad que pertenecen a la clase más derivada. Además, se excluyen las propiedades de las clases primarias.
WBEM_FLAG_PROPAGATED_ONLY 0x20 Este valor se usa para obtener únicamente los nombres de propiedad que pertenezcan a las clases primarias.
WBEM_FLAG_SYSTEM_ONLY 0x30 Este valor se usa para obtener únicamente los nombres de las propiedades del sistema.
WBEM_FLAG_NONSYSTEM_ONLY 0x40 Este valor se usa para obtener únicamente los nombres de las propiedades que no sean del sistema.

Al usar esta función, siempre se asigna una nueva matriz SAFEARRAY si se devuelve el valor WBEM_S_NO_ERROR y si el parámetro pstrNames establece de forma que siempre apunte a esta. La matriz que se devuelve puede contener 0 elementos si no hay ninguna propiedad que coincida con los filtros especificados. Si el uso de la función devuelve un valor distinto de WBM_S_NO_ERROR, no se devolverá una nueva estructura SAFEARRAY.

Requisitos

Plataformas: Vea Requisitos de sistema.

Encabezado: WMINet_Utils.idl

Versiones de .NET Framework: está disponible desde la versión 4.7.2

Consulte también