/*

* Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:    List of media items

*

*/

#ifndef __C_GLXITEMLIST_H__

#define __C_GLXITEMLIST_H__

#include <e32std.h>

#include "glxmedia.h"

// Forward declarations

class CMPXCollectionPath;

class MGlxItemListObserver;

class MGlxMediaUser;

class MGlxMediaPool;

namespace NGlxItemList

    {

    class MListModificationStrategy;

    class TDifferenceInfo;

    }

/**

 * CGlxItemList

 *

 * List that has media items

 *

 * @author Aki Vanhatalo

 *

 * @internal reviewed 17/07/2007 by Kimmo Hoikka

 *

 * @ingroup mlm_media_list_manager_design

 */

NONSHARABLE_CLASS( CGlxItemList ) : public CBase

    {

public:

     /**

      * Constructor

      * @param aIdSpaceId id of id space in which list item ids are

      * @param aObserver Observer to be notified of item addition/removal

      * @param aMediaUser User class of media objects - media objects that 

      *                   this list links to will be linked to the user, so that 

      *                   cache manager is able to quickly access the media lists 

      *                   that use particular media objects

      */

    static CGlxItemList* NewL( const TGlxIdSpaceId& aIdSpaceId, 

        MGlxItemListObserver& aObserver, MGlxMediaUser& aMediaUser );    

    /** 

     * Destructor

     */

    ~CGlxItemList();

    /**

     * @return id space id

     */

    inline const TGlxIdSpaceId& IdSpaceId() const;

    /**

     * Synchronises the list with new path 

     * Sends added/removed notifications as necessary

     * Note: Does not send "perfect" notification if the order of the items 

     * has been changed. Hence, this function cannot be reliably used when 

     * sort order has changed

     *

     * @param aSource path with item ids. 

     * @param aMediaPool interface from which to ask for media items

     */

    void SetContentsL( const CMPXCollectionPath& aSource, const MGlxMediaPool& aMediaPool );

    /**

     * Remove an item form the list

     * Sends removed notification

     *

     * @param aItemId Id of item to remove

     * @param aIdSpaceId Id space of the item

     */

    void Remove( const TGlxIdSpaceId& aIdSpaceId, const TGlxMediaId& aItemId );

    /**

     * Remove any pointers to the media object at the specified index

     * @param aIndex index of media object from which to remove a reference

     */

    void RemoveReference( TInt aIndex );

    /** 

     * @return count of items in the list

     */

    inline TInt Count() const;

    /** 

     * @return item at index

     */

    inline TGlxMedia& Item( TInt aIndex );

    /** 

     * @param aId Id of item for which index is needed

     * @return index of item with id aId or KErrNotFound

     */

    TInt Index( const TGlxIdSpaceId& aIdSpaceId, const TGlxMediaId& aId ) const;

private:

    /**

     * Constructor

     * @param aIdSpaceId id of id space in which list item ids are

     * @param aObserver Observer to be notified

     * @param aMediaUser User class of media objects - media objects that 

     *                   this list links to will be linked to the user, so that 

     *                   cache manager is able to quickly access the media lists 

     *                   that use particular media objects

     */

    CGlxItemList( const TGlxIdSpaceId& aIdSpaceId,

        MGlxItemListObserver& aObserver, MGlxMediaUser& aMediaUser );

    /**

     * Process differences between source and current list

     * @param aSource source list 

     * @param aStrategy strategy object that contains the logic of how to

     *                  process the differences that are found

     */

    void ProcessDifferences( const CMPXCollectionPath& aSource, 

            NGlxItemList::MListModificationStrategy& aStrategy );

    /**

     * Find the first matches in the source and current lists.

     * @param aInfo object that contains start-search-from indexes in source 

     *              and current list

     * @param aSource source list

     * @param aSourceMatchIndex On return, contains the index of matching 

     *                          source item, or if not found, the count of

     *                          source list. (Returning count simplifies 

     *                          client functions algorithm)

     * @param aTargetMatchIndex On return, contains the index of matching 

     *                          target item, or if not found, the count of

     *                          target (current) list. (Returning count 

     *                          simplifies client functions algorithm)

     */

    void FindMatchingItems( const NGlxItemList::TDifferenceInfo& aInfo, 

        const CMPXCollectionPath& aSource, TInt& aSourceMatchIndex, 

        TInt& aTargetMatchIndex );

    /**

     * Process difference that would require removing items to eliminate.

     * Forwards the actual "remove" request to the modification strategy

     * @param aTargetMatchIndex Index until which items need to be removed

     * @param aInfo Info of indexes needed to remove the items.

     *              Strategy can modify these indexes

     * @param aStrategy strategy object that contains the logic of how to

     *                  process the differences that are found

     */

    void ProcessRemove( TInt aTargetMatchIndex, NGlxItemList::TDifferenceInfo& aInfo, 

            NGlxItemList::MListModificationStrategy& aStrategy );

    /**

     * Process difference that would require inserting items to eliminate.

     * Forwards the actual "insert" request to the modification strategy

     * @param aSourceMatchIndex Index to which items need to be copies

     * @param aInfo Info of indexes needed to insert the items.

     *              Strategy can modify these indexes

     * @param aStrategy strategy object that contains the logic of how to

     *                  process the differences that are found

     */

    void ProcessInsert( TInt aSourceMatchIndex, NGlxItemList::TDifferenceInfo& aInfo, 

            NGlxItemList::MListModificationStrategy& aStrategy );

    /** 

     * @return item at index, non-const

     */

    inline TGlxMedia& operator[] ( TInt aIndex );

private:

    /// Media items in this list

    RArray< TGlxMedia > iItems;

    /// The id of the "space" of unique item ids 

    TGlxIdSpaceId iIdSpaceId;

    /// User of media objects. Used for building a link from media object 

    /// (CGlxMedia) to its used when building a link from item (TGlxMedia) 

    /// to media object

    MGlxMediaUser& iMediaUser;

    /// Observer for changes

    MGlxItemListObserver& iObserver; 

    __DECLARE_TEST;

    };

#include "glxitemlist.inl" 

#endif // __C_GLXITEMLIST_H__