/*---------------------------------------------------------------------------*

Copyright (C) 2013-2014 Nintendo. All rights reserved.

These coded instructions, statements, and computer programs contain
proprietary information of Nintendo of America Inc. and/or Nintendo
Company Ltd., and are protected by Federal copyright law.  They may
not be disclosed to third parties or copied or duplicated in any form,
in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

#ifndef NN_EC_ITEM_LIST_H_
#define NN_EC_ITEM_LIST_H_

#include <nn/ec/ec_Types.h>
#include <nn/ec/ec_Item.h>

namespace nn { namespace ec {

//! @addtogroup nn_ec_class
//! @{

/*!
@brief      Class for handling an item list.
*/
class ItemList : public RootObject, private NonCopyable<ItemList>
{
public:
    NN_EC_DECLARE_ACCESSOR;
    NN_EC_DECLARE_IMPL;

public:
    /*!
@brief Specifies an invalid index.
    */
    static const u32 INVALID_INDEX = 0xFFFFFFFF;

public:
    /*!
@brief Instantiates the object.
    */
    ItemList();

    /*!
@brief Destroys the object.
    */
    virtual ~ItemList();

    /*!
@brief Clears the object.

When this function is called, internally allocated memory is released. @n
In addition, the reference counter of the item in the list is decremented by 1.
    */
    void Clear();

    /*!
@brief Downloads the icons of the items contained in the list.

This function downloads the icons for the list items within the specified range. @n
For more information, see <tt>@ref Item::DownloadIconAsync</tt>.

When downloading multiple icons at one time with this function, the tasks are added to the download queue as follows.

Example: A list contains three items: a, b, and c, and the download queue contains three tasks: x, y, and z.
@li HEAD: DL-Queue(Tx, Ty, Tz) == DownloadIconsAsync(0, 3, HEAD) => DL-Queue(Ta, Tb, Tc, Tx, Ty, Tz)
@li TAIL: DL-Queue(Tx, Ty, Tz) == DownloadIconsAsync(0, 3, TAIL) => DL-Queue(Tx, Ty, Tz, Ta, Tb, Tc)

@param[in] startIndex  Specifies the start position.
@param[in] num  Specifies the number to download.
@param[in] position  Specifies the position at which to add the download task. @n
The task is added to the front of the download queue by default.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInvalidData        Indicates that the data is invalid. (For example, the list has no items, or an item on the list has invalid data.) 
@retval     ResultOutOfMemory       Insufficient memory.
    */
    nn::Result DownloadIconsAsync(u32 startIndex = 0, u32 num = 0xFFFFFFFF, QueuePosition position = QUEUE_POSITION_HEAD);

    /*!
@brief Gets an item.

The reference counter of the item obtained with this function is decremented by 1 when <tt>@ref Clear</tt> or the destructor is called. @n
Make note of the persistence of the item.

@param[in] index  Specifies the index in the list.

@return Returns the item. @n
If the specified index is out of bounds, <tt>NULL</tt> is returned.
    */
    Item* GetItem(u32 index);

    /*!
@brief Gets an item.

The reference counter of the item obtained with this function is decremented by 1 when <tt>@ref Clear</tt> or the destructor is called. @n
Make note of the persistence of the item.

@param[in] index  Specifies the index in the list.

@return Returns the item. @n
If the specified index is out of bounds, <tt>NULL</tt> is returned.
    */
    const Item* GetItem(u32 index) const;

    /*!
@brief Gets the number of items contained in the list.

@return Returns the number of items.
    */
    u32 GetNumItems() const;

    /*!
@brief Gets the index of the item in the list.

@param[in] pItem  Specifies the item.

@return Returns the index. @n
If the specified item is invalid or does not exist in the list, <tt>@ref INVALID_INDEX</tt> is returned.
    */
    u32 GetIndex(const Item* pItem) const;

protected:
    // 
    NN_EC_IMPL;
};

//! @}

}} // namespace nn::ec

#endif // NN_EC_ITEM_LIST_H_