Skip to main content
IWbemServices::PutInstance method

The IWbemServices::PutInstance method creates or updates an instance of an existing class. The instance is written to the WMI repository.


HRESULT PutInstance(
  [in]  IWbemClassObject *pInst,
  [in]  LONG             lFlags,
  [in]  IWbemContext     *pCtx,
  [out] IWbemCallResult  **ppCallResult


pInst [in]

Pointer to the instance to be written. The caller cannot make assumptions about the reference count at the completion of this call.

lFlags [in]

One or more of the following values can be set.


This flag causes the instance to be created if it does not exist or overwritten if it exists already.


This flag causes this call to update. The instance must exist for the call to be successful.


This flag is used for creation only. The call fails if the instance already exists.


This flag causes this to be a semisynchronous call. For more information, see Calling a Method.


If this flag is set, WMI does not store any qualifiers with the Amended flavor. If this flag is not set, it is assumed that this object is not localized, and all qualifiers are stored with this instance.

pCtx [in]

Typically NULL, indicating that every property in the instance is to be updated. Otherwise, this is a pointer to an IWbemContext object containing more information about the instance. The data in the context object must be documented by the provider responsible for the instance. A non-NULLIWbemContext object can indicate whether support exists for partial-instance updates.

For more information about how to support full and partial-instance updates, see IWbemServices::PutInstanceAsync. For more information about requesting a full or partial-instance update operation, see Modifying an Instance Property.

ppCallResult [out]

If NULL, this parameter is not used. If the lFlags parameter contains WBEM_FLAG_RETURN_IMMEDIATELY, this call returns immediately with WBEM_S_NO_ERROR. The ppCallResult parameter then receives a pointer to a new IWbemCallResult object, which can be polled with IWbemCallResult::GetCallStatus to obtain the result.

Return value

This method returns an HRESULT indicating the status of the method call. The following list lists the value contained within an HRESULT.

COM-specific error codes also may be returned if network problems cause you to lose the remote connection to Windows Management.


The current user does not have permission to update an instance of the specified class.


WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.


The class supporting this instance is not valid.


This indicates other unspecified errors.


A NULL value was specified for a property that cannot be NULL, such as one that is marked by an Indexed or Not_Null qualifier.


The specified instance is not valid (for example, PutInstance with a class invokes this return).


A specified parameter is not valid.


WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.


There was not enough memory to complete the operation.


Windows Management service was probably stopped and restarted. A new call to ConnectServer is needed.


This indicates the failure of the remote procedure call (RPC) link between the current process and Windows Management.


The call succeeded.


Applications and providers call PutInstance to create or update an instance of an existing class. Depending on how the pCtx parameter is set, either some or all of the properties of the instance are updated. For more information about how to support partial instance updating, see IWbemServices::PutInstanceAsync. For more information about requesting a partial instance update, see Modifying an Instance Property.

The PutInstance method supports creating instances and updating instances only. It does not support moving instances. That is, a caller cannot set the pInst parameter to an instance that has a key that is the same as another instance in a sibling class. For example, suppose ClassA is the base class to ClassB and ClassC. The ClassA class defines the KeyProp property as its key and ClassB has an instance that has KeyProp set to 1. To create an instance of ClassC with KeyProp set to 1, an application must first delete the ClassB instance by calling DeleteInstance and then save the ClassC instance with PutInstance.

When the instance pointed to by pInst belongs to a subclass, Windows Management calls all of the providers responsible for the classes from which the subclass derives. All of these providers must succeed for the original PutInstance request to succeed. The provider supporting the topmost class in the hierarchy is called first. The calling order continues with the subclass of the topmost class and proceeds from top to bottom until Windows Management reaches the provider for the class owning the instance pointed to by pInst.

Windows Management does not call the providers for any of the child classes of an instance. Therefore, if an application wants to change the values of inherited properties, the application must call PutInstance on the full instance of the child class rather than a corresponding instance of the parent class.

When an application must update an instance that belongs to a class hierarchy, the pInst parameter must point to the instance containing the properties to be modified. That is, consider a target instance that belongs to ClassB. The ClassB instance derives from ClassA, and ClassA defines the property PropA. If an application wants to make a change to the value of PropA in the ClassB instance, it must set pInst to that instance rather than an instance of ClassA.

Calling PutInstance on an instance of an abstract class is not allowed.


Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008


WbemCli.h (include Wbemidl.h)





See also

Creating an Instance
Retrieving an Error Code