Edit

GetNames function

  • Article

Retrieves either a subset or all of the names of the properties of an object.

Note

This API is for internal use only. It's not intended for use from developer code.

Syntax

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

Parameters

vFunc
[in] This parameter is unused.

ptr
[in] A pointer to an IWbemClassObject instance.

wszQualifierName
[in] A pointer to a valid LPCWSTR that specifies a qualifier name that operates as part of a filter. For more information, see the Remarks section. This parameter can be null.

lFlags
[in] A combination of bit fields. For more information, see the Remarks section.

pQualifierValue [in] A pointer to a valid VARIANT structure initialized to a filter value. This parameter can be null.

pstrNames
[out] A SAFEARRAY structure that contains property names. On entry, this parameter must always be a pointer to null. See the Remarks section for more information.

Return value

The following values returned by this function are defined in the WbemCli.h header file, or you can define them as constants in your code:

Constant Value Description
WBEM_E_FAILED 0x80041001 There has been a general failure.
WBEM_E_INVALID_PARAMETER 0x80041008 One or more parameters are not valid, or an incorrect combination of flags and parameters was specified.
WBEM_E_OUT_OF_MEMORY 0x80041006 Not enough memory is available to complete the operation.
WBEM_S_NO_ERROR 0 The function call was successful.

Remarks

This function wraps a call to the IWbemClassObject::GetNames method.

The named returned are controlled by a combination of flags and parameters. For example, the function can return the names of all properties or only the names of the key properties. The primary filter is specified in the lFlags parameter, and the other parameters vary depending on it.

The flag values in lFlags are bit fields

The flags that can be passed as the lEnumFlags argument are bit fields that are defined in the WbemCli.h header file, or you can define them as constants in your code. You can combine one flag from each group with any flag from any other group. However, flags from the same group are mutually exclusive.

Group 1 flags Value Description
WBEM_FLAG_ALWAYS 0 Return all property names. strQualifierName and pQualifierVal are unused.
WBEM_FLAG_ONLY_IF_TRUE 1 Return only properties that have a qualifier of the name specified by the strQualifierName parameter. If this flag is used, you must specify strQualifierName.
WBEM_FLAG_ONLY_IF_FALSE 2 Return only properties that do not have a qualifier of the name specified by the strQualifierName parameter. If this flag is used, you must specify strQualifierName.
WBEM_FLAG_ONLY_IF_IDENTICAL 3 Return only properties that have a qualifier of the name specified by the wszQualifierName parameter and also have a value identical to that specified by the pQualifierVal structure. If this flag is used, you must specify both a wszQualifierName and a pQualifierValue.
Group 2 flags Value Description
WBEM_FLAG_KEYS_ONLY 0x4 Return only the names of properties that define the keys.
WBEM_FLAG_REFS_ONLY 0x8 Return only property names that are object references.
Group 3 flags Value Description
WBEM_FLAG_LOCAL_ONLY 0x10 Return only property names that belong to the most derived class. Exclude properties from the parent classes.
WBEM_FLAG_PROPAGATED_ONLY 0x20 Return only property names that belong to the parent classes.
WBEM_FLAG_SYSTEM_ONLY 0x30 Return only the names of system properties.
WBEM_FLAG_NONSYSTEM_ONLY 0x40 Return only the names of non-system properties.

The function always allocates a new SAFEARRAY if it returns WBEM_S_NO_ERROR, and pstrNames is always set to point to it. The returned array can have 0 elements if no properties match the specified filters. If the function returns an value other than WBM_S_NO_ERROR, a new SAFEARRAY structure is not returned.

Requirements

Platforms: See System Requirements.

Header: WMINet_Utils.idl

.NET Framework Versions: Available since 4.7.2

See also