IWbemServices：:P utInstance 方法 (wbemcli.h)

發行項
03/03/2024

IWbemServices：:P utInstance 方法會建立或更新現有類別的實例。執行個體是寫入到 WMI 存放庫。

語法

HRESULT PutInstance(
  [in]  IWbemClassObject *pInst,
  [in]  long             lFlags,
  [in]  IWbemContext     *pCtx,
  [out] IWbemCallResult  **ppCallResult
);

參數

[in] pInst

要寫入之實例的指標。呼叫端無法在完成此呼叫時假設參考計數。

[in] lFlags

您可以設定下列一或多個值。

WBEM_FLAG_CREATE_OR_UPDATE

如果實例不存在或已存在，則此旗標會導致建立實例。

WBEM_FLAG_UPDATE_ONLY

此旗標會導致此呼叫更新。執行個體必須存在，才能成功呼叫。

WBEM_FLAG_CREATE_ONLY

此旗標僅用於建立。如果執行個體已經存在，則呼叫會失敗。

WBEM_FLAG_RETURN_IMMEDIATELY

此旗標會使此為半異步呼叫。如需詳細資訊，請參閱呼叫方法。

WBEM_FLAG_USE_AMENDED_QUALIFIERS

如果設定此旗標，WMI 不會儲存任何具有修改類別的限定符。如果未設定此旗標，則會假設此對象並未本地化，而且所有限定符都會與此實例一起儲存。

[in] pCtx

通常 為 NULL，表示實例中的每個屬性都會更新。否則，這是 IWbemContext 物件的指標，其中包含實例的詳細資訊。內容對象中的數據必須由負責實例的提供者記載。非 NULLIWbemContext 物件可以指出部分實例更新是否支援。

如需如何支援完整和部分實例更新的詳細資訊，請參閱 IWbemServices：:P utInstanceAsync。如需要求完整或部分實例更新作業的詳細資訊，請參閱修改實例屬性。

[out] ppCallResult

如果 為 NULL，則不會使用此參數。如果 lFlags 參數包含 WBEM_FLAG_RETURN_IMMEDIATELY，此呼叫會立即傳回 WBEM_S_NO_ERROR。 ppCallResult 參數接著會接收新 IWbemCallResult 物件的指標，該物件可以使用 IWbemCallResult：：GetCallStatus 輪詢以取得結果。

傳回值

這個方法會傳回 HRESULT ，指出方法呼叫的狀態。下列清單列出 HRESULT 中包含的值。

如果網路問題造成您失去 Windows 管理遠端連線，也可能傳回 COM 特定的錯誤碼。

備註

應用程式和提供者會呼叫 PutInstance 來建立或更新現有類別的實例。根據 pCtx 參數的設定方式，實例的某些或所有屬性都會更新。如需如何支援部分實例更新的詳細資訊，請參閱 IWbemServices：:P utInstanceAsync。如需要求部分實例更新的詳細資訊，請參閱修改實例屬性。

PutInstance 方法僅支援建立實例和更新實例。它不支持行動實例。也就是說，呼叫端無法將 pInst 參數設定為具有與同層級類別中另一個實例相同索引鍵的實例。例如，假設 ClassA 是 ClassB 和 ClassC 的基類。 ClassA 類別會將 KeyProp 屬性定義為其索引鍵，而 ClassB 的實例已將 KeyProp 設定為 1。若要建立將 KeyProp 設為 1 的 ClassC 實例，應用程式必須先呼叫 DeleteInstance 來刪除 ClassB 實例，然後使用 PutInstance 儲存 ClassC 實例。

當 pInst 指向的實例屬於子類別時，Windows 管理會呼叫負責子類別衍生類別的所有提供者。所有這些提供者都必須成功，原始 PutInstance 要求才能成功。系統會先呼叫支援階層中最上層類別的提供者。呼叫順序會繼續進行最上層類別的子類別，並從上到下繼續進行，直到 Windows Management 到達擁有 pInst 所指向實例的類別提供者為止。

Windows 管理不會呼叫執行個體之任何子類別的提供者。因此，如果應用程式想要變更繼承屬性的值，應用程式必須在子類別的完整實例上呼叫 PutInstance ，而不是父類別的對應實例。

當應用程式必須更新屬於類別階層的實例時， pInst 參數必須指向包含要修改之屬性的實例。也就是說，請考慮屬於 ClassB 的目標執行個體。 ClassB 執行個體衍生自 ClassA，而 ClassA 會定義 PropA 屬性。如果應用程式想要變更 ClassB 實例中的 PropA 值，它必須將 pInst 設定為該實例，而不是 ClassA 的實例。

不允許在抽象類的實例上呼叫 PutInstance 。

規格需求

需求	值
最低支援的用戶端	Windows Vista
最低支援的伺服器	Windows Server 2008
目標平台	Windows
標頭	wbemcli.h (包含 Wbemidl.h)
程式庫	Wbemuuid.lib
Dll	Fastprox.dll;Esscli.dll;FrameDyn.dll;FrameDynOS.dll;Ntevt.dll;Stdprov.dll;Viewprov.dll;Wbemcomn.dll;Wbemcore.dll;Wbemess.dll;Wbemsvc.dll;Wmipicmp.dll;Wmidcprv.dll;Wmipjobj.dll;Wmiprvsd.dll