PutInstanceWmi 函式
建立或更新現有類別的執行個體。 執行個體是寫入到 WMI 存放庫。
注意
此 API 僅供內部使用。 不是要讓您在開發人員程式碼中使用。
語法
HRESULT PutInstanceWmi (
[in] IWbemClassObject* pInst,
[in] long lFlags,
[in] IWbemContext* pCtx,
[out] IWbemCallResult** ppCallResult
);
參數
pInst
[in] 所要寫入的執行個體指標。
lFlags
[in] 影響此函式行為的旗標組合。 下列值定義於 WbemCli.h 標頭檔中，或者，您可以將其定義為程式碼中的常數：
| 常數 | 值 | 描述 |
|---|---|---|
WBEM_FLAG_USE_AMENDED_QUALIFIERS |
0x20000 | 如果設定，WMI 不會儲存任何變體已修改過的限定詞。 如果未設定，則會假設此物件並未當地語系化，而且所有限定詞都會與此執行個體一起儲存。 |
WBEM_FLAG_CREATE_OR_UPDATE |
0 | 如果執行個體不存在，則會建立執行個體；如果執行個體已經存在，則會加以覆寫。 |
WBEM_FLAG_UPDATE_ONLY |
1 | 更新執行個體。 執行個體必須存在，才能成功呼叫。 |
WBEM_FLAG_CREATE_ONLY |
2 | 建立執行個體。 如果執行個體已經存在，則呼叫會失敗。 |
WBEM_FLAG_RETURN_IMMEDIATELY |
0x10 | 旗標會造成半同步呼叫。 |
pCtx
[in] 一般而言，此值為 null。 否則會是指向 IWbemContext 執行個體的指標，可供要求類別的提供者使用。
ppCallResult
[out] 如果是 null，則表示此參數未使用。 如果 lFlags 包含 WBEM_FLAG_RETURN_IMMEDIATELY，則函式會立即傳回並出現 WBEM_S_NO_ERROR。 ppCallResult 參數會接收指向新 IWbemCallResult 物件的指標。
傳回值
此函式傳回的下列值定義於 WbemCli.h 標頭檔中，或者，您可以將其定義為程式碼中的常數：
| 常數 | 值 | 描述 |
|---|---|---|
WBEM_E_ACCESS_DENIED |
0x80041003 | 使用者沒有可供更新指定類別執行個體的權限。 |
WBEM_E_FAILED |
0x80041001 | 發生未指定的錯誤。 |
WBEM_E_INVALID_CLASS |
0x80041010 | 支援這個執行個體的類別無效。 |
WBEM_E_ILLEGAL_NULL |
0x80041028 | 將 null 值指定給了不能是 null 的屬性，例如由 Indexed 或 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 | 在 lFlags 中指定了 WBEM_FLAG_UPDATE_ONLY，但執行個體不存在。 |
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::PutInstance 方法發出的呼叫。
PutInstanceWmi 函式僅支援建立執行個體和更新現有類別的執行個體。 視 pCtx 參數的設定方式而定，執行個體的某些或所有屬性都會更新。
當 pInst 所指向的執行個體屬於某個子類別時，Windows 管理會呼叫負責子類別衍生來源類別的所有提供者。 這些提供者全都必須成功，原始的 PutInstanceWmi 要求才能成功。 系統會先呼叫支援階層中最上層類別的提供者。 呼叫順序會繼續執行最上層類別的子類別，由上到下進行，直到 Windows Management 到達擁有 pInst 所指向執行個體之類別的提供者為止。
Windows 管理不會呼叫執行個體之任何子類別的提供者。
當應用程式必須更新屬於類別階層的執行個體時，pInst 參數必須指向包含要修改之屬性的執行個體。 也就是說，請考慮屬於 ClassB 的目標執行個體。 ClassB 執行個體衍生自 ClassA，而 ClassA 會定義 PropA 屬性。 如果應用程式想要變更 ClassB 執行個體中的 PropA 值，則必須將 pInst 設定為該執行個體，而不是設定為 ClassA 的執行個體。
不允許在抽象類別的執行個體上呼叫 PutInstanceWmi。
如果函式呼叫失敗，您可以藉由呼叫 GetErrorInfo 函式來取得其他錯誤資訊。
規格需求
平台：請參閱系統需求。
標頭：WMINet_Utils.idl
.NET Framework版本：自 4.7.2 起提供
