IWbemClassObject::Put

[This is preliminary documentation and subject to change.]

The IWbemClassObject::Put method sets a named property to a new value. This method always overwrites the current value with the new one.

HRESULT IWbemClassObject::Put(
  [in] BSTR bstrName, 
  [in] Long lFlags,
  [in] VARIANT *pVal,
  [in] VARTYPE vtType 
);

Parameters

bstrName
Must point to a valid BSTR containing the property name. The pointer is treated as read-only. This cannot be NULL.
lFlags
Reserved. It must be zero.
pVal
Must point to a valid VARIANT, which becomes the new property value. If pVal is NULL or points to a VARIANT of type VT_NULL, the property is set to NULL, that is, no value.

Note  The NULL value for a property designated by a VARIANT of type VT_NULL is distinguished from a property of type VT_I4 with a zero value.

If pVal is NULL or points to a VT_NULL, the type of the property is inferred from the vtType parameter.

If pVal is to contain an embedded IWbemClassObject, the caller must call IWbemClassObject::QueryInterface for IID_IDispatch and place the resulting pointer in the VARIANT using a type of VT_DISPATCH.

The pointer is treated as read-only. The caller is responsible for invoking VariantClear after this call has completed.

vtType
This parameter is used only when pVal is NULL or points to a VARIANT of type VT_NULL. In such a case, the vtType parameter specifies a COM type of the property. In every other case, vtType must be zero. vtType must also be zero whenever the underlying object is an instance (even if pVal is NULL), since the type of the property is fixed and cannot be changed. In other words, vtType is used if, and only if, pVal is NULL or points to a VT_NULL VARIANT, and the underlying object is a class.

Return Values

WBEM_E_FAILED General failure.
WBEM_E_INVALID_PARAMETER An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_PROPERTY_TYPE Property type is not recognized.
WBEM_E_OUT_OF_MEMORY There was insufficient memory to complete the operation.
WBEM_E_TYPE_MISMATCH For instances, this error code indicates that the pVal parameter points to a VARIANT of an incorrect type for the property. For class definitions, this is returned if the property already exists in the parent class, and the new COM type is different from the old COM type. Such properties are read-only for the derived class.
WBEM_NO_ERROR Success.

Remarks

If the property exists in the superclass, its default value is changed unless it is a type mismatch. If the property does not exist and it is not a type mismatch, the property is created.

When executing this method on an instance, an overwrite always occurs. It occurs because the property always exists.

When you are creating a new class, and the underlying type of the property is an object reference, a date/time string, or other special type, it might be necessary to modify the CIMTYPE qualifier for the property to indicate the special new class. When modifying properties of an instance, the qualifiers are set to the correct values ahead of time.

You can only write system properties when you create a new class. In that case, the name of the class you create is designated by writing it to the system property __CLASS.

See Also

System Classes, Properties, and Qualifiers_