3.1.4.3.6 IWbemServices::PutClass (Opnum 8)

  • Article

The IWbemServices::PutClass method creates a new class or updates an existing class in the namespace that is associated with the current IWbemServices interface. The server MUST NOT allow the creation of classes that have names that begin or end with an underscore because those names are reserved for system classes. If the class name does not conform to the CLASS-NAME element defined in WQL, the server MUST return WBEM_E_INVALID_PARAMETER.

 HRESULT PutClass(
   [in] IWbemClassObject* pObject,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [out, in, unique] IWbemCallResult** ppCallResult
 );

pObject: MUST be a pointer to an IWbemClassObject interface pointer that MUST contain the class information to create a new class or update an existing class. This parameter MUST NOT be NULL.

lFlags: Specifies the behavior of the PutClass 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 match a flag 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 it creates or updates the CIM class.<34>

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

WBEM_FLAG_RETURN_IMMEDIATELY

0x00000010

If this bit is not set, the server MUST make the method call synchronously.

If this bit is set, the server MUST make the method call semisynchronously.

WBEM_FLAG_UPDATE_ONLY

0x00000001

The server MUST update a CIM class pObject if the CIM class 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 class pObject.

WBEM_FLAG_CREATE_ONLY

0x00000002

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

WBEM_FLAG_UPDATE_FORCE_MODE

0x00000040

The server MUST update the class even if conflicting child classes exist.

WBEM_FLAG_UPDATE_SAFE_MODE

0x00000020

The server MUST update the class as long as the change does not cause any conflicts with existing child classes or instances.

This flag is mutually exclusive with WBEM_FLAG_UPDATE_FORCE_MODE. If none of these flags are set, the server MUST update the class if there is no derived class, if there is no instance for that class, or if the class is unchanged.

pCtx: MUST be a pointer to an IWbemContext interface, which MUST contain additional information that the client wants to provide to the server about the CIM class that is referred to by the pObject parameter. If the pCtx parameter is NULL, it MUST be ignored.

ppCallResult: If the input parameter is non-NULL, the server MUST return WBEM_S_NO_ERROR and IWbemCallResult MUST deliver the result of the requested operation (regardless whether WBEM_FLAG_RETURN_IMMEDIATELY is set). The output parameter MUST be filled according to the state of the lFlags parameter (whether WBEM_FLAG_RETURN_IMMEDIATELY is set) as listed in the following table.

Flag state

Operation Started Successfully

Operation Failed to Start

WBEM_FLAG_RETURN_IMMEDIATELY is not set.

MUST be set to IWbemCallResult if the input parameter is non-NULL.

MUST be set to NULL if the input parameter is non-NULL.

WBEM_FLAG_RETURN_IMMEDIATELY is set.

This parameter MUST NOT be NULL upon input. If NULL, the server MUST return WBEM_E_INVALID_PARAMETER. On output, the parameter MUST contain the IWbemCallResult interface pointer.

MUST be set to NULL if the input parameter is non-NULL.

If the ppCallResult input parameter is NULL and WBEM_FLAG_RETURN_IMMEDIATELY is not set, the server MUST deliver the result of the requested operation synchronously.

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 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 MUST first determine whether the class is dynamic or static. If the class exists in the ClassTable for the namespace, then it is static when InstanceProviderId is NULL and dynamic otherwise. If the class does not exist in the ClassTable, then WMI MUST iterate through each entry in ProviderTable with IsClassProvider set to TRUE, calling the IsClassSupported entrypoint (described in section 3.1.4.17.14). If a provider returns TRUE, then the algorithm is terminated and the class is dynamic. Otherwise, the class is static.

If the CIM class 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 class being updated is static, the security principal that makes the call MUST have WBEM_FULL_WRITE access to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

The server MUST return WBEM_E_CANNOT_BE_SINGLETON if an attempt is made to mark a class as a singleton that has a nonsingleton superclass or a class with key properties.

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

In response to the IWbemServices::PutClass method, the server MUST evaluate the pObject parameter and MUST add or update this class into the current namespace. The method MUST fail if pObject represents a read-only class, if the method parameters or their combinations are not valid as specified in this section, or if the server is unable to execute the method. The method MUST fail with WBEM_E_NOT_FOUND if pObject property __SUPERCLASS is specified but not found in ClassTable.

If a new class is added or an existing class is updated successfully, ClassTable MUST be updated with the changes. If pObject property __SUPERCLASS is specified, DerivedClassTable MUST point to the entry in the ClassTable representing the superclass.

If the CIM class referred by pObject is a new entry in the ClassTable, the server MUST generate a __ClassCreationEvent event object upon successful creation of the class.

If the CIM class referred by pObject already exists in the ClassTable prior to this method call, the server MUST generate a __ClassModificationEvent event object upon successfully updating the class information.

The successful synchronous method execution MUST return WBEM_S_NO_ERROR.

The semisynchronous method execution MUST follow the rules that are specified in section 3.1.1.1.2.

The failed method execution MUST set output parameters to NULL and MUST return an error in the format specified in section 2.2.11.

The server MUST ensure that the value referred by __CLASS conforms to CLASS-NAME in section 2.2.1.1. In addition:

  • If the value has an underscore character ("_") as the first character, the server MUST return WBEM_E_INVALID_OPERATION.

  • If the value has an underscore character ("_") as the last character prior to NULL, the server MUST return WBEM_E_INVALID_OBJECT.

  • The server SHOULD enforce a maximum length for the _CLASS property (2.2) of the object pointed to by the pObject parameter, and return WBEM_E_QUOTA_VIOLATION if the limit is exceeded.<35>