IWbemServices：：ExecQueryAsync 方法 (wbemcli.h)

發行項
08/27/2023

IWbemServices：：ExecQueryAsync方法會執行查詢以非同步方式擷取物件。

語法

HRESULT ExecQueryAsync(
  [in] const BSTR      strQueryLanguage,
  [in] const BSTR      strQuery,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

參數

[in] strQueryLanguage

有效的 BSTR ，其中包含 Windows Management Instrumentation (WMI) 支援的其中一種查詢語言。這必須是「WQL」。

[in] strQuery

包含查詢文字的有效 BSTR 。這不可以是 Null。當您實作執行個體提供者時，您的提供者可能會拒絕查詢，因為它太複雜。當提供者判斷查詢太複雜時，WMI 可以使用簡單的查詢重試提供者，或選擇擷取並列舉查詢實例的超集合。

如需建置 WMI 查詢字串的詳細資訊，請參閱使用 WQL 查詢和 WQL 參考。

[in] lFlags

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

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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

WBEM_FLAG_BIDIRECTIONAL

此旗標會讓 WMI 保留列舉物件的指標，直到用戶端釋放列舉值為止。

WBEM_FLAG_SEND_STATUS

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

WBEM_FLAG_ENSURE_LOCATABLE

此旗標可確保傳回的物件具有足夠的資訊，讓系統屬性，例如 __PATH、 __RELPATH和 __SERVER為非Null。

WBEM_FLAG_PROTOTYPE

這個旗標用於原型處理。它不會執行查詢，但會傳回看起來像一般結果物件的物件。

WBEM_FLAG_DIRECT_READ

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

[in] pCtx

通常 為 Null。否則，這是 IWbemCoNtext 物件的指標，提供者可用來傳回要求的類別或實例。內容物件中的值必須在提供者的檔中指定。如需此參數的詳細資訊，請參閱呼叫 WMI。

[in] pResponseHandler

呼叫端 IWbemObjectSink實作的指標。此處理程式會在查詢結果集中接收物件，因為它們可供使用。如果傳回任何錯誤碼，則不會使用提供的 IWbemObjectSink 指標。如果 傳回WBEM_S_NO_ERROR ，則會呼叫使用者的 IWbemObjectSink 實作來指出作業的結果。 Windows Management Instrumentation (WMI) 呼叫 IWbemObjectSink：：Indicate 與物件任意次數，後面接著單一呼叫 IWbemObjectSink：：SetStatus 以指出最終狀態。

WMI 只會在WBEM_S_NO_ERROR傳回時呼叫AddRef至指標。當錯誤碼傳回時，參考計數與專案相同。如需非同步呼叫方法的詳細說明，請參閱呼叫方法。

傳回值

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

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

其他錯誤碼會傳回 pResponseHandler 參數所指定的物件接收。

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

完成時，執行個體提供者可以使用ExecQueryAsync的傳回碼，或透過透過pResponseHandler對SetStatus的呼叫來回報成功或失敗。如果您選擇呼叫 SetStatus，則透過 pResponseHandler 傳送的傳回碼優先。

備註

WQL 查詢中可以使用的 AND 和 OR 關鍵字數目有一些限制。複雜查詢中使用的大量 WQL 關鍵字可能會導致 WMI 將 WBEM_E_QUOTA_VIOLATION 錯誤碼傳回為 HRESULT 值。 WQL 關鍵字的限制取決於查詢的複雜程度。

呼叫端的 IWbemObjectSink：：Indicate 方法可以呼叫以報告間歇狀態。系統會呼叫 IWbemObjectSink：：SetStatus 方法，以指出結果集的結尾。

當提供者不支援查詢處理時，WMI 可以支援它。不過，查詢處理的提供者實作可能比 WMI 版本更有效率。若要支援查詢，您的執行個體提供者必須實作 ExecQueryAsync 方法。如果提供者支援 ExecQueryAsync，WMI 會透過 strQuery 參數將簡單的一元 SELECT 查詢直接傳送給提供者，提供者必須剖析查詢並傳回相關的實例。提供者必須剖析查詢，因為 WMI 不會修改查詢，即使查詢是以 WQL 撰寫也是如此。

若要使用 WMI 進行查詢處理，請勿在__InstanceProviderRegistration中設定QuerySupportLevels屬性。當您這樣做時，WMI 會呼叫 CreateInstanceEnumAsync 的實作，並張貼篩選結果，讓呼叫端只取得符合查詢準則的實例。

下列範例顯示 ExecQueryAsync的典型執行個體提供者實作。系統會呼叫 IWbemObjectSink：：SetStatus 方法，以指出結果集的結尾。它也可能呼叫，而不需對 IWbemObjectSink：：指出發生錯誤狀況。

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

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

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

// Parse the query.
//   You must implement ParseQuery().
    if (!ParseQuery(strQuery))  return WBEM_E_PROVIDER_NOT_CAPABLE;   

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

// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
    int iNumInst = GetNumberInst();

// Now loop through the private source and create each   
// instance which is part of the result set of the query.
    for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
    {
// Prepare an empty object to receive the class definition.
         IWbemClassObject *pNextInst = 0;
         hRes = pClass->SpawnInstance(0, &pNextInst);

// Create the instance.
//   You must implement FillInst().
         /*FillInst(pNextInst, iCnt);*/ 

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

// Clean up memory
    pClass->Release();
  
// Send finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

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

注意當提供者實作 ExecQueryAsync時，預設會根據查詢傳回正確的結果集。如果提供者無法輕鬆地傳回正確的結果集，它可能會傳回結果的超集合，並要求 WMI 在將物件傳遞至用戶端之前先進行篩選，以確保結果集正確無誤。若要這樣做，提供者會在提供給其 ExecQueryAsync實作的接收上呼叫SetStatus，並具有下列旗標。

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
    WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);

注意後續傳送至 WMI 服務的任何物件都會經過篩選。提供者可以使用下列呼叫，在中間資料流程中關閉篩選。

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS, 
    WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);

規格需求


最低支援的用戶端	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