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

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

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

WBEM_FLAG_BIDIRECTIONAL

このフラグにより、クライアントが列挙子を解放するまで、Windows Management は列挙のオブジェクトへのポインターを保持します。

WBEM_FLAG_DIRECT_READ

このフラグは、親クラスまたはサブクラスに関係なく、指定されたクラスのプロバイダーに直接アクセスします。

[in] pCtx

通常は NULL です。 それ以外の場合、これは、要求されたインスタンスを返すプロバイダーが使用できる IWbemContext オブジェクトへのポインターです。 コンテキスト オブジェクトの値は、該当するプロバイダーのドキュメントで指定する必要があります。 詳細については、「WMI を呼び出す」を参照してください。

[in] pResponseHandler

IWbemObjectSink の呼び出し元の実装へのポインター。 このハンドラーは、使用可能になるとオブジェクトを受け取ります。 エラー コードが返された場合、指定された IWbemObjectSink ポインターは使用されません。 WBEM_S_NO_ERRORが返された場合、操作の結果を示すためにユーザーの IWbemObjectSink 実装が呼び出されます。 Windows Management は、WBEM_S_NO_ERRORが返された場合にのみ、ポインターに 対して AddRefを 呼び出します。 エラー コードが返された場合、参照カウントは入力時と同じです。 詳細については、「メソッドの呼び出し」を参照してください。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。 次の一覧は、 HRESULT に含まれる値の一覧です。

失敗した場合は、COM 関数 GetErrorInfo から詳細情報を取得できます。

ネットワークの問題によって Windows Management へのリモート接続が失われると、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 のパフォーマンスに与える影響を判断するのに役立ちます。

要件

こちらもご覧ください

メソッドの呼び出し

IWbemServices

IWbemServices::CreateInstanceEnum