Énumération des éléments

Lorsqu’un appareil est créé, l’acquisition d’images Windows (WIA) crée une arborescence hiérarchique d’éléments WIA qui représentent l’appareil, ainsi que les dossiers et images associés à cet appareil. Utilisez la méthode de l’élément racine (l’élément à la racine de l’arborescence qui représente l’appareil) IWiaItem::EnumChildItems (ou IWiaItem2::EnumChildItems) pour créer un objet énumérateur et obtenir un pointeur vers son interface IEnumWiaItem (ou IEnumWiaItem2), qui permet de naviguer dans l’arborescence d’éléments et d’accéder aux images ou aux lits d’analyse associés à l’appareil.

L’exemple suivant montre une fonction qui énumère de manière récursive tous les éléments d’une arborescence, en commençant par un élément racine qui est passé à la fonction.

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

La fonction prend le paramètre pWiaItem, pointeur vers l’interface IWiaItem (ou IWiaItem2) de l’élément racine de l’arborescence d’éléments à énumérer.

Tout d’abord, la fonction vérifie si l’élément est un dossier ou s’il contient des pièces jointes. Si c’est le cas, il appelle ensuite la méthode IWiaItem::EnumChildItems (ou IWiaItem2::EnumChildItems) de pWiaItem pour créer un objet énumérateur pour l’arborescence d’éléments. Si cet appel réussit et que l’énumérateur est valide, la fonction itère au sein des éléments enfants et s’appelle de manière récursive sur chaque élément, en les traitant comme un élément racine potentiel pour le niveau suivant d’éléments enfants.

De cette façon, la fonction énumère toutes les branches de l’arborescence d’éléments sous l’élément racine passé à EnumerateItems.