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

Copyright (C) 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_H_
#define NN_EC_API_H_

#include <nn/ec/ec_Types.h>
#include <nn/ec/ec_DateTime.h>
#include <nn/ec/ec_Money.h>
#include <nn/ec/ec_Option.h>

namespace nn { namespace ec {

//! @addtogroup  nn_ec_api
//! @{

//! @name  Library Initialization and Finalization
//! @{

/*!
@brief  Initializes the library.

Initialize the following libraries beforehand. @n
If you want to specify an allocator and options, specify them before you call this function.

@li  Socket library (SO)
@li  SSL library (NSSL)
@li  HTTP library (CURL)
@li  Account library (ACT)
@li  Automatic connection library (AC)

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidCountry  Cannot get the system's country setting.
@retval ResultInvalidLanguage  Cannot get the system's language setting.
@retval ResultInvalidMeta  Cannot get the application's metadata.

@see  SetAllocator
@see  SetOption
@see  <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48711786">Programming Manual</a>
*/
nn::Result Initialize(u32 version = NN_EC_VERSION);

/*!
@brief  Finalizes the library.

This function calls <tt>@ref Cancel</tt> and waits until the communication process ends.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.

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

//! @}
//! @name  Settings
//! @{

/*!
@brief  Sets the allocator.

This library allocates and frees memory from multiple threads. @n
The allocation or freeing of memory is handled exclusively in the library. It makes no difference whether the allocator is thread-safe or thread-unsafe. @n
If the allocator is shared with another module, however, make it thread-safe.

When not setting an allocator, this library uses <tt>MEMAllocFromDefaultHeapEx</tt> and <tt>MEMFreeToDefaultHeap</tt>.

If called after <tt>@ref Initialize</tt>, the function returns <tt>@ref ResultAlreadyInitialized</tt>.

@param[in] pAllocate  Memory allocation function.
@param[in] pFree  Memory-freeing function.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultAlreadyInitialized  The library is already initialized.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
*/
nn::Result SetAllocator(AllocateFunction pAllocate, FreeFunction pFree);

/*!
@brief  Sets the options.

See <tt>@ref Option</tt> for the options that can be set.

If called after <tt>@ref Initialize</tt>, the function returns <tt>@ref ResultAlreadyInitialized</tt>.

@param[in] option  Options.
@param[in] pValue  The flag to set.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultAlreadyInitialized  The library is already initialized.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
*/
nn::Result SetOption(Option option, void* pValue);

/*!
@brief  Sets the application.

If you want to list or purchase items for another title, set the information for that title in this function. @n
If you are not handling items for other titles, you do not need to call this function.

If the EC applet starts immediately after this function has been called, communication processes might take place inside the EC applet startup function.

If the application is modified, any license information that was synchronized with <tt>@ref SynchronizeAocRights</tt> is cleared.

@param[in] uniqueId  Specifies the unique ID of the title.
@param[in] tin  Specifies the TIN.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval ResultExcluded  The EC applet is running.

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

/*!
@brief  Sets the download callback for metadata.

This function blocks while the metadata download callback is being called.

@param[in] pCallback  Specifies the callback. @n
You can clear this setting by specifying <tt>NULL</tt>.
@param[in] pContext  Specifies the callback parameters.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.

@see  Item::DownloadIconAsync
@see  Item::DownloadPromotionImageAsync
@see  ItemList::DownloadIconsAsync
@see  <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48923120">Programming Manual</a>
*/
nn::Result SetMetadataDownloadCallback(DownloadCallback pCallback, void* pContext);

/*!
@brief  Creates a memory cache for metadata.

When you create a memory cache, you can store the downloaded metadata in that memory cache.

If the metadata download function finds data in the memory cache, it retrieves the data from the cache. This improves performance when repeatedly downloading the same metadata.

If the memory cache runs out of space, data is removed from the cache starting from the data that has not been accessed for the longest time.

@param[in] size  Specifies the size of the memory cache.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval ResultInvalidArgument  Indicates that an argument is invalid.

@see  <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48923255">Programming Manual</a>

*/
nn::Result CreateMetadataCache(size_t size);

/*!
@brief  Deletes a metadata memory cache.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.

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

//! @}
//! @name  Session
//! @{

/*!
@brief  Logs in to the eShop server.

This function gets a service token via the account library and then establishes a session between the client and the eShop server.

The session established this way may be invalidated by the eShop server for certain reasons. @n
Some communication API functions call this function to re-establish a session when an invalid session error has been detected.

The application must be connected to the network in advance.

This function blocks because it involves communication.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval ResultNotConnected  Not connected to the Internet.
@retval ResultCanceled  The communication process was canceled.
@retval ResultExcluded  The EC applet is running.
@retval ResultEshopNotInitialized  The Nintendo eShop initialization sequence has not completed.
@retval ResultNeedsNetworkUpdate  Specifies that a system update is required.
@retval ResultNotInService  The service is not available.
@retval ResultResponseError  A response error occurred.
@retval ResultCurlError  A communication error occurred.
@retval ResultServerError  A server error occurred.
@retval ResultNetworkUpdateCheckError  An error occurred when checking for system update.
@retval nn::act::Result*  An error occurred in the account library.
For more information, see <tt>nn::act::AcquireIndependentServiceToken</tt>.

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

/*!
@brief  Gets the time of the eShop server.

This function uses the time when the client logged in to the eShop server and the internal clock to calculate the eShop server time. @n
The function cannot get the time before logging in. @n
In addition, accuracy of the time is not guaranteed if one or more days have elapsed since logging in.

The time might be off by a number of milliseconds to a number of seconds, depending on network latency and the accuracy of the eShop server clock.

Use this function when comparing the current time with the release date of an item.

@param[out] pServerTime  The server time (UTC).

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval ResultInvalidArgument  Indicates that an argument is invalid.
@retval ResultNotLoggedIn  Not logged in to the eShop server.

@see  Item::GetReleaseDate
*/
nn::Result GetServerTime(DateTime* pServerTime);

//! @}
//! @name  Communication
//! @{

/*!
@brief  Cancels the communication process.

The communication API functions in this library block until the communication process ends. Call this function from a different thread from the one running communication process.

When you cancel communication with this function, all subsequent communication API functions return <tt>@ref ResultCanceled</tt>. @n
To exit the canceled state, use <tt>@ref ResetCancel</tt>.

Note that this function cannot cancel the downloading of metadata. @n
To cancel this kind of process, use <tt>@ref CancelMetadataDownload</tt>.

This function calls <tt>nn::act::Cancel</tt>. Keep this in mind when you call this function while an account communication API function is being called.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval ResultExcluded  The EC applet is running.

*/
nn::Result Cancel();

/*!
@brief  Resets the canceled state.

Calling this function makes communication API functions available again after communication was canceled. @n
Terminating the application without calling this function after a cancellation does not cause any problems.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
*/
nn::Result ResetCancel();

/*!
@brief  Cancels the downloading of metadata.

Calling this function cancels all metadata download processes. @n
It also clears all messages registered in the download queue.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
*/
nn::Result CancelMetadataDownload();

//! @}
//! @name  License Information
//! @{

/*!
@brief  Updates license information for downloadable content to the most recent state.

This function is used when license information is updated, such as when purchasing or redeeming items. @n
Note that license information can be updated due to external factors while the application is running. (For example, due to the purchase of items on Nintendo eShop.)

This function blocks because it involves communication.

@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 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.

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

/*!
@private
@brief  Gets the content list held by the specified data title.

If a Nintendo 3DS system is linked with the Nintendo Network ID, you can get the content lists held by 3DS data titles.

This function blocks because it involves communication.

@param[out] pContentIndexes  A list of content indexes.
@param[out] pNum  The number of pieces of content.
@param[in] num  The number of pieces of content you want to get.
@param[in] uniqueId  The unique ID of the data title.
@param[in] variation  The variation of the data title.
@param[in] platformType  The platform type of the data title.

@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 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 GetOwnedContents(u16* pContentIndexes, u32* pNum, u32 num, u32 uniqueId, u8 variation, PlatformType platformType);

//! @}
//! @name  Balance
//! @{

/*!
@brief  Gets the current balance.

This function blocks because it involves communication.

@param[out] pBalance  Stores the balance.

@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 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.

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

//! @}
//! @name  Version
//! @{

/*!
@brief  Checks whether a data title is the latest version.

This function blocks because it involves communication.

@param[out] pIsLatestVersion  Stores whether it is the latest version.

@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 ResultInvalidArgument  Indicates that an argument is invalid.
@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.

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

//! @}
//! @name  Error Handling
//! @{

/*!
@brief  Gets the error code from the processing result.

If the result of the process was <tt>@ref ResultServerError</tt>, the error code retrieved by this function must not be configured in the error viewer.

@param[in] result  Specifies the <tt>result</tt>.

@return  The error code.

@see  GetLastServerErrorMessage
@see  <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925064">Programming Manual</a>
*/
s32 GetErrorCode(const nn::Result& result);

/*!
@brief  Gets the message for the last server error that occurred.

If the result of a process was <tt>ResultServerError</tt>, configure the error viewer with the title and message retrieved with this function and display them to the user. @n
You do not, however, need to do this for processes that do not affect the system as a whole when they fail, such as background communication and metadata downloading.

This function blocks while communication is taking place.

@param[out] pTitle  Stores the title to set in error viewer. @n
There must be at least <tt>@ref SERVER_ERROR_TITLE_SIZE </tt> elements in the buffer.
@param[out] pMessage  Stores the message to set in error viewer. @n
There must be at least <tt>@ref SERVER_ERROR_MESSAGE_SIZE </tt> elements in the buffer.

@return  The result of processing.

@retval Result::IsSuccess  Indicates success.
@retval ResultNotInitialized  Indicates that the library is not initialized.
@retval ResultInvalidArgument  Indicates that an argument is invalid.

@see  <a class="el" href="../../Doc/EcdkProgrammingManual/contents/Pages/Page_48711722.html#PageId_48925064">Programming Manual</a>
*/
nn::Result GetLastServerErrorMessage(char16* pTitle, char16* pMessage);

//! @}

//! @}

}} // namespace nn::ec

#endif // NN_EC_API_H_