IWbemServices::ExecQueryAsync メソッド (wbemcli.h)

IWbemServices::ExecQueryAsync メソッドは、オブジェクトを非同期的に取得するためのクエリを実行します。

構文

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

パラメーター

[in] strQueryLanguage

Windows Management Instrumentation (WMI) でサポートされているクエリ言語のいずれかを含む有効な BSTR 。 これは "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

このフラグは、クライアントの IWbemObjectSink::SetStatus の実装を通じて中間状態レポートを受信する要求を WMI に登録します。 プロバイダーの実装では、このフラグを変更するための中間状態レポートをサポートする必要があります。

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 を 1 回呼び出して最終的な状態を示します。

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 からスレッドを取得します。 sink AddRef メソッドを呼び出し、別のスレッドを作成して、結果セット内のオブジェクトを配信できます。 別のスレッドを作成すると、現在のスレッドは、スレッド プールを使い果たさずに WMI に戻ることができます。 プロバイダーが単一スレッド設計を選択するか、デュアル スレッド設計を選択するかは、プロバイダーが WMI スレッドの使用を計画する期間によって異なります。 固定ルールはありません。 実験は、設計が WMI のパフォーマンスにどのように影響するかを判断するのに役立ちます。

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

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

要件

関連項目

メソッドの呼び出し

IWbemObjectSink::SetStatus

IWbemServices

IWbemServices::ExecQuery

WQL を使用したクエリ