Creating and Modifying an Instance

[This is preliminary documentation and subject to change.]

To create an instance of an existing class, call IWbemClassObject::SpawnInstance. Every instance of a class inherits the properties that are defined with the class. Instances can differ from their classes only in the values of properties and qualifiers and in the number and types of qualifiers. Each instance can have its own set of qualifiers attached both to the instance itself and to any of the properties of the instance. These instance-specific qualifiers do not need to appear in the class declaration.

To store the instance in the CIMOM repository, call IWbemServices::PutInstance.

An instance can have instance-specific qualifiers and qualifiers that are attached to a property of the instance. These qualifiers do not have to appear in the class definition. An instance can override the value of a class qualifier only if the flavor of that qualifier was set to EnableOverride. See Qualifier Flavors for more information about overriding qualifier values.

An overridable qualifier can be modified or deleted by any instance of the class to which the qualifier is attached. Class qualifiers with flavors set to DisableOverride cannot be modified or deleted in any way.

The following code creates an instance of the Example class:

IWbemClassObject *pNewInstance = 0;
IWbemClassObject *pExampleClass = 0;

BSTR PathToClass = SysAllocString(L"Example");
HRESULT hRes = g_pNamespace->GetObject(PathToClass, 0, &pExampleClass, 0);
SysFreeString(PathToClass);

if (hRes != 0)
   return;

pExampleClass->SpawnInstance(0, &pNewInstance);
pExampleClass->Release();  // Don't need the class any more

VARIANT v;
VariantInit(&v);

// Create the index value.
// =======================

V_VT(&v) = VT_BSTR;

V_BSTR(&v) = SysAllocString(L"IX100");
BSTR KeyProp = SysAllocString(L"Index");
pNewInstance->Put(KeyProp, 0, &v);
SysFreeString(KeyProp);
VariantClear(&v);

// Other properties acquire the 'default' value specified
// in the class definition unless otherwise modified here.

// Write the instance to CIMOM
hRes = g_pNamespace->PutInstance(pNewInstance, 0, 0);
pNewInstance->Release();
 

After its creation, this instance has a path of \\.\Root\Default:Example.Index="IX100."

New properties are created initially with the VARIANT data type unless the Cimtype standard qualifier is attached to the property to specify its true type. For example, a date/time property should be created with the Cimtype qualifier set to the DATETIME type. When the Cimtype qualified is used, CIMOM checks that the qualifier specifies a type that is correct for the property.

To establish references to other objects, attach the Cimtype qualifier containing a string of the following format to a property of type VT_BSTR:

REF:ClassName

For example, if you require an object reference property that refers to Win32LogicalDisk instances, the Cimtype qualifier is attached to the property when you create your class definition.

BSTR RefProp = SysAllocString(L"MyReferenceProperty");
  IWbemQualifierSet *pQual = 0;
  pNewClass->GetPropertyQualifierSet(RefProp, &pQual);

  VARIANT v;
  VariantInit(&v);
  V_VT(&v) = VT_BSTR;
  V_BSTR(&v) = SysAllocString(L"REF:Win32LogicalDisk");
  BSTR QualName = SysAllocString(L"CIMTYPE");
  pQual->Put(QualName, WBEM_FLAVOR_FLAG_PROPAGATE_TO_INSTANCE, &v);

However, if there is an embedded object, use the keyword object instead of ref.