IEnumWbemClassObject

IEnumWbemClassObject インターフェイスは、Common Information Model (CIM) オブジェクトを列挙するために使用され、標準的な COM 列挙子に似ています。

IEnumWbemClassObject は WMI クエリから返されるオブジェクトであり、返された値を列挙するために使用します。このクラスの使用方法の詳細については、Querying WMI および Enumerating WMI を参照してください。

例

次の C++ のコード例は、IEnumWbemClassObject を取得する方法を示しています。

void ExecQuerySync(IWbemServices *pSvc)
{
    // Query for all users and groups.

    BSTR Language = SysAllocString(L"WQL");
    BSTR Query = SysAllocString(L"SELECT * FROM __Namespace");

    // Initialize the IEnumWbemClassObject pointer.
    IEnumWbemClassObject *pEnum = 0;

    // Issue the query.
    HRESULT hRes = pSvc->ExecQuery(
        Language,
        Query,
        WBEM_FLAG_FORWARD_ONLY,         // Flags
        0,                              // Context
        &pEnum
        );

    SysFreeString(Query);
    SysFreeString(Language);

    if (hRes != 0)
    {
        printf("Error\n");
        return;
    }
    
    ULONG uTotal = 0;

    // Retrieve the objects in the result set.
    for (;;)
    {
        IWbemClassObject *pObj = 0;
        ULONG uReturned = 0;

        hRes = pEnum->Next(
            0,                  // Time out
            1,                  // One object
            &pObj,
            &uReturned
            );

        uTotal += uReturned;

        if (uReturned == 0)
            break;

        // Use the object.
        
        // ...
        
        // Release it.
        // ===========
        
        pObj->Release();    // Release objects not owned.            
    }

    // All done.
    pEnum->Release();
}

IEnumWbemClassObject::Reset メソッドは、列挙シーケンスを先頭に戻します。CIM オブジェクトは動的であるため、このメソッドを呼び出しても、以前に取得したものと同じオブジェクトの一覧が返されるとは限りません。

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

ネットワークの問題によって Windows Management へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。

ネットワークの問題により Windows Management へのリモート接続が失われると、COM 固有のエラーコードが返されることがあります。

WBEM_S_NO_ERROR が返されない場合は、COM 関数 GetErrorInfo を呼び出してエラーに関する詳細情報を取得できます。

IEnumWbemClassObject::Next メソッドを使用すると、列挙内の現在位置から 1 つ以上のオブジェクトを取得できます。

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

ネットワークの問題により Windows Management へのリモート接続が失われると、COM 固有のエラーコードが返されることがあります。エラー発生時には、COM 関数 GetErrorInfo を呼び出して詳細なエラー情報を取得できます。

複数のオブジェクトを要求し、要求した数のオブジェクトが返された場合、この関数は WBEM_S_NO_ERROR を返します。要求した数より少ないオブジェクトしか利用できず、列挙が完了している場合は、それらのオブジェクトが返され、この関数は WBEM_S_FALSE を返します。

列挙が完了していない場合、呼び出しは指定されたタイムアウト時間までオブジェクトが利用可能になるのを待機します。オブジェクトが利用可能になる前に列挙がタイムアウトした場合、この関数は WBEM_S_TIMEDOUT を返します。

例

C++ と WMI でのクエリ作成に関する詳しい解説と例については、CodeProject の WMI Queries In C++ を参照してください。

HRESULT ProcessEnum( IEnumWbemClassObject*    pEnum )
{
    HRESULT    hRes = WBEM_S_NO_ERROR;

    // Final Next will return WBEM_S_FALSE
    while ( WBEM_S_NO_ERROR == hRes )
    {
        ULONG            uReturned;
        IWbemClassObject*    apObj[10];

        hRes = pEnum->Next( WBEM_INFINITE, 10, apObj, &uReturned );

        if ( SUCCEEDED( hRes ) )
        {
            // Do something with the objects.
            //ProcessObjects( uReturned,  apObj );

            for ( ULONG n = 0; n < uReturned; n++ )
            {
                apObj[n]->Release();
            }

        }    // If Enum succeeded...
    }    // While Enum is returning objects...

    return hRes;
}

シンクへのオブジェクトの取得を制御された非同期方式で行う必要がある場合は、NextAsync メソッドを使用します。

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

COM 関数 GetErrorInfo を呼び出すと、エラーに関する詳細情報を取得できます。ネットワークの問題により Windows Management へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。

この呼び出しは直ちに戻り、シンクへの配信はバックグラウンドで行われます。1 つ以上のスレッドからこのメソッドが複数回呼び出された場合、それらは論理的にキューイングされ、呼び出しの順序とオブジェクトの配信順序は保持されます。1 つ以上のスレッドからこのメソッドが複数回呼び出された場合、以前の呼び出しに関連するシンクオブジェクトの処理がすべて完了するまで、呼び出しは戻りません。 Reset を呼び出しても、以前の呼び出しの結果として進行中のオブジェクトの配信には影響しません。 Reset メソッドは、新しい呼び出しがオブジェクトシーケンスの先頭から開始されるようにするだけです。

要求した数のオブジェクトが直ちに利用可能な場合、この関数は WBEM_S_NO_ERROR を返します。要求した数より少ないオブジェクトしか利用できない場合は、利用可能なオブジェクトが返され、WBEM_S_NO_ERROR が返されます。残りのオブジェクトは、ユーザーが指定したシンクによって配信されます。

オブジェクトが利用可能になるにつれて、呼び出し元が実装した IWbemObjectSink::Indicate が 0 回以上呼び出され、オブジェクトが配信されます。uCount 個の項目が返された場合は、その後に WBEM_S_NO_ERROR の値で IWbemObjectSink::SetStatus が呼び出されます。

要求した数より利用可能なオブジェクトが少ない場合は、利用可能なオブジェクトについて Indicate が呼び出されます。その後、WBEM_S_FALSE の値 (エラーが発生した場合はそのエラーコード) で SetStatus が呼び出されます。

要求した数のオブジェクトが配信された場合、最後のオブジェクトに続いて、状態コード WBEM_S_NO_ERROR で SetStatus が呼び出されます。要求した数のオブジェクトを配信し終える前に列挙が完了した場合、SetStatus メソッドの状態コードは WBEM_S_FALSE になります。

利用可能なオブジェクトがない場合、Indicate は呼び出されません。ただし、操作全体の状態を示すために、SetStatus の最終呼び出しは必ず行われます。

コールバックは、クライアントが必要とする認証レベルと同じレベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することをお勧めします。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、IEnumWbemClassObject::Next および Calling a Method を参照してください。

IEnumWbemClassObject::Clone メソッドは、列挙子全体の論理的なコピーを作成し、列挙内の現在位置を保持します。

エラー発生時には、COM 関数 GetErrorInfo を呼び出して詳細なエラー情報を取得できます。ネットワークの問題により Windows Management へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。

次の一覧は、HRESULT に含まれる値を示します。

シンクへのコールバックは、クライアントが必要とする認証レベルと同じレベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することをお勧めします。非同期通信が必要な場合は、 Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、 IEnumWbemClassObject および Calling a Method を参照してください。

例

次のコードは、IEnumWbemClassObject::Clone メソッドの使用方法を示しています。

BOOL CloneEnum(IEnumWbemClassObject *pSrc)
{
    IEnumWbemClassObject *pCopy = 0;

    HRESULT hRes = pSrc->Clone(&pCopy);

    if (hRes != WBEM_S_NO_ERROR)       // Failed to clone it.
        return FALSE;

    // Use the copy of the enumerator.
    // ...

    pCopy->Release();

    return TRUE;
}

IEnumWbemClassObject::Skip メソッドを使用すると、列挙内の現在位置を指定した数のオブジェクト分だけ先に進めることができます。これは後続の NextAsync の呼び出しにも影響しますが、NextAsync によって開始済みの保留中の配信には影響しません。

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

ネットワークの問題により Windows Management へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。