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

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_API_APPLET_H_
#define NN_EC_API_APPLET_H_

#include <nn/ec/ec_TypesApplet.h>
#include <nn/ec/ec_Money.h>
#include <nn/ec/ec_ShoppingCart.h>
#include <nn/ec/ec_DownloadCart.h>

namespace nn { namespace ec { namespace applet {

//! @addtogroup nn_ec_api
//! @{

//! @name Applet
//! @{

/*!
@brief Sets the anchor.

By setting an anchor before running the EC applet, you can have the application retrieve that anchor when control returns from the EC applet. @n
The application does not need to retrieve the anchor if the POWER Button is pressed and the system enters into the shutdown sequence while the EC applet is running.

Use <tt>SYSGetArguments</tt> to retrieve the set anchor.

@param[in] pAnchor  Specifies the anchor. @n
Specify <tt>NULL</tt> to clear the anchor.

@return Returns the processing result.

@retval Result::IsSuccess Indicates success.
@retval ResultInvalidArgument  Indicates that an argument is invalid. /< The anchor size is too large.

@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925509">Programming Manual</a>
*/
nn::Result SetAnchor(const char* pAnchor);

/*!
@brief Sets the controller channel to give priority to controlling applets.

The EC applet can be controlled using the Wii U GamePad and the following controllers.

@li Wii Remote
@li Wii U Pro Controller

This function sets which controller to give priority to when multiple controllers are available. @n
If a controller cannot be found on the specified channel, the EC applet gives priority to the controller with the lowest channel number.

Note that the Wii U GamePad can always be used to control the applet regardless of the controller channel setting.

@param[in] channel  Specifies the controller channel. @n
A value from 0 to 3 can be specified.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval ResultInvalidArgument  Indicates that an argument is invalid.

@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925545">Programming Manual</a>
*/
nn::Result SetPriorUseControllerChannel(s32 channel);

/*!
@brief Starts the EC applet in balance management mode.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[out] pPostBalance        The balance after running the EC applet. @n
Specify <tt>NULL</tt> if not necessary.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712048">Programming Manual</a>
*/
nn::Result ManageBalance(Money* pPostBalance = NULL);

/*!
@brief Starts the EC applet in item purchase mode.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[in] shoppingCart  Specifies a shopping cart.
@param[out] pPostBalance        The balance after running the EC applet. @n
Specify <tt>NULL</tt> if not necessary.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval     ResultInvalidData        Indicates that the data is invalid. (No items are in the cart, or an item in the cart has invalid data.) 
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_54695908">Programming Manual</a>
*/
nn::Result Purchase(const ShoppingCart& shoppingCart, Money* pPostBalance = NULL);

/*!
@brief Starts the EC applet in item purchase mode.

This function is for purchasing single items only. @n
To purchase batches of items, use the API function that takes a <tt>@ref ShoppingCart</tt> object as an argument.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[in] pItem  Specifies the item.
@param[out] pPostBalance        The balance after running the EC applet. @n
Specify <tt>NULL</tt> if not necessary.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval     ResultInvalidData        Indicates that the data is invalid. (Item contains invalid data.)
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_54695908">Programming Manual</a>
*/
nn::Result Purchase(const Item* pItem, Money* pPostBalance = NULL);

/*!
@brief Starts the EC applet in item redemption mode.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[out] pPostBalance        The balance after running the EC applet. @n
If nothing has been added to the balance, the value will not change. @n
Specify <tt>NULL</tt> if not necessary.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925006">Programming Manual</a>
*/
nn::Result Redeem(Money* pPostBalance = NULL);

/*!
@brief Starts the EC applet in item redemption mode.

This function is used when the user selects an item that is redeemed by the application. @n
Use the API function that takes no arguments when an item is selected by the EC applet.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[in] pItem  Specifies the item.
@param[in] pDownloadCode  Specifies the download code of the item. @n
The function returns <tt>@ref ResultInvalidArgument</tt> if the specified value is not a 16-digit alphanumeric string.
@param[out] pPostBalance        The balance after running the EC applet. @n
If nothing has been added to the balance, the value will not change. @n
Specify <tt>NULL</tt> if not necessary.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval     ResultInvalidData        Indicates that the data is invalid. (Item contains invalid data.)
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925006">Programming Manual</a>
*/
nn::Result Redeem(const Item* pItem, const char* pDownloadCode, Money* pPostBalance = NULL);

/*!
@brief Starts the EC applet in item redownload mode.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[in] downloadCart  Specifies the download cart.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval     ResultInvalidData        Indicates that the data is invalid. (No items are in the cart, or an item in the cart has invalid data.) 
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48924983">Programming Manual</a>
*/
nn::Result Download(const DownloadCart& downloadCart);

/*!
@brief Starts the EC applet in item redownload mode.

This function is for redownloading single items only. @n
To redownload multiple items at one time, use the API function that takes a <tt>@ref DownloadCart</tt> object as an argument.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@param[in] pItem  Specifies the item.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval     ResultInvalidData        Indicates that the data is invalid. (Item contains invalid data.)
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48924983">Programming Manual</a>
*/
nn::Result Download(const Item* pItem);

/*!
@brief Starts the EC applet in data title update mode.

You must close data titles before running the EC applet. @n
In addition, you cannot open data titles while the EC applet is running.

Call <tt>@ref Finish</tt> when the application has transitioned to the foreground after running the EC applet.

@return The result of processing.

@retval Result::IsSuccess Indicates success.
@retval     ResultInternalError     An internal error occurred.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval     ResultNotLoggedIn       Not logged in to the eShop server.
@retval     ResultNotInForeground   The application is not in the foreground.
@retval     ResultNotConnected      Not connected to the Internet.
@retval     ResultExcluded          The EC applet is running or the system is communicating.
@retval     ResultResponseError     A response error occurred.
@retval     ResultCurlError         A communication error occurred.
@retval     ResultServerError       A server error occurred.

@see        SetApplication
@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48712081">Programming Manual</a>
*/
nn::Result UpdateDataTitle();

/*!
@brief        Determines whether the EC applet is running.

While the EC applet is running, communications, excluding the downloading of metadata, and the execution of the EC applet are restricted.

@return Returns <tt>true</tt> if the EC applet is running, or <tt>false</tt> otherwise.

@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48931067">Programming Manual</a>
*/
bool IsExecuting();

/*!
@brief      Finishes the processing of the EC applet.

Calling this function updates both the processing result of the EC applet and the balance after running the EC applet. @n
It also cancels restrictions on communications and the EC applet's execution.

Call this function when the application has transitioned from the background to the foreground. @n
If you call this function at any other time it could cause inconsistencies.

@return The result of processing.

@retval Result::IsSuccess Indicates success.

@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48931067">Programming Manual</a>
*/
nn::Result Finish();

/*!
@brief Gets the processing result of the EC applet.

You must call <tt>@ref Finish</tt> before calling this function.

@return Returns the return code.

@see        <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48931067">Programming Manual</a>
*/
s32 GetReturnCode();

//! @}

//! @}

}}} // namespace nn::ec::applet

#endif // NN_EC_API_APPLET_H_