Auflisten von Elementen

Wenn ein Gerät erstellt wird, erstellt Windows Image Acquisition (WIA) eine hierarchische Struktur von WIA-Elementen, die das Gerät und die Ordner und Bilder darstellen, die diesem Gerät zugeordnet sind. Verwenden Sie die IWiaItem::EnumChildItems-Methode (oder IWiaItem2::EnumChildItems), um ein Enumeratorobjekt zu erstellen und einen Zeiger auf die IEnumWiaItem-Schnittstelle (oder IEnumWiaItem2) abzurufen, die verwendet wird, um in der Elementstruktur zu navigieren und Zugriff auf die dem Gerät zugeordneten Bilder oder Scanbetten zu erhalten.

Das folgende Beispiel zeigt eine Funktion, die alle Elemente einer Struktur rekursiv auflistet, beginnend mit einem Stammelement, das an die Funktion übergeben wird.

    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;
    }

Die Funktion verwendet den Parameter pWiaItem, einen Zeiger auf die IWiaItem-Schnittstelle (oder IWiaItem2) des Stammelements der elementstruktur, die aufgelistet werden soll.

Zunächst überprüft die Funktion, ob es sich bei dem Element um einen Ordner handelt oder ob es Anlagen enthält. Wenn dies der Fall ist, wird die IWiaItem::EnumChildItems -Methode (oder IWiaItem2::EnumChildItems) von pWiaItem aufgerufen, um ein Enumeratorobjekt für die Elementstruktur zu erstellen. Wenn dieser Aufruf erfolgreich ist und der Enumerator gültig ist, durchläuft die Funktion die untergeordneten Elemente und ruft sich rekursiv für jedes Element auf, wobei jedes Element als potenzielles Stammelement für die nächste Ebene untergeordneter Elemente behandelt wird.

Auf diese Weise listet die Funktion alle Verzweigungen der Elementstruktur unterhalb des Stammelements auf, das an EnumerateItems übergeben wird.