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

發行項
03/03/2024

IWbemServices：:P utClassAsync 方法會建立新的類別，或更新現有的類別。 pObject 參數指定的類別必須以所有必要的屬性值正確初始化。呼叫會立即傳回。成功或失敗會提供給 pResponseHandler 參數所指定的物件接收。

語法

HRESULT PutClassAsync(
  [in] IWbemClassObject *pObject,
  [in] long             lFlags,
  [in] IWbemContext     *pCtx,
  [in] IWbemObjectSink  *pResponseHandler
);

參數

[in] pObject

包含類別定義的物件指標。

[in] lFlags

下列一或多個值有效。

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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

WBEM_FLAG_CREATE_OR_UPDATE

如果這個類別不存在或已存在，此旗標會導致建立這個類別。

WBEM_FLAG_UPDATE_ONLY

匯報現有的類別。

WBEM_FLAG_CREATE_ONLY

此旗標僅適用於類別建立。如果類別已經存在，呼叫就會失敗。

WBEM_FLAG_SEND_STATUS

此旗標會向 Windows 管理註冊要求，以透過用戶端實作 IWbemObjectSink：：SetStatus 接收中繼狀態報告。提供者實作必須支援此旗標的中繼狀態報告，才能變更行為。

WBEM_FLAG_OWNER_UPDATE

發送提供者必須在呼叫 PutClassAsync 時指定此旗標，以指出此類別已變更。

WBEM_FLAG_UPDATE_COMPATIBLE

如果沒有衍生類別，而且該類別沒有實例，此旗標可讓類別更新。如果變更只是對非重要限定符 (，則它也會允許在所有情況下更新，例如描述限定符) 。這是此呼叫的預設行為，用於與舊版 Windows 管理相容。如果類別具有執行個體或重要限定詞發生變更，則更新會失敗。

WBEM_FLAG_UPDATE_SAFE_MODE

即使有子類別，此旗標仍允許更新類別，只要變更不會與子類別發生任何衝突即可。此旗標允許的更新範例是將新的屬性新增至任何子類別中先前未提及的基類。如果類別有執行個體，更新就會失敗。

WBEM_FLAG_UPDATE_FORCE_MODE

此旗標會在衝突的子類別存在時強制更新類別。如果類別限定元是在子類別中定義，而且基類嘗試新增與現有限定符衝突的相同限定符，則此旗標會強制更新。在強制模式中，刪除子類別中的衝突限定符，即可解決此衝突。

[in] pCtx

通常 為 NULL。否則，這是 IWbemContext 物件的指標，可由接收要求類別的提供者使用。內容物件中的值必須在有問題的提供者檔中指定。如需此參數的詳細資訊，請參閱呼叫 WMI。

[in] pResponseHandler

呼叫端 IWbemObjectSink 實作的指標。當狀態變成可用時，此處理程式會使用 SetStatus 方法接收 Put 要求的狀態。如果傳回任何錯誤碼，則不會使用提供的 IWbemObjectSink 指標。如果 傳回WBEM_S_NO_ERROR ，則會呼叫使用者的 IWbemObjectSink 實作來指出作業的結果。 Windows 管理只會在傳回WBEM_S_NO_ERROR時呼叫 AddRef 至指標。如果錯誤碼傳回，則參考計數與專案相同。如需此參數的詳細說明，請參閱呼叫方法。

傳回值

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

其他狀態或錯誤碼會回報給 pReponseHandler 參數所指定的物件接收。

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

請注意，如果 PutInstanceAsync 傳回 WBEM_S_NO_ERROR，WMI 會等候回應處理程式的 SetStatus 方法的結果。 WMI 會在本機連線上無限期等候，或直到遠端連線逾時為止。

因為傳回 WBEM_E_FAILED 導致其他提供者沒有機會建立類別，所以只有在類別提供者失敗時，才應該傳回它，因為稍後可能會成功。

注意如果您在用戶端或提供者正在使用類別定義時變更類別定義，將會導致無法預期的行為。 IWbemServices：:P utClass 方法只有在目前沒有用戶端或提供者目前使用類別時，才應該用來建立或更新類別。

備註

如果為一個特定類別安裝多個類別提供者，WMI 將無法辨識哪些類別提供者能夠建立該類別。

系統會呼叫 IWbemObjectSink：：SetStatus 方法，以指出結果集的結尾。它也可能呼叫，而不需對 IWbemObjectSink：：指出發生錯誤狀況。

由於回呼可能不會與用戶端所需的相同驗證層級傳回，因此建議您使用半異步而非異步通訊。如果您需要異步通訊，請參閱呼叫方法。

如需以半同步方式使用方法的詳細資訊，請參閱 IWbemServices：:P utClass 和呼叫方法。

範例

下列程式代碼範例描述 PutClassAsync 的簡單實作。

HRESULT CStdProvider::PutClassAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pObject,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    // You must implement the ClassIsValid function yourself to
    // determine if the class contains a valid instance
   if (ClassIsValid(lFlags, pObject))
   {
       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

另請參閱

呼叫方法

建立類別

IWbemServices

IWbemServices：:P utClass