<div class="content" name="PutInstance" uuid="5d2e7939-f60c-4891-a339-1bf027a6d3ec"><p>The IWbemServices::PutInstance method creates or updates an
instance of an existing class.</p><p>The PutInstance method <a href="6837a7cb-ba2d-46b1-802c-fce2fd5a6ad6#gt_e127848e-c66d-427d-b3aa-9f904fa4ada7" data-linktype="relative-path">opnum</a> equals 14.</p><dl>
<dd>
<div><pre> HRESULT PutInstance(
   [in] IWbemClassObject* pInst,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [out, in, unique] IWbemCallResult** ppCallResult
 );
</pre></div>
</dd></dl><p><b>pInst: </b>MUST be a pointer to an <a href="46710c5c-d7ab-4e4c-b4a5-ebff311fdcd1" data-linktype="relative-path">IWbemClassObject</a> interface
object that MUST contain the class instance that the client wants to create or
update. This parameter MUST NOT be NULL.</p><p><b>lFlags: </b>Flags that affect the behavior of the
PutInstance method. Flag behavior MUST be interpreted as specified in the following
table.</p><dl>
<dd>
<p>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.</p>
</dd>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x00020000</td>
  <td>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.</td>
 </tr><tr>
  <td>WBEM_FLAG_RETURN_IMMEDIATELY 0x00000010</td>
  <td>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.</td>
 </tr><tr>
  <td>WBEM_FLAG_UPDATE_ONLY 0x00000001</td>
  <td>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.</td>
 </tr><tr>
  <td>WBEM_FLAG_CREATE_ONLY 0x00000002</td>
  <td>The server MUST create a CIM instance pObject if the CIM instance is not already present.</td>
 </tr></tbody></table>
</dd></dl><p><b>pCtx: </b>This parameter is optional. The <i>pCtx</i>
parameter MUST be a pointer to an <a href="18c8f1a1-652f-43b7-9186-6098bc303a8d" data-linktype="relative-path">IWbemContext</a> interface
object. The <i>pCtx</i> parameter indicates whether the client is requesting a
partial-instance update or a full-instance update. A partial-instance update
modifies a subset of the CIM instance properties. In contrast, a full-instance
update modifies all the properties. If NULL, this parameter indicates that the
client application is requesting a full-instance update. When <i>pCtx</i> is
used to perform a partial-instance update, the IWbemContext interface object
MUST be filled in 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.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Property name</p>
   </th>
   <th>
   <p>Type</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>__PUT_EXTENSIONS</td>
  <td>VT_BOOL</td>
  <td>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 and the properties that follow MUST be set as specified in their respective descriptions.</td>
 </tr><tr>
  <td>__PUT_EXT_STRICT_NULLS</td>
  <td>VT_BOOL</td>
  <td>If this property is set to TRUE, the server MUST force the setting of properties to NULL. This parameter is optional.</td>
 </tr><tr>
  <td>__PUT_EXT_PROPERTIES</td>
  <td>VT_ARRAY | VT_BSTR</td>
  <td>Contains a CIM property list to update. The server MUST ignore the properties that are not listed. To perform a partial instance update, the list of properties MUST be specified.</td>
 </tr><tr>
  <td>__PUT_EXT_ATOMIC</td>
  <td>VT_BOOL</td>
  <td>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 that was updated. On failure, not a single change MUST remain. The operation is successful when all properties are updated.</td>
 </tr></tbody></table>
</dd></dl><p><b>ppCallResult: </b>If the input parameter is
non-NULL, the server MUST return WBEM_S_NO_ERROR and <a href="23ec4065-3fbe-4e39-baef-69e22c285623" data-linktype="relative-path">IWbemCallResult</a> 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 <i>lFlags</i> parameter (whether
WBEM_FLAG_RETURN_IMMEDIATELY is set) as listed in the following table.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Flag state</p>
   </th>
   <th>
   <p>Operation Started Successfully</p>
   </th>
   <th>
   <p>Operation Failed to Start</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>WBEM_FLAG_RETURN_IMMEDIATELY is not set.</td>
  <td>MUST be set to IWbemCallResult if the input parameter is non-NULL.</td>
  <td>MUST be set to NULL if the input parameter is non-NULL.</td>
 </tr><tr>
  <td>WBEM_FLAG_RETURN_IMMEDIATELY is set.</td>
  <td>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.</td>
  <td>MUST be set to NULL if the input parameter is non-NULL.</td>
 </tr></tbody></table>
</dd>
<dd>
<p>If the <i>ppCallResult</i> input
parameter is NULL and WBEM_FLAG_RETURN_IMMEDIATELY is not set, the server MUST
deliver the result of the requested operation synchronously.</p>
</dd></dl><p><b>Return Values: </b>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 <a href="a2899649-a5a3-4b13-9ffa-d8394dcdac63" data-linktype="relative-path">2.2.11</a>) to indicate the
successful completion of the method.</p><dl>
<dd>
<p><b>WBEM_S_NO_ERROR</b> (0x00)</p>
</dd></dl><p>The <a href="6837a7cb-ba2d-46b1-802c-fce2fd5a6ad6#gt_f3ef2572-95cf-4c5c-b3c9-551fd648f409" data-linktype="relative-path">security
principal</a> that makes the call MUST have WBEM_REMOTE_ENABLE and WBEM_ENABLE
accesses to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.</p><p>If the CIM instance being updated is <a href="6837a7cb-ba2d-46b1-802c-fce2fd5a6ad6#gt_b11172af-9369-448d-9722-444eb52b21cb" data-linktype="relative-path">dynamic</a>, the security
principal that makes the call MUST have WBEM_WRITE_PROVIDER access to the
namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.</p><p>If the CIM instance being created or updated is dynamic, the
server MUST obtain <b>SupportsPut</b> for the corresponding provider in the <b>ProviderTable</b>.
If <b>SupportsPut</b> is FALSE, the server MUST return
WBEM_E_PROVIDER_NOT_CAPABLE.</p><p>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.</p><p>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.</p><p>If the <a href="6837a7cb-ba2d-46b1-802c-fce2fd5a6ad6#gt_633b12d4-e2c4-442f-95ff-4b2b5d708ed5" data-linktype="relative-path">CIM
class</a> of the instance being created has a parent class that is not
abstract, the server MUST fail the operation with WBEM_E_NOT_FOUND. <a href="https://go.microsoft.com/fwlink/?LinkId=89848" data-linktype="external">[DMTF-DSP0004]</a>
requires that the operation MUST succeed whenth e parent CIM class is abstract.</p><p>In response to the IWbemServices::PutInstance method, the
server MUST evaluate the <i>pInst</i> parameter as specified in this section.
It MUST add or update this instance into the current namespace. The method MUST
fail if the following applies: if the server does not allow creation of new
instances for the <i>pInst</i> class or does not allow modification of the instance
that is represented by <i>pInst</i>; 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.</p><p>The successful synchronous method execution MUST return
WBEM_S_NO_ERROR.</p><p>The <a href="6837a7cb-ba2d-46b1-802c-fce2fd5a6ad6#gt_51f3288a-1aea-49f6-96a1-91f368e8b49b" data-linktype="relative-path">semisynchronous</a>
method execution MUST follow the rules as specified in section <a href="c40421d8-b195-4268-884f-a4e74ea58dce" data-linktype="relative-path">3.1.1.1.2</a>.</p><p>The failed method execution MUST set output parameters to
NULL and MUST return an error in the format that is specified in section
2.2.11.</p><p>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.<a id="Appendix_A_Target_42"></a><a aria-label="Product behavior note 42" href="27182640-aa3f-43b6-941f-a77d25f798e8#Appendix_A_42" data-linktype="relative-path">&lt;42&gt;</a></p></div>