IWbemClassObject::GetNames

[This is preliminary documentation and subject to change.]

The IWbemClassObject::GetNames method retrieves the names of all of the properties in the object. Depending on user-supplied selection criteria, furthermore, it can retrieve a subset of the properties. These properties can then be accessed by using IWbemClassObject::Get for each name. This method can also return system properties.

HRESULT IWbemClassObject::GetNames(
  [in] BSTR bstrQualifierName,
  [in] Long lFlags,
  [in] VARIANT *pQualifierVal,
  [out] SAFEARRAY (BSTR) *pbstrNames
);
 

Parameters

bstrQualifierName
Can be NULL. If not NULL, it must point to a valid BSTR specifying a qualifier name. This is treated as read-only. See Remarks.
lFlags
See Remarks.
pQualifierValue
Can be NULL. If not NULL, it must point to a valid VARIANT structure initialized to a filter value. See Remarks. This VARIANT is treated as read-only by the method. Thus, the caller is responsible for calling VariantClear on it, if required.
pbstrNames
Cannot be NULL, but on entry this parameter must point to NULL. A new SAFEARRAY is always allocated, and the pointer is set to point to it. The returned array can have zero elements, but is always allocated when WBEM_NO_ERROR is returned. On error, a new SAFEARRAY is not returned.

Return Values

WBEM_E_FAILED General failure.
WBEM_E_INVALID_PARAMETER One or more parameters were invalid, or an incorrect combination of flags and parameters was specified.
WBEM_E_OUT_OF_MEMORY There was not enough memory to complete the task.
WBEM_NO_ERROR Success.

Remarks

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

The flag values are bit fields, and can be combined. One flag from each of the following groups can be combined with a flag from each of the other groups. Flag values within a group are mutually exclusive.

GROUP 1

WBEM_FLAG_ALWAYS
Return all property names. QualifierName and pQualifierVal are reserved.
WBEM_FLAG_ONLY_IF_TRUE
Return only properties that have a qualifier of the name specified by the parameter QualifierName. If this flag is used, you must specify QualifierName.
WBEM_FLAG_ONLY_IF_FALSE
Return only properties that do not have a qualifier of the name specified by the parameter QualifierName. If this flag is used, you must specify QualifierName.
WBEM_FLAG_ONLY_IF_IDENTICAL
Return only properties that have a qualifier of the name specified by the parameter QualifierName, and also have a value identical to the value specified by the VARIANT pointed to by pQualifierVal. If this flag is used, you must specify both QualifierName and pQualifierVal.

GROUP 2

WBEM_FLAG_KEYS_ONLY
Return only the names of the property or properties that define the keys.
WBEM_FLAG_REFS_ONLY
Return only property names that are object references.

GROUP 3

WBEM_FLAG_LOCAL_ONLY
Return only property names that belong to the derived-most class. Exclude properties from the superclass or superclasses.
WBEM_FLAG_PROPAGATED_ONLY
Return only property names that belong to the superclass or superclasses.
WBEM_FLAG_SYSTEM_ONLY
Return only system properties.
WBEM_FLAG_NONSYSTEM_ONLY
Return only property names that are not system properties.

It is not an error for an empty list, which is an array of zero elements, to be returned in cases where no properties match the specified filters.

See Also

IWbemClassObject::Get, System Properties, IWbemClassObject::BeginEnumeration