IWbemServices：：CreateInstanceEnumAsync 方法 (wbemcli.h)

發行項
03/13/2024

IWbemServices：：CreateInstanceEnumAsync 方法會建立列舉值，根據使用者指定的選取準則，以異步方式傳回指定類別的實例。此方法支援簡單的 WMI 查詢語言 (WQL) 查詢。您可以使用 IWbemServices：：ExecQueryAsync 方法來處理更複雜的查詢。

語法

HRESULT CreateInstanceEnumAsync(
  [in] const BSTR      strFilter,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

參數

[in] strFilter

包含所需實例之類別名稱的有效 BSTR 。此參數不可為 NULL。

[in] lFlags

此參數可以是下列其中一個值。

WBEM_FLAG_USE_AMENDED_QUALIFIERS

如果設定此旗標，Windows Management Instrumentation (WMI) 會擷取儲存在目前連線地區設定之當地語系化命名空間中已修改的限定符。如果未設定，只會擷取儲存在立即命名空間中的限定符。

WBEM_FLAG_DEEP

此旗標會強制列舉包含這個和階層中所有子類別的實例。

WBEM_FLAG_SHALLOW

此旗標會強制列舉只包含這個類別的純實例，但不包括子類別的所有實例，這些實例會提供在此類別中找不到的屬性。

WBEM_FLAG_SEND_STATUS

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

WBEM_FLAG_BIDIRECTIONAL

此旗標會導致 Windows 管理保留列舉物件的指標，直到客戶端釋放列舉值為止。

WBEM_FLAG_DIRECT_READ

此旗標會導致直接存取指定之類別的提供者，而不需考慮其父類別或子類別。

[in] pCtx

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

[in] pResponseHandler

呼叫端實作 IWbemObjectSink 的指標。這個處理程式會在物件變成可用時接收物件。如果傳回任何錯誤碼，則不會使用提供的 IWbemObjectSink 指標。如果 傳回WBEM_S_NO_ERROR ，則會呼叫使用者的 IWbemObjectSink 實作來指出作業的結果。如果WBEM_S_NO_ERROR傳回，Windows 管理只會在指標上呼叫 AddRef。如果錯誤碼傳回，則參考計數會與輸入時相同。如需詳細資訊，請參閱呼叫方法。

傳回值

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

失敗時，您可以從 COM 函式 GetErrorInfo 取得更多資訊。

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

實例提供者可以使用 CreateInstanceEnumAsync 的傳回碼，或透過 pResponseHandler 呼叫 SetStatus 來報告成功或失敗。如果您選擇呼叫 SetStatus，則透過 pResponseHandler 傳送的 傳回碼優先。

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

備註

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

由於回呼可能不會在用戶端所需的相同驗證層級傳回，因此建議您使用半同步而非異步通訊。

如需詳細資訊，請參閱 IWbemServices：：CreateInstanceEnum 和呼叫方法。

範例

下列範例示範如何實作 CreateInstanceEnumAsync。

#define NUM_OF_INSTANCES 3

HRESULT CStdProvider::CreateInstanceEnumAsync( 
            /* [in] */ BSTR strClass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0; 
    IWbemClassObject *pNextInst = 0;

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

         // Deliver the class to WMI.
         pResponseHandler->Indicate(1, &pNextInst);
         pNextInst->Release();
    }

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

在上述範例中，實例提供者會從 WMI 取得線程，以執行任何必要的作業。您可能想要呼叫接收 AddRef 方法，並建立另一個線程來傳遞結果集中的物件。建立另一個線程可讓目前的線程返回 WMI，而不需要耗盡線程集區。提供者是否透過雙線程設計選擇單一線程設計，取決於提供者計劃使用WMI線程的時間長度。沒有固定的規則。測試可協助您判斷設計如何影響 WMI 效能。

規格需求

需求	值
最低支援的用戶端	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：：CreateInstanceEnum