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

SWbemObject.PutAsync_ method

The PutAsync_ method of SWbemObject asynchronously creates or updates an instance or class object to Windows Management Instrumentation (WMI). You can use this method after you modify any properties or methods in SWbemObject, and your changes are written to WMI.

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

Syntax

SWbemObject.PutAsync_( _
  ByVal objWbemSink, _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

objWbemSink [in]

Required. Object sink that asynchronously receives the result of the put operation.

iFlags [in, optional]

Determines if the call creates or updates the class or instance and if the call returns immediately. This parameter can accept the following values.

ValueMeaning
wbemChangeFlagUpdateCompatible
0 (0x0)

Allows a class to be updated if there are no derived classes and there are no instances for that class. It also allows updates in all cases if the change is just 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 if there are child classes, if the change does not cause conflicts with child classes. You can use this flag when adding a new property to a base class that was not previously mentioned in any of the child classes. If the class has instances the update fails.

WbemChangeFlagUpdateForceMode
64 (0x40)

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

Using force mode to update a static class results in 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 has completed.

wbemFlagSendStatus
128 (0x80)

Causes asynchronous calls to send status updates to the SWbemSink.OnProgress event handler for the object sink.

wbemFlagDontSendStatus
0 (0x0)

Prevents asynchronous calls from sending status updates to the OnProgress event handler for the object sink.

wbemFlagUseAmendedQualifiers
131072 (0x20000)

Causes WMI to write class amendment data along with the base class definition. For more information about amended qualifiers, see Localizing WMI Class Information.

 

objWbemNamedValueSet [in, 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 is servicing the request. A provider that supports or requires this information must document the recognized value names, data type of the value, allowed values, and semantics.

objWbemAsyncContext [in, optional]

This is an SWbemNamedValueSet object that returns to the object sink to identify the source of the original asynchronous call. Use this parameter if you are making 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, containing 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 table.

Error (Name/Dec/Hex)Meaning
wbemErrAccessDenied
2147749891 (0x80041003)

Current user does not have 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 Nothing was specified for a property that may not be Nothing. An example of such a property is one that is 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 result of the put operation is returned to the caller through callbacks delivered to the sink that is specified in objWbemSink. Implement the objWbemSink. OnObjectPut method to obtain the object path of the instance or class that is written to the WMI repository. For more information about sink methods, see Calling a Method.

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, use semisynchronous or synchronous communication. For more information, see Calling a Method.

Examples

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

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Type library

Wbemdisp.tlb

DLL

Wbemdisp.dll

See also

SWbemObject
SWbemObjectPath.Class
SWbemProperty
SWbemQualifier

 

 

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