The object that exports the IWbemQualifierSet interface acts as a container for the entire set of named qualifiers for a single property, Also, it can act as a container for an entire class object, instance, or class definition, depending on how the pointer was obtained. If the pointer was obtained from IWbemClassObject::GetQualifierSet, the object consists of the set of qualifiers for an entire object (a class or instance). If the pointer was obtained from IWbemClassObject::GetPropertyQualifierSet, then the object represents the qualifiers for a particular property on a class or instance.
Within WBEM, this interface is always in-process. Put operations only affect the local copy of the object. Get operations retrieve values from the local copy. Updates are performed only when entire objects are read or written using methods on the IWbemServices interface.
Dynamic providers must not implement this interface; the implementation provided by WBEM must be used.
| IWbemQualifierSet Methods | Description |
| Get | Reads a particular named qualifier. |
| Put | Writes a particular named qualifier. |
| Delete | Deletes the specified named qualifier. |
| GetNames | Gets the names of qualifiers subject to certain filters. |
| BeginEnumeration | Resets prior to an enumeration of all qualifiers. |
| Next | Gets the next qualifier during an enumeration of all qualifiers. |
| EndEnumeration | Ends an enumeration of qualifiers. |
The IWbemQualifierSet::Get method gets the specified named qualifier, if found.
HRESULT IWbemQualifierSet::Get(
[in] BSTR strName,
[in] LONG lFlags,
[out, OPTIONAL] VARIANT *pVal,
[out, OPTIONAL] LONG *plFlavor
);
Parameters
strName
The qualifier name for which the value is being requested. This must point to a valid
BSTR which is not NULL. The pointer is treated as read-only.
lFlags
Reserved. Must be zero.
pVal
When successful, the VARIANT is assigned to the correct type and value for the
qualifier. VariantInit is called on this VARIANT, so a pointer to a VARIANT
already containing a value should be cleared before using it as a parameter.
It is the responsibility of the caller to call VariantClear on the pointer when the value is no longer required. If there is an error code, the VARIANT pointed to by pVal is not modified.
If this parameter is NULL, the parameter is ignored.
plFlavor
Can be NULL. If not NULL, this must point to a LONG that receives the qualifier flavor
bits for the requested qualifier.
Return Values
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_NOT_FOUND | The specified qualifier did not exist. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
The IWbemQualifierSet::Put method writes the named qualifier and value. If the qualifier does not exist, it is created. The new qualifier overwrites the previously existing value of the same name.
In some cases, it is not possible to write the value of a qualifier if it was propagated from another object. Propagated qualifiers are generally read-only, but they can be overridden in some cases.
When writing the key qualifier, it is not necessary to specify any flavors or propagation rules.
The user may not create qualifiers with names that begin or end with an underscore. This is reserved for system classes and properties.
HRESULT IWbemQualifierSet::Put(
[in] BSTR strName,
[in] VARIANT *pVal,
[in] LONG lFlavor
);
Parameters
strName
The name of the qualifier that is being written. This must point to a valid non-NULL
BSTR. The pointer is treated as read-only.
pVal
Cannot be NULL. This must point to a valid VARIANT that contains the qualifier
value to be written. The pointer is treated as read-only. It is the caller's
responsibility to call VariantClear on this pointer after the value is no longer
needed.
Only variants of type VT_I4, VT_R8, VT_BSTR, VT_BOOL and arrays of types VT_BSTR, VT_I4, VT_R8, and VT_BOOL are supported.
lFlavor
The desired qualifier flavor for this qualifier. Not required if the qualifier is the
key qualifier (can be zero).
Return Values
| WBEM_E_CANNOT_BE_KEY | There was an illegal attempt to specify a key qualifier on a property that cannot be a key. The keys are specified in the class definition for an object, and cannot be altered on a per-instance basis. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_INVALID_QUALIFIER_TYPE | The pVal parameter is not of a legal qualifier type. |
| WBEM_E_OVERRIDE_NOT_ALLOWED | It is not possible to perform the IWbemQualifierSet::Put operation on this qualifier because the owning object does not permit overrides. |
| WBEM_S_NO_ERROR | The call succeeded. |
| WBEM_E_INVALID_QUALIFIER | Qualifiers mismatched. For example, the qualifiers "dynamic" and "key" cannot exist in the same qualifier set. |
See Also
The IWbemQualifierSet::Delete method deletes the specified qualifier by name. Due to qualifier propagation rules, a particular qualifier may have been inherited from another object and merely overridden in the current class or instance. In this case, use the Delete method to reset the qualifier to the original inherited value.
HRESULT IWbemQualifierSet::Delete(
[in] BSTR strName
);
Parameters
strName
The name of the qualifier to delete. This must be a valid non-NULL BSTR. The pointer
is treated as read-only.
Return Values
| WBEM_E_INVALID_OPERATION | Deleting this qualifier is illegal. |
| WBEM_E_INVALID_PARAMETER | The Name parameter was not valid. |
| WBEM_E_NOT_FOUND | The specified qualifier was not found. |
| WBEM_S_NO_ERROR | The call succeeded. |
| WBEM_S_RESET_TO_DEFAULT | When deleting an overridden qualifier, this status code (a non-error code) indicates that the local override was deleted, and that the original qualifier from the parent object has resumed scope. A subsequent attempt to get the qualifier will succeed, returning the parent's value. |
See Also
The IWbemQualifierSet::GetNames method retrieves the names of all of the qualifiers available from the current object or property. Alternately, depending on the filter value of IFlags, this method retrieves the names of certain qualifiers.
You can access these qualifiers by name, using IWbemQualifierSet::Get for each name. It is not an error for any given object to have zero qualifiers, so the number of strings in pstrNames on return can be zero, even though WBEM_S_NO_ERROR returns.
HRESULT IWbemQualifierSet::GetNames(
[in] LONG lFlags,
[out] SAFEARRAY (BSTR) *pstrNames
);
Parameters
lFlags
One of the following constants:
| 0 (Zero) | Return the names of all qualifiers. |
| WBEM_FLAG_LOCAL_ONLY | Return only the names of qualifiers specific to the current property or object. If the current qualifiers set refers to a property, return only the qualifiers specific to the property (including overrides), and not those qualifiers propagated from the class definition. If the current qualifiers set refers to an instance, return only instance-specific qualifier names. If the current qualifiers set refers to a class, return only qualifiers specific to the derived-most class. |
| WBEM_FLAG_PROPAGATED_ONLY | Return only the names of qualifiers propagated from another object. For example, if the current qualifier set refers to a property, return only the qualifiers propagated to this property from the class definition, and not those from the property itself. If the current qualifier set refers to an instance, return only those qualifiers propagated from the class definition. If the current qualifier set refers to a class, return only those qualifier names inherited from the superclasses. |
pstrNames
A new SAFEARRAY is created that contains the requested names.
In all cases where no error is returned, a new array is created and pstrNames is set to point to it. This occurs even though the resulting array has zero elements. On error, a new SAFEARRAY is not returned.
Return Values
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
The IWbemQualifierSet::BeginEnumeration method resets before there is an enumeration of all the qualifiers in the object. To enumerate all of the qualifiers on an object, this method must be called before the first call to IWbemQualifierSet::Next.
HRESULT IWbemQualifierSet::BeginEnumeration(
[in] LONG lFlags
);
Parameters
lFlags
Specifies the qualifiers to include in the enumeration. It must be one of the
following constants:
| 0 (Zero) | Return the names of all qualifiers. |
| WBEM_FLAG_LOCAL_ONLY | Return only the names of qualifiers specific to the current property or object. If the current qualifiers set refers to a property, return only the qualifiers specific to the property (including overrides), and not those qualifiers propagated from the class definition. If the current qualifiers set refers to an instance, return only instance-specific qualifier names. If the current qualifiers set refers to a class, return only qualifiers specific to the derived-most class. |
| WBEM_FLAG_PROPAGATED_ONLY | Return only the names of qualifiers propagated from another object. For example, if the current qualifier set refers to a property, return only the qualifiers propagated to this property from the class definition, and not those from the property itself. If the current qualifier set refers to an instance, only return those qualifiers propagated from the class definition. If the current qualifier set refers to a class, only return those qualifier names inherited from the superclasses. |
Return Values
| WBEM_E_INVALID_PARAMETER | The lFlags parameter was not valid. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation. |
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
The IWbemQualifierSet::Next method retrieves the next qualifier in an enumeration that started with IWbemQualifierSet::BeginEnumeration. This method is called repeatedly to enumerate all the qualifiers until WBEM_S_NO_MORE_DATA returns. To terminate the enumeration early, call IWbemQualifierSet::EndEnumeration.
The order of the qualifiers returned during the enumeration is not defined and may vary if the qualifier set is altered.
HRESULT IWbemQualifierSet::Next(
[in] LONG lFlags,
[out, OPTIONAL] BSTR *pstrName,
[out, OPTIONAL] VARIANT *pVal,
[out, OPTIONAL] LONG *plFlavor
);
Parameters
lFlags
Reserved. Must be zero.
pstrName
This parameter receives the name of the qualifer. A new BSTR is always allocated
whenever WBEM_S_NO_ERROR is returned.
The caller must ensure that this parameter does not point to a valid BSTR on entry (NULL is recommended). Also, the caller must remember to call SysFreeString on the returned string when it is no longer required. Callers may pass NULL, in which case this parameter will be ignored.
If upon entry pstrName points to a valid BSTR, this BSTR is not freed, and there will be a memory leak.
pVal
This parameter receives the value for the qualifier. VariantInit is called on
the VARIANT by this method. The caller must call VariantClear on this
pointer when the value is no longer required. If an error code is returned, the VARIANT
pointed to by pVal is left unmodified. This parameter will be ignored if set to NULL.
plFlavor
If not NULL, the value pointed to is set to the qualifier flavor.
Return Values
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation. |
| WBEM_E_UNEXPECTED | Caller did not call IWbemQualifierSet::BeginEnumeration. |
| WBEM_S_NO_ERROR | The call succeeded. |
| WBEM_S_NO_MORE_DATA | No more qualifiers are left in the enumeration. |
See Also
IWbemQualifierSet::BeginEnumerationCall the IWbemQualifierSet::EndEnumeration method to terminate enumerations which were initiated with IWbemQualifierSet::BeginEnumeration and IWbemQualifierSet::Next. We recommend this call, but it is not required. It immediately releases resources associated with the enumeration. Failing to make the call may result in useless memory consumption until the interface pointer is released.
HRESULT IWbemQualifierSet::EndEnumeration( );
Parameters
None.
Return Values
| WBEM_S_NO_ERROR | The call succeeded. |
See Also
IWbemQualifierSet::BeginEnumeration