3.1.4.3.13 IWbemServices::PutInstanceAsync (Opnum 15)

Article
06/24/2021

The IWbemServices::PutInstanceAsync method is the asynchronous version of the PutInstance method. The PutInstanceAsync method creates or updates an instance of an existing class.

 HRESULT PutInstanceAsync(
   [in] IWbemClassObject* pInst,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [in] IWbemObjectSink* pResponseHandler
 );

pInst: MUST be a pointer to an IWbemClassObject interface object that MUST contain the class instance that the client wants to create or update. This parameter MUST NOT be NULL.

lFlags: Flags that affect the behavior of the PutInstanceAsync method. Flag behavior MUST be interpreted as specified in the following table.

The server MUST accept a combination of zero or more flags from the following table and MUST comply with all the restrictions in a flag description. Any other DWORD value that does not comply with this condition MUST be treated as not valid.

Value	Meaning
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x00020000	If this bit is set, the server SHOULD ignore all the amended qualifiers while this method creates or updates a CIM instance. If this bit is not set, the server SHOULD include all the qualifiers, including amended qualifiers, while this method creates or updates a CIM instance.
WBEM_FLAG_UPDATE_ONLY 0x00000001	The server MUST update a CIM instance pObject if the CIM instance is present. This flag is mutually exclusive with WBEM_FLAG_CREATE_ONLY. If none of these flags are set, the server MUST create or update a CIM instance pObject.
WBEM_FLAG_CREATE_ONLY 0x00000002	The server MUST create a CIM instance pObject if the CIM instance is not already present.
WBEM_FLAG_SEND_STATUS 0x00000080	If this bit is not set, the server MUST make one final IWbemObjectSink::SetStatus call on the interface pointer that is provided in the pResponseHandler parameter. If this bit is set, the server MAY make intermediate IWbemObjectSink::SetStatus calls on the interface pointer prior to call completion.

Value

Meaning

WBEM_FLAG_USE_AMENDED_QUALIFIERS

0x00020000

If this bit is set, the server SHOULD ignore all the amended qualifiers while this method creates or updates a CIM instance.

If this bit is not set, the server SHOULD include all the qualifiers, including amended qualifiers, while this method creates or updates a CIM instance.

WBEM_FLAG_UPDATE_ONLY

0x00000001

The server MUST update a CIM instance pObject if the CIM instance is present.

This flag is mutually exclusive with WBEM_FLAG_CREATE_ONLY. If none of these flags are set, the server MUST create or update a CIM instance pObject.

WBEM_FLAG_CREATE_ONLY

0x00000002

The server MUST create a CIM instance pObject if the CIM instance is not already present.

WBEM_FLAG_SEND_STATUS

0x00000080

If this bit is not set, the server MUST make one final IWbemObjectSink::SetStatus call on the interface pointer that is provided in the pResponseHandler parameter.

If this bit is set, the server MAY make intermediate IWbemObjectSink::SetStatus calls on the interface pointer prior to call completion.

pCtx: This parameter is optional. The pCtx parameter MUST be a pointer to an IWbemContext (section 2.2.13) interface object. The pCtx parameter indicates whether the client is requesting a partial-instance update or full-instance update. A partial-instance update modifies a subset of CIM instance properties; a full-instance update modifies all the properties. If NULL, this parameter indicates that the client application is requesting a full-instance update. When pCtx is used to perform a partial-instance update, the IWbemContext interface MUST be completed with the properties that are specified in the following table. If the IWbemContext interface object does not contain the properties in the table, the method MUST return WBEM_E_INVALID_CONTEXT.

Property name	Type	Description
__PUT_EXTENSIONS	VT_BOOL	If this property is set to TRUE, one or more of the other IWbemContext values have been specified. To perform a partial-instance update, this property MUST be set to TRUE.
__PUT_EXT_STRICT_NULLS	VT_BOOL	If this property is set to TRUE, the server MUST force the setting of properties to NULL. This parameter is optional.
__PUT_EXT_PROPERTIES	VT_ARRAY \| VT_BSTR	Contains a CIM property list to update. The server MUST ignore properties that are not listed. To perform a partial-instance update, the list of properties MUST be specified.
__PUT_EXT_ATOMIC	VT_BOOL	If the return code indicates success, all CIM property updates MUST have been successful. On failure, the server MUST revert any changes to the original state for all CIM property updates. On failure, any changes MUST NOT remain. The operation is successful when all properties are updated.

pResponseHandler: MUST be a pointer to an IWbemObjectSink interface object that is implemented by the client of this method. This parameter MUST NOT be NULL.

Return Values: This method MUST return an HRESULT value that MUST indicate the status of the method call. The server MUST return WBEM_S_NO_ERROR (specified in section 2.2.11) to indicate the successful completion of the method.

WBEM_S_NO_ERROR (0x00)

The following validation occurs before asynchronous operation is started.

The security principal that makes the call MUST have WBEM_REMOTE_ENABLE and WBEM_ENABLE accesses to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

The server SHOULD enforce a maximum length for the _RELPATH system property of the object pointed to by the pInst parameter and return WBEM_E_QUOTA_VIOLATION if the limit is exceeded.<43>

Requirements mentioned in the parameter definitions are also checked before the asynchronous operation is started.

If successful, the server MUST create a new entry in AsyncOperationTable as specified in section 3.1.1.1.3.

The following validation occurs asynchronously.

If the CIM instance being updated is dynamic, the security principal that makes the call MUST have WBEM_WRITE_PROVIDER access to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

If the CIM instance being updated is static and if the CIM instance is of a class that has a WMI system class as one of the classes in the parent hierarchy, the security principal that makes the call MUST have WBEM_FULL_WRITE access to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

If the CIM instance being updated is static and if the CIM instance is of a class that does not have a WMI system class as one of the classes in the parent hierarchy, the security principal that makes the call MUST have WBEM_PARTIAL_WRITE_REP access to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

If the CIM class of the instance being created has a parent class that is not abstract, the server MUST fail the operation with WBEM_E_NOT_FOUND. [DMTF-DSP0004] requires that the operation MUST succeed when the parent CIM class is abstract.

If the CIM instance being created or updated is dynamic, the server MUST obtain SupportsPut for the corresponding provider in the ProviderTable. If SupportsPut is FALSE, the server MUST return WBEM_E_PROVIDER_NOT_CAPABLE.

In response to an IWbemServices::PutInstanceAsync method, the server MUST evaluate the pInst parameter as specified in this section. It MUST add or update this instance into the current namespace. The method MUST fail if one of the following is true: the server does not allow the creation of new instances for the class of pInst or does not allow modification of the instance that is represented by pInst; the method parameters or their combinations are not valid, as specified earlier in this section; or the server is unable to execute the method.

If the instance belongs to the __Namespace class, then the server MUST create a new namespace as described in section 3.1.4.3.13.

3.1.4.3.13 IWbemServices::PutInstanceAsync (Opnum 15)

Additional resources