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 且無法更新屬性，提供者應該傳回錯誤，因為提供者必須以新的值更新屬性。
如果 pCtx 不是 Null ，而且指向有效的內容資訊，則呼叫端應用程式會要求部分實例更新。 如同先前一樣，不支援部分實例更新的執行個體提供者應該傳回 WBEM_E_PROVIDER_NOT_CAPABLE來失敗作業。

實作非同步作業時，直到您在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

另請參閱

呼叫方法

建立實例

IWbemCoNtext

IWbemServices