Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

IWbemClassObject::Put method

The IWbemClassObject::Put method sets a named property to a new value. This method always overwrites the current value with a new one. When IWbemClassObject points to a CIM class definition, Put creates or updates the property value. When IWbemClassObject points to a CIM instance, Put updates a property value only. Put cannot create a property value.

A user cannot create properties with names that begin or end with an underscore (_). This is reserved for system classes and properties.

Syntax


HRESULT Put(
  [in]  LPCWSTR wszName,
  [in]  LONG lFlags,
  [in]  VARIANT *pVal,
  [in]  CIMTYPE vtType
);

Parameters

wszName [in]

A parameter that must point to a valid property name. This parameter cannot be NULL.

lFlags [in]

Reserved. This parameter must be 0 (zero).

pVal [in]

A parameter that 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.

vtType [in]

A type of VARIANT pointed to by pVal.

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 0 (zero) value.

When creating new properties, if pVal is NULL or points to a VT_NULL, the type of the property is determined from the vtType parameter.

If pVal is to contain an embedded IWbemClassObject, the caller must call IWbemClassObject::QueryInterface for IID_IUnknown and place the resulting pointer in the VARIANT using a type of VT_UNKNOWN. The original embedded object is copied during the Put operation, and so cannot be modified by the operation.

The pointer is treated as read-only. The caller must call VariantClear after this call is complete.

Use this parameter only when creating new properties in a CIM class definition and pVal is NULL or points to a VARIANT of type VT_NULL. In such a case, the vtType parameter specifies the CIM type of the property. In every other case, vtType must be 0 (zero). Also, vtType must be 0 (zero) when the underlying object is an instance (even if pVal is NULL), because the type of the property is fixed and cannot be changed. In other words, use vtType if, and only if, pVal is NULL or points to a VT_NULL VARIANT, and the underlying object is a CIM class.

When using IWbemClassObject::Put to assign empty array values to a property, you do not need to specify the exact VT type; you can assign a value to pVal that is a VARIANT with a variant type of VT_ARRAY|VT_VARIANT.

Return value

This method returns an HRESULT that indicates the status of the method call. The following table lists the values contained within an HRESULT.

Return codeDescription
WBEM_E_FAILED

There has been a general failure.

WBEM_E_INVALID_PARAMETER

An NULL or otherwise invalid parameter was specified.

WBEM_E_INVALID_PROPERTY_TYPE

Property type is not recognized. When creating class instances, this is returned if the class already exists.

WBEM_E_OUT_OF_MEMORY

There was not enough 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_S_NO_ERROR

The call succeeded.

 

Remarks

If the property set by the IWbemClassObject::Put method exists in the parent class, the default value of the property is changed unless the property type does not match the parent class type. 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, because the property always exists.

When creating a new class and the underlying type of the property is an object reference, date/time string, or other special type, you might need to modify the CIM type parameter for the property to indicate the special new class. The CIMType qualifier on instance properties is read-only and inherited from the class object.

If the variant type specified in pVal does not match the CIM type of the property, WMI attempts to change the variant to the appropriate variant type, using the normal variant coercion rules. If the variant cannot be coerced, WBEM_E_TYPE_MISMATCH is returned. The following table lists exceptions to the normal variant coercion rules when the property is type uint32.

Pass in variant typeResult
VT_I4S_OK
VT_I2WBEM_TYPE_MISMATCH
VT_R8S_OK

However, passing in a VT_ARRAY|VT_R8 to a property of type uint32[] will fail.

 

The __CLASS system property is only writeable during class creation, when it may not be left blank. All other system properties are read-only.

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

The following code example shows how to set the class name for a new CIM class.


// pObj is an empty object from IWbemServices::GetObject
// Set up the property value.
VARIANT v; 
VariantInit(&v);
V_VT(&v) = VT_BSTR;
V_BSTR(&v) = SysAllocString(L"MyClass");

// Write it.
LPCWSTR strClassProp = L"__CLASS";
pObj->Put(strClassProp, 0, &v, 0);

// Clean up.
VariantClear(&v);

The following code example shows how to set the value of the SomeUint64 property. Be aware that the BSTR value must be in decimal format and not hexadecimal.


// pObj is an instance containing a uint64 property
// Set up the property value.
VARIANT v; 
VariantInit(&v);
V_VT(&v) = VT_BSTR;
V_BSTR(&v) = SysAllocString(L"1033"); // - decimal format, not hex

// Write it.
LPCWSTR strClassProp = L"SomeUint64";
pObj->Put(strClassProp, 0, &v, CIM_UINT64);

// Clean up.
VariantClear(&v);

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

CIMWin32.dll;
Esscli.dll;
Evntrprv.dll;
Fastprox.dll;
Framedyn.dll;
Krnlprov.dll;
Ncprov.dll;
Wbemcore.dll;
Wbemess.dll;
Wmipiprt.dll

See also

IWbemClassObject
WMI System Classes
WMI System Properties
WMI Qualifiers
IUnknown::QueryInterface

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.