建立或更新已存在類別的實例。 實例會寫入 WMI 存放庫。
備註
此 API 僅供內部使用。 它不是用來從開發者程式碼中取得的。
語法
HRESULT PutInstanceWmi (
[in] IWbemClassObject* pInst,
[in] long lFlags,
[in] IWbemContext* pCtx,
[out] IWbemCallResult** ppCallResult
);
參數
pInst
[在]指向要寫入的實例的指標。
lFlags
[在]影響此函式行為的多個旗標組合。 以下值在 WbemCli.h 標頭檔案中定義，或者你可以在程式碼中將它們定義為常數：
| 常數 | 價值觀 | Description |
|---|---|---|
WBEM_FLAG_USE_AMENDED_QUALIFIERS |
0x20000 | 如果設定好，WMI 不會儲存任何帶有 Amended 風味的限定條件。 若未設定，則假設該物件未被本地化，所有限定符皆與此實例一同儲存。 |
WBEM_FLAG_CREATE_OR_UPDATE |
0 | 如果實例不存在就建立，若已存在則覆寫。 |
WBEM_FLAG_UPDATE_ONLY |
1 | 更新實例。 該實例必須存在，呼叫才會成功。 |
WBEM_FLAG_CREATE_ONLY |
2 | 建立實例。 如果該實例已經存在，呼叫就會失敗。 |
WBEM_FLAG_RETURN_IMMEDIATELY |
0x10 | 該旗標會產生半同步通話。 |
pCtx
[在]通常，此值為 null。 否則，它就是指向 IWbemContext 實例的指標，供提供所需類別的提供者使用。
ppCallResult
[出]若 null，則該參數未被使用。 若lFlags包含 WBEM_FLAG_RETURN_IMMEDIATELY，函數立即返回 。WBEM_S_NO_ERROR 參數 ppCallResult 接收到指向一個新的 IWbemCallResult 物件的指標。
返回值
以下由此函式回傳的值定義在 WbemCli.h 標頭檔案中，或你也可以將它們定義為程式碼中的常數：
| 常數 | 價值觀 | Description |
|---|---|---|
WBEM_E_ACCESS_DENIED |
0x80041003 | 使用者無權更新指定類別的實例。 |
WBEM_E_FAILED |
0x80041001 | 發生了未說明的錯誤。 |
WBEM_E_INVALID_CLASS |
0x80041010 | 支援此實例的類別不成立。 |
WBEM_E_ILLEGAL_NULL |
0x80041028 | a null 被指定為一個不能是 null的性質，例如以 Indexed or Not_Null 限定符標記的性質。 |
WBEM_E_INVALID_OBJECT |
0x8004100f | 該實例不具效性。 （例如，呼叫類別會 PutInstanceWmi 回傳此值。） |
WBEM_E_INVALID_PARAMETER |
0x80041008 | 參數不成立。 |
WBEM_E_ALREADY_EXISTS |
0x80041019 |
WBEM_FLAG_CREATE_ONLY旗幟已被指定，但實例本身已經存在。 |
WBEM_E_NOT_FOUND |
0x80041002 |
WBEM_FLAG_UPDATE_ONLY 在 中指定 lFlags，但該實例不存在。 |
WBEM_E_OUT_OF_MEMORY |
0x80041006 | 記憶體不足以完成操作。 |
WBEM_E_SHUTTING_DOWN |
0x80041033 | WMI 可能已經停止並重新啟動。 再打一次 ConnectServerWmi 。 |
WBEM_E_TRANSPORT_FAILURE |
0x80041015 | 目前程序與 WMI 之間的遠端程序呼叫（RPC）連結已失效。 |
WBEM_S_NO_ERROR |
0 | 函式呼叫成功。 |
備註
此函式會包裹呼叫 IWbemServices：:P utInstance 方法。
這個 PutInstanceWmi 函式只支援建立實例並更新現有類別的實例。 根據參數的 pCtx 設定方式，實例的部分或全部屬性會被更新。
當指向的 pInst 實例屬於子類別時，Windows 管理會呼叫所有負責該子類別衍生類別的提供者。 所有這些提供者都必須成功，原始 PutInstanceWmi 請求才會成功。 支援階層頂端類別的提供者會先被呼叫。 呼叫順序會依照最頂層類別的子類別繼續，從上到下，直到 Windows 管理系統找到擁有該實例 pInst的提供者。
Windows 管理不會呼叫實例中任何子類別的提供者。
當應用程式必須更新屬於類別階層的實例時，參數 pInst 必須指向包含要修改屬性的實例。 也就是說，考慮一個屬於 ClassB 的目標實例。 該 ClassB 實例源自 ClassA，並 ClassA 定義了 PropA 的性質。 如果應用程式想在實ClassB例中更改 的PropA值，必須設定pInst為該實例，而非 ClassA 的實例。
不允許呼叫 PutInstanceWmi 抽象類別的實例。
如果函式呼叫失敗，你可以透過呼叫 GetErrorInfo 函式來取得額外的錯誤資訊。
需求
平台：請參閱系統需求。
標題： WMINet_Utils.idl
.NET Framework 版本： 自 4.7.2 版本起可用
