項目の列挙

デバイスが作成されると、Windows イメージ取得 (WIA) によって、デバイスとそのデバイスに関連付けられているフォルダーとイメージを表す WIA 項目の階層ツリーが作成されます。 ルート項目の (デバイスを表すツリーのルートにある項目) IWiaItem::EnumChildItems (または IWiaItem2::EnumChildItems) メソッドを使用して列挙子オブジェクトを作成し、その IEnumWiaItem (または IEnumWiaItem2) インターフェイスへのポインターを取得します。このインターフェイスは、項目ツリーを移動し、デバイスに関連付けられているイメージまたはスキャンベッドにアクセスするために使用されます。

次の例は、ツリーのすべての項目を再帰的に列挙する関数を示しています。その関数に渡されるルート項目から始めます。

    HRESULT EnumerateItems( IWiaItem *pWiaItem ) //XP or earlier
    HRESULT EnumerateItems( IWiaItem2 *pWiaItem ) //Vista or later
    {
        //
        // Validate arguments
        //
        if (NULL == pWiaItem)
        {
            return E_INVALIDARG;
        }

        //
        // Get the item type for this item.
        //
        LONG lItemType = 0;
        HRESULT hr = pWiaItem->GetItemType( &lItemType );
        if (SUCCEEDED(hr))
        {
            //
            // If it is a folder, or it has attachments, enumerate its children.
            //
            if (lItemType & WiaItemTypeFolder || lItemType & WiaItemTypeHasAttachments)
            {
                //
                // Get the child item enumerator for this item.
                //
                IEnumWiaItem *pEnumWiaItem = NULL; //XP or earlier
                IEnumWiaItem2 *pEnumWiaItem = NULL; //Vista or later
                
                hr = pWiaItem->EnumChildItems( &pEnumWiaItem );
                if (SUCCEEDED(hr))
                {
                    //
                    // Loop until you get an error or pEnumWiaItem->Next returns
                    // S_FALSE to signal the end of the list.
                    //
                    while (S_OK == hr)
                    {
                        //
                        // Get the next child item.
                        //
                        IWiaItem *pChildWiaItem = NULL; //XP or earlier
                        IWiaItem2 *pChildWiaItem = NULL; //Vista or later
                        
                        hr = pEnumWiaItem->Next( 1, &pChildWiaItem, NULL );

                        //
                        // pEnumWiaItem->Next will return S_FALSE when the list is
                        // exhausted, so check for S_OK before using the returned
                        // value.
                        //
                        if (S_OK == hr)
                        {
                            //
                            // Recurse into this item.
                            //
                            hr = EnumerateItems( pChildWiaItem );

                            //
                            // Release this item.
                            //
                            pChildWiaItem->Release();
                            pChildWiaItem = NULL;
                        }
                    }

                    //
                    // If the result of the enumeration is S_FALSE (which
                    // is normal), change it to S_OK.
                    //
                    if (S_FALSE == hr)
                    {
                        hr = S_OK;
                    }

                    //
                    // Release the enumerator.
                    //
                    pEnumWiaItem->Release();
                    pEnumWiaItem = NULL;
                }
            }
        }
        return  hr;
    }

この関数は、列挙する項目ツリーのルート項目の IWiaItem (または IWiaItem2) インターフェイスへのポインターである pWiaItem パラメーターを受け取ります。

最初に、この関数は、アイテムがフォルダーかどうか、または添付ファイルがあるかどうかを確認します。 その場合は、pWiaItem の IWiaItem::EnumChildItems (または IWiaItem2::EnumChildItems) メソッドを呼び出して、項目ツリーの列挙子オブジェクトを作成します。 この呼び出しが成功し、列挙子が有効な場合、関数は子項目を反復処理し、各項目で自身を再帰的に呼び出し、それぞれが次のレベルの子項目の潜在的なルート項目として扱われます。

この方法で、 関数は EnumerateItems に渡されるルート項目の下にある項目ツリーのすべての分岐を列挙します。