IWbemServices：:P utInstanceAsync 方法 (wbemcli.h)
IWbemServices：:P utInstanceAsync方法會以非同步方式建立或更新現有類別的實例。 更新確認或錯誤報表是透過呼叫端所實作的 IWbemObjectSink 介面來提供。
語法
HRESULT PutInstanceAsync(
[in] IWbemClassObject *pInst,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
參數
[in] pInst
要寫入 WMI 存放庫之實例的指標。 呼叫端無法在完成此呼叫時假設參考計數。
[in] lFlags
指定如果實例目前不存在，呼叫端是否想要建立實例。
實作執行個體提供者時，您可以選擇傳回WBEM_E_PROVIDER_NOT_CAPABLE來支援lFlags中的有限旗標數目。
這個屬性可以有下列一或多個值。
WBEM_FLAG_CREATE_OR_UPDATE
如果實例不存在或已存在，此旗標會導致建立這個實例。
WBEM_FLAG_UPDATE_ONLY
更新現有的實例。
WBEM_FLAG_CREATE_ONLY
此旗標僅適用于實例建立。 如果類別已經存在，呼叫就會失敗。
WBEM_FLAG_SEND_STATUS
此旗標會向 Windows 管理註冊要求，以透過 IWbemObjectSink：：SetStatus的用戶端實作接收中繼狀態報表。 提供者實作必須支援此旗標的中繼狀態報表，才能變更行為。
WBEM_FLAG_USE_AMENDED_QUALIFIERS
如果設定此旗標，WMI 不會儲存任何具有 修改 類別的限定詞。 如果未設定此旗標，則會假設此物件並未當地語系化，而且所有限定詞都會與此實例一起儲存。
[in] pCtx
描述用戶端是否要求部分實例更新或完整實例更新的指標。 部分實例更新會修改 實例屬性的子集。 相反地，完整實例更新會修改所有屬性。 如果 為 Null，此參數表示呼叫端應用程式要求完整實例更新。 否則，這是產生類別實例之動態類別提供者所需的 IWbemCoNtext 物件的指標。 如需此參數的詳細資訊，請參閱 呼叫 WMI。
[in] pResponseHandler
呼叫端 IWbemObjectSink實作的指標。 當此處理程式使用 IWbemObjectSink：：SetStatus 方法可供使用時，就會收到此呼叫的狀態。 如果傳回任何錯誤碼，則不會使用提供的 IWbemObjectSink 指標。 如果 傳回WBEM_S_NO_ERROR ，則會呼叫使用者的 IWbemObjectSink 實作來指出作業的結果。 如果WBEM_S_NO_ERROR傳回，Windows 管理只會在指標上呼叫AddRef。 如果錯誤碼傳回，則參考計數與專案相同。 如需如何進行非同步呼叫的詳細資訊，請參閱 呼叫 方法。
傳回值
這個方法會傳回 HRESULT ，指出方法呼叫的狀態。 下列清單列出 HRESULT中包含的值。
請注意，如果 PutInstanceAsync 傳回 WBEM_S_NO_ERROR，WMI 會等候回應處理常式的 SetStatus 方法的結果。 WMI 會在本機連線上無限期等候，或直到遠端連線逾時為止。
如果網路問題造成您失去 Windows 管理遠端連線，也可能傳回 COM 特定的錯誤碼。
備註
呼叫 PutInstanceAsync 的用戶端一律必須使用其 IWbemObjectSink：：Indicate 方法回報呼叫的結果。
當 pInst 所指向的實例屬於衍生自其他類別的類別時， PutInstanceAsync 的成功取決於負責父類別的提供者成功。 例如，如果pInst屬於ClassB 和 ClassB衍生自ClassA，則對ClassA提供者所實作的PutInstanceAsync方法呼叫必須成功，ClassB上的更新作業才能成功。 如需詳細資訊，請參閱 IWbemServices：:P utInstance中的。
實作執行個體提供者時，如果實例的索引鍵屬性設定為 Null， PutInstanceAsync 應該選擇保證在 類別內是唯一的值。 當 WMI 服務使用 Null 金鑰屬性更新實例的要求時，它會在內部產生 GUID 並將它指派給金鑰屬性。 此外，當更新的實例屬於子類別時，作業的成功取決於對階層中較高類別負責之每個提供者的 PutInstanceAsync 呼叫成功。 在您確定所有其他提供者都成功之前，請勿傳回 WBEM_S_NO_ERROR 。 如需詳細資訊，請參閱 IWbemServices：:P utInstance。
支援部分更新的執行個體提供者必須檢查 __PUT_EXTENSIONS內容值 是否存在。 系統內容值是由 WMI 所定義的值，具有特定意義、由用戶端應用程式設定，且由執行個體提供者支援。 IWbemCoNtext介面可讓您存取系統內容值和其他提供者特定的內容值。 下列清單列出支援部分實例更新作業的內容值。
系統會呼叫 IWbemObjectSink：：SetStatus 方法，以指出結果集的結尾。 它也可能呼叫，而不需對 IWbemObjectSink：：指出 發生錯誤狀況。
由於回呼可能不會與用戶端所需的相同驗證層級傳回，因此建議您使用半非同步而非非同步通訊。 如果您需要非同步通訊，請參閱 呼叫 方法。
如需以半非同步方式使用方法的詳細資訊，請參閱 IWbemServices：:P utInstance 和 呼叫方法。
| 系統內容值 | 描述 |
|---|---|
|
__PUT_EXTENSIONS
(VT_BOOL) |
用戶端應用程式已設定一或多個其他系統內容值，以提供更新作業的詳細資訊。 |
|
__PUT_EXT_STRICT_NullS
(VT_BOOL) |
執行個體提供者必須強制在適當時 VT_Null 屬性的設定，並在失敗時引發錯誤。 |
|
__PUT_EXT_PROPERTIES
| (VT_ARRAY VT_BSTR) |
包含要更新的屬性清單。 執行個體提供者應該忽略所有其他屬性。 |
|
__PUT_EXT_ATOMIC
(VT_BOOL) |
所有更新都必須成功，或執行個體提供者必須還原回來。 沒有部分成功。 |
實作執行個體提供者時，您應該以下列方式回應pCtx中的Null屬性：
- 如果屬性類型 VT_Null，提供者可以忽略屬性，而不進行變更或失敗作業。
- 如果屬性類型不是 VT_Null 且無法更新屬性，提供者應該傳回錯誤，因為提供者必須以新的值更新屬性。
實作非同步作業時，直到您在pResponseHandler上執行的任何AddRef之後，非同步作業才會完成。 即使您在pResponseHander上呼叫SetStatus，也是如此。 如果 pResponseHandler 外泄，則根據您的實作，任何同步或半同步用戶端也不會完成且可能停止回應。
即使在重大情況下，您也必須釋放分離提供者的參考。 這是因為在同步和半同步案例中，WMI 服務擁有 pResponseHandler的實作：即使您的分離提供者的進程結束時，用戶端仍然不會回應。
範例
下列範例說明如何建構 PutInstanceAsync。
HRESULT CStdProvider::PutInstanceAsync(
/* [in] */ IWbemClassObject __RPC_FAR *pInst,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
// You must implement the InstanceIsValid method
// to check to see if the instance in the pInst variable
// is valid.
if (InstanceIsValid(lFlags, pInst))
{
return WBEM_S_NO_ERROR;
}
return WBEM_E_PROVIDER_NOT_CAPABLE;
}
規格需求
| 最低支援的用戶端 | 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 |