SWbemServicesEx.PutAsync method

The PutAsync method of the SWbemServicesEx object saves an object asynchronously to a namespace. When successful, this method sends an OnCompleted event to the SWbemSink object that is specified as an input parameter.

This method is called in the asynchronous mode. For more information, see Calling a Method.

For an explanation of this syntax, see Document Conventions for the Scripting API.

Syntax

SWbemServicesEx.PutAsync( _
  ByVal objWbemSink, _
  ByVal ojbWbemObject, _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

objWbemSink

Required. Object sink that receives the objects asynchronously. Create a SWbemSink object to receive the objects.

ojbWbemObject

Required. The new object to be put in the namespace. This may be a newly created object or a modified object.

iFlags [optional]

This parameter determines whether the call creates or updates the object and whether the call returns immediately. This parameter can accept the following values.

wbemChangeFlagUpdateCompatible (0 (0x0))

Allows a class to be updated when there are no derived classes and no instances for the class. It also allows updates in all cases when the change is only to unimportant qualifiers, for example, the Description qualifier. This is the default behavior for this call, and is used for compatibility with previous versions of WMI. If the class has instances, the update fails.

wbemChangeFlagUpdateSafeMode (32 (0x20))

Allows updates of classes even when there are child classes and the change does not cause conflicts with the child classes. Use this flag when adding a new property to a base class that is not mentioned previously in any of the child classes. If the class has instances, the update fails.

wbemChangeFlagUpdateForceMode (64 (0x40))

This flag forces updates of classes when conflicting child classes exist. For example, this flag forces an update when a class qualifier is defined in a child class, and the base class tries to add the same qualifier in conflict with the existing one. In the force mode, this conflict is resolved by deleting the conflicting qualifier in the child class. If the class has instances, the update fails.

The use of the force mode to update a static class causes the deletion of all instances of that class. A forced update on a provider class does not delete instances of the class.

wbemChangeFlagCreateOrUpdate (0 (0x0))

Causes the class or instance to be created if it does not exist, or overwritten if it exists already.

wbemChangeFlagCreateOnly (2 (0x2))

Used for creation only. The call fails if the class or instance already exists.

wbemChangeFlagUpdateOnly (1 (0x1))

Causes this call to update. The class or instance must exist for the call to be successful.

wbemFlagReturnImmediately (16 (0x10))

Causes the call to return immediately.

wbemFlagReturnWhenComplete (0 (0x0))

Causes this call to block until the query is complete. This flag calls the method in the synchronous mode.

wbemFlagUseAmendedQualifiers (131072 (0x20000))

Causes WMI to write class amendment data and the base class definition. For more information, see Localizing WMI Class Information.

objWbemNamedValueSet [optional]

Typically, this is undefined. Otherwise, this is an SWbemNamedValueSet object whose elements represent the context information that can be used by the provider that services the request. A provider that supports or requires such information must document the recognized value names, data type of the value, allowed values, and semantics.

objWbemAsyncContext [optional]

An SWbemNamedValueSet object that returns to the object sink to identify the source of the original asynchronous call. Use this parameter to make multiple asynchronous calls using the same object sink. To use this parameter, create an SWbemNamedValueSet object and use the SWbemNamedValueSet.Add method to add a value that identifies the asynchronous call you are making. This SWbemNamedValueSet object is returned to the object sink and the source of the call can be extracted using the SWbemNamedValueSet.Item method. For more information, see Calling a Method.

Return value

This method does not return a value. If the call is successful, the OnObjectPut event of the supplied object sink receives an SWbemObjectPath object, which contains the object path of the instance or class that is successfully committed to WMI.

Error codes

After the completion of the PutAsync method, the Err object may contain one of the error codes in the following list.

wbemErrAccessDenied - 2147749891 (0x80041003)

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

wbemErrAlreadyExists - 2147749913 (0x80041019)

The wbemChangeFlagCreateOnly flag was specified, but the instance already exists.

wbemErrFailed - 2147749889 (0x80041001)

Unspecified error.

wbemErrIllegalNull - 2147749898 (0x8004100A)

A value of Null was specified for a property that cannot be Null. An example of such a property is one marked by a Key, Indexed, or Not_Null qualifier.

wbemErrInvalidObject - 2147749908 (0x80041014)

The specified instance is not valid.

wbemErrInvalidParameter - 2147749896 (0x80041008)

A specified parameter is not valid.

wbemErrNotFound - 2147749890 (0x80041002)

The wbemChangeFlagUpdateOnly flag was specified, but the instance or class does not exist.

wbemErrIncompleteClass - 2147749920 (0x80041020)

Required properties for classes have not all been set.

wbemErrOutOfMemory - 2147749894 (0x80041006)

Not enough memory to complete the operation.

Remarks

This call returns immediately, and the results and status are returned to the caller through events delivered to the sink that is specified in objWbemSink. To handle each object when it arrives, create an objWbemSink.OnObjectReady event subroutine. Any processing done after all the objects arrive is done in a subroutine for the objWbemSink.OnCompleted event.

An asynchronous callback allows a non-authenticated user to provide data to the sink. This poses security risks to your scripts and applications. To eliminate the risks, see Setting Security on an Asynchronous Call.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Wbemdisp.h
Type library	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_ISWbemServicesEx
IID	IID_ISWbemServicesEx