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

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_BOSS_BOSS_NBDLDATALIST_H_
#define NN_BOSS_BOSS_NBDLDATALIST_H_

#include <nn/boss/boss_Const.h>
#include <nn/boss/boss_Result.h>
#include <nn/boss/boss_Types.h>
#include <nn/boss/boss_NetTaskSetting.h>
#include <nn/boss/boss_Task.h>

#ifdef __cplusplus

namespace nn {
namespace boss {

/*!
@addtogroup  nn_boss_api
  @{
*/

/*!
@brief  Class that bears an NBDL data list.
*/
class NbdlDataList : public NetTaskSetting
{
    friend class AlmightyNbdlDataList;

public:
    static const u32 DOWNLOAD_DEFAULT_TIMEOUT_SEC = 60; //!< Standard timeout for <tt>NbdlDataList::Download</tt> in seconds.

    static const u32 ATTRIBUTE_MAX_LENGTH_WITH_NULL = 10;    //!< Maximum length of the attribute value for data attributes (including the <tt>NULL</tt> terminating character).
    static const u32 DESCRIPTION_MAX_LENGTH_WITH_NULL = 512; //!< Maximum length of the description value for data attributes (including the <tt>NULL</tt> terminating character).

    /*!
@brief  Enumerates the type of data. The value of the type of a data attribute is one of the enumerands in this type.
*/
    enum DataType
    {
        DATATYPE_APPDATA = 0,     //!< Extra Data
        DATATYPE_MESSAGE = 1,     //!< Notifications
    };

    /*!
@brief  Stores the attribute values of each data item. The NBDL data list is retrieved as an array of this structure.

The size is 584 bytes.
*/
    struct DataAttributes
    {
        u64  size;                                           //!< Data size.
        char name[NSDATA_NAME_MAX_LENGTH_WITH_NULL];         //!< Data name.
        char attribute1[ATTRIBUTE_MAX_LENGTH_WITH_NULL];     //!< Attribute 1
        char attribute2[ATTRIBUTE_MAX_LENGTH_WITH_NULL];     //!< Attribute 2
        char attribute3[ATTRIBUTE_MAX_LENGTH_WITH_NULL];     //!< Attribute 3
        u16  type;                                           //!< Data type.
        char description[DESCRIPTION_MAX_LENGTH_WITH_NULL];  //!< Description
    };

    static const u32 OPTION_GET_MESSAGE_ATTRIBUTE_TOGETHER = 0x00000001; //!< By default, only the data attributes of application data are retrieved, but this option can also be used to retrieve the data attributes of notification data.


/*!
@brief  Instantiates an object.
*/
    explicit NbdlDataList(void);

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

/*!
@brief  Downloads an NBDL data list.

NBDL data lists run as dedicated immediate-execution tasks.  <br/>
A different dedicated immediate-execution task cannot be registered while an NBDL data list is downloading. <br/>

This function communicates with the server and might take several seconds to complete. <br/>
You can cancel this function using <tt>@ref Cancel</tt>. <br/>

@param[out] pDataAttributes  Pointer to the buffer that stores the NBDL data list. The maximum size of the data list is <tt>sizeof( @ref DataAttributes) * @ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. You can always retrieve the data list if you set a buffer size of at least this amount. If the size is too small, this function downloads the amount of entries that fit in the buffer.
@param[in] dataAttributesSize  The size of <var>pDataAttributes</var>.
@param[out] pDataCount  The number of data items included in the NBDL data list. If the entire data list could not be retrieved because <var>pDataAttributes</var> was not large enough, this value represents the number of data items included in the data list downloaded from the server, not the number of data items stored in <var>pDataAttributes</var>.
@param[in] bossCode  The BOSS code. (The code that is assigned to each application that uses NBDL. You can check this code from the BOSS data server management tool after your application for use of NBDL tasks has been approved by Nintendo.))
@param[in] targetTaskId  ID of the task for which to get the NBDL data list.
@param[in] directoryName  The name of the directory that stores the data. Normally, you can omit this setting. When omitted, the task ID is used for the directory name. The <tt>@ref Storage</tt> class uses this directory name when retrieving a list of files. If you omit the directory name, specify the task ID in the <tt>@ref Storage</tt> class. (There are special cases where this argument must be specified explicitly. For more information, see the BOSS Programming Manual.)
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successful download.
@retval ResultFail  Indicates that the download failed. You can get details about the failure by calling <tt>@ref GetLastDownloadResult</tt>.
@retval ResultNotCompleted  Specifies that the download timed out.
@retval ResultCanceled  Specifies that the download was canceled.
@retval Other  Specifies that an error occurred before the download began. (See <tt>@ref nn_boss_result</tt> for the error.)
*/
    nn::Result Download(DataAttributes pDataAttributes[NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY], size_t dataAttributesSize, u32* pDataCount, const char* bossCode, const char* targetTaskId, const char* directoryName = NULL);

/*!
@brief  Downloads the NBDL data list for a specific account.

NBDL data lists run as dedicated immediate-execution tasks.  <br/>
A different dedicated immediate-execution task cannot be registered while an NBDL data list is downloading. <br/>

This function communicates with the server and might take several seconds to complete. <br/>
You can cancel this function using <tt>@ref Cancel</tt>. <br/>

@param[out] pDataAttributes  Pointer to the buffer that stores the NBDL data list. The maximum size of the data list is <tt>sizeof( @ref DataAttributes) * @ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>. You can always retrieve the data list if you set a buffer size of at least this amount. If the size is too small, this function downloads the amount of entries that fit in the buffer.
@param[in] dataAttributesSize  The size of <var>pDataAttributes</var>.
@param[out] pDataCount  The number of data items included in the NBDL data list. If the entire data list could not be retrieved because <var>pDataAttributes</var> was not large enough, this value represents the number of data items included in the data list downloaded from the server, not the number of data items stored in <var>pDataAttributes</var>.
@param[in] bossCode  The BOSS code. (The code that is assigned to each application that uses NBDL. You can check this code from the BOSS data server management tool after your application for use of NBDL tasks has been approved by Nintendo.))
@param[in] slotNo  Slot number of the target account.
@param[in] targetTaskId  ID of the task for which to get the NBDL data list.
@param[in] directoryName  The name of the directory that stores the data. Normally, you can omit this setting. When omitted, the task ID is used for the directory name. The <tt>@ref Storage</tt> class uses this directory name when retrieving a list of files. If you omit the directory name, specify the task ID in the <tt>@ref Storage</tt> class. (There are special cases where this argument must be specified explicitly. For more information, see the BOSS Programming Manual.)
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successful download.
@retval ResultFail  Indicates that the download failed. You can get details about the failure by calling <tt>@ref GetLastDownloadResult</tt>.
@retval ResultNotCompleted  Specifies that the download timed out.
@retval ResultCanceled  Specifies that the download was canceled.
@retval Other  Specifies that an error occurred before the download began. (See <tt>@ref nn_boss_result</tt> for the error.)
*/
    nn::Result Download(DataAttributes pDataAttributes[NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY], size_t dataAttributesSize, u32* pDataCount, const char* bossCode, u8 slotNo, const char* targetTaskId, const char* directoryName = NULL);

/*!
@brief  Cancels the download of an NBDL data list.

Use this function when you want to cancel <tt>@ref NbdlDataList::Download</tt>, which is a blocking function.
*/
    void Cancel(void);

/*!
@brief  Gets details of the execution results for <tt>@ref NbdlDataList::Download</tt>.

You can get the execution results for the last time <tt>@ref NbdlDataList::Download</tt> was executed.

@return  Returns the execution results for the last time <tt>@ref NbdlDataList::Download</tt> was executed.
*/
    TaskResult GetLastDownloadResult(void);

/*!
@brief  Sets the name of the file to download. Use this function to retrieve the attribute information only for a specific file.

@param[in] fileName  Name of the file to download. The maximum length of the strings that can be specified for filenames (including the terminating null character) is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successful retrieval.
@retval ResultInvalidParameter  A parameter is invalid. (For example, <var>fileName</var> is <tt>NULL</tt>.)
*/
    nn::Result SetFileName(const char* fileName);

/*!
@brief  Sets the language code of data to include in the NBDL data list.

By default, the NBDL data list includes data that matches the language in System Settings, but you can download a data list for a specific language using this function.

@param[in] language  The language to set. Set a two-character language code based on ISO 639-1 alpha-2.

@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidParameter  Indicates an invalid parameter.

*/
    nn::Result SetLanguageCodeA2(const char* language);

/*!
@brief  Sets the country of the data to include in the NBDL data list.

By default, the NBDL data list includes data that matches the country in System Settings, but you can download a data list for a specific country using this function.

@param[in] country  The country to set. Set a two-character country code based on ISO 3166-1 alpha-2.

@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidParameter  Indicates an invalid parameter.

*/
    nn::Result SetCountryCodeA2(const char* country);

/*!
@brief  Sets the timeout time for downloading the NBDL data list.

The standard timeout time of <tt>@ref DOWNLOAD_DEFAULT_TIMEOUT_SEC</tt> is used if no value is set.

@param[in] timeoutSec  Specifies the timeout value to set in seconds.
*/
    void SetTimeoutSec(u32 timeoutSec);

/*!
@brief  Sets the options that specify the functionality of NBDL data list tasks.

@param[in] option  Specifies the option to set.
@return  Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates successful retrieval.
@retval ResultInvalidParameter  Indicates an invalid parameter.
*/
    nn::Result SetOption(u32 option);

private:
    u32        m_TimeoutSec;
    Task       m_DownloadTask;
    TaskResult m_LastResult;
    TitleID    m_TitleId;

    nn::Result DoDownload(DataAttributes pDataAttributes[NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY], size_t dataAttributesSize, u32* pDataCount, const char* bossCode, u8 slotNo, const char* targetTaskId, const char* directoryName);
//! @}

};

} // end of namespace boss
} // end of namespace nn

#endif // __cplusplus

#endif /* NN_BOSS_BOSS_NBDLDATALIST_H_ */