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.