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

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_SHOPPING_CATALOG_H_
#define NN_EC_SHOPPING_CATALOG_H_

#include <nn/ec/ec_Catalog.h>
#include <nn/ec/ec_Query.h>

namespace nn { namespace ec {

//! @addtogroup nn_ec_class
//! @{

/*!
@brief Class for handling a shopping catalog.

@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712105">Programming Manual</a>
*/
class ShoppingCatalog : public Catalog
{
public:
    NN_EC_DECLARE_ACCESSOR;
    NN_EC_DECLARE_IMPL;

public:
    /*!
@brief      The maximum number of items you want to get.
    */
    static const u32 ITEM_NUM_MAX = 100;

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

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

    /*!
@brief Gets a list of downloadable content.

This function calls <tt>@ref Clear</tt> before retrieving the list. @n
The reference counters of previously retrieved items are decremented by 1, so make note of the persistence of items retrieved with <tt>@ref GetItem</tt>.

This function blocks because it involves communication.

@param[in] pQuery  Specifies the query. @n
Specify <tt>NULL</tt> if you are not using a query.
@param[in] startIndex  Specifies the start position.
@param[in] num  Specifies the number of items to retrieve. @n
The maximum number that can be specified is <tt>@ref ITEM_NUM_MAX</tt>.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval     ResultOutOfMemory       Insufficient memory.
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultCanceled          The communication process was canceled.
@retval     ResultExcluded          The EC applet is running.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.
@retval     Other                  Sometime an error generated by <tt>@ref Login</tt> is returned.
    */
    nn::Result RetrieveAocs(const Query* pQuery, u32 startIndex, u32 num);

    /*!
@brief Gets an item list from a download code.

This function calls <tt>@ref Clear</tt> before retrieving the list. @n
The reference counters of previously retrieved items are decremented by 1, so make note of the persistence of items retrieved with <tt>@ref GetItem</tt>.

This function returns <tt>@ref ResultWrongDownloadCode</tt> if the specified code is not a download code for an item that can be used by the application.

This function blocks because it involves communication.

@param[in] pQuery  Specifies the query. @n
Specify <tt>NULL</tt> if you are not using a query. @n
Values other than <tt>@ref Query::Select</tt> are ignored.
@param[in] pDownloadCode  Specifies the download code. @n
The function returns <tt>@ref ResultInvalidArgument</tt> if the specified value is not a 16-digit alphanumeric string.
@param[in] num  Specifies the number of items to retrieve. @n
If multiple items can be retrieved, specify the maximum number. @n
The maximum number that can be specified is <tt>@ref ITEM_NUM_MAX</tt>.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval     ResultOutOfMemory       Insufficient memory.
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultCanceled          The communication process was canceled.
@retval     ResultExcluded          The EC applet is running.
@retval     ResultWrongDownloadCode     Not a valid download code.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.
@retval     Other                  Sometime an error generated by <tt>@ref Login</tt> is returned.
    */
    nn::Result RetrieveWithDownloadCode(const Query* pQuery, const char* pDownloadCode, u32 num = 1);

    /*!
@brief Gets the total number of items that can be retrieved.

The value returned by this function does not depend on the number of items to retrieve as specified in <tt>Retrieve*</tt>.

You must call <tt>Retrieve*</tt> before calling this function. @n
This function returns <tt>0</tt> if an item list could not be retrieved with <tt>Retrieve*</tt>.

@return Returns the total number of retrievable items.

@see        RetrieveAocs
@see        RetrieveWithDownloadCode
    */
    u32 GetTotal() const;

private:
    // 
    Impl* CreateImpl(u32 num);
};

//! @}

}} // namespace nn::ec

#endif // NN_EC_SHOPPING_CATALOG_H_