Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

IWbemServices::PutInstance method

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

Syntax


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

Parameters

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.

FlagMeaning
WBEM_FLAG_CREATE_OR_UPDATE

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

WBEM_FLAG_UPDATE_ONLY

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

WBEM_FLAG_CREATE_ONLY

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

WBEM_FLAG_RETURN_IMMEDIATELY

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

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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 table 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.

Return codeDescription
WBEM_E_ACCESS_DENIED

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

WBEM_E_ALREADY_EXISTS

WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.

WBEM_E_INVALID_CLASS

The class supporting this instance is not valid.

WBEM_E_FAILED

This indicates other unspecified errors.

WBEM_E_ILLEGAL_NULL

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

WBEM_E_INVALID_OBJECT

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

WBEM_E_INVALID_PARAMETER

A specified parameter is not valid.

WBEM_E_NOT_FOUND

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

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the operation.

WBEM_E_SHUTTING_DOWN

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

WBEM_E_TRANSPORT_FAILURE

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

WBEM_S_NO_ERROR

The call succeeded.

 

Remarks

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.

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.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Fastprox.dll;
Esscli.dll;
Framedyn.dll;
Ntevt.dll;
Stdprov.dll;
Viewprov.dll;
Wbemcomn.dll;
Wbemcore.dll;
Wbemess.dll;
Wbemsvc.dll;
Wmipicmp.dll;
Wmidcprv.dll;
Wmipjobj.dll;
Wmiprvsd.dll

See also

IWbemServices
Creating an Instance
Retrieving an Error Code
IWbemCallResult
IWbemServices::PutInstanceAsync

 

 

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