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

Copyright (C) 2012 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_BOSSSTORAGE_H_
#define NN_BOSS_BOSS_BOSSSTORAGE_H_

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

#ifdef __cplusplus

namespace nn {
namespace boss {

/*!
@addtogroup nn_boss_api
  @{
*/

class NsData;

/*!
@brief        Class that represents BOSS storage.

Used for purposes such as checking for the existence of BOSS storage, retrieving a list of the <tt>@ref NsData</tt> names in BOSS storage, and clearing the history information recorded in BOSS storage for avoiding duplicate downloads.
Also, when creating an instance of the <tt>@ref NsData</tt> class, you must pass the instance of this class to a constructor to specify its BOSS storage location.
*/
class Storage
{
public:
/*!
@brief Instantiates the object. The information required to use an instance is not set in this constructor. Use the <tt>@ref Initialize</tt> function to configure this class.

*/
    explicit Storage( void );

/*!
@brief Instantiates the object and calls <tt>@ref Initialize</tt>. This function targets the account that is logged in when the function is called.

@param[in]    directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name.
@param[in]    storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>.
*/
    explicit Storage( const char* directoryName, StorageKind storageKind = BSKIND_NBDL );

/*!
@brief Instantiates the object and calls <tt>@ref Initialize</tt>. Specifies a slot in the target account.

@param[in]    slotNo     Specifies a slot in the target account.
@param[in]    directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name.
@param[in]    storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>.
*/
    explicit Storage( u8 slotNo, const char* directoryName, StorageKind storageKind = BSKIND_NBDL );

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

/*!
@brief Initializes the instance. This function targets the account that is logged in when the function is called.

@param[in]    directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name.
@param[in]    storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval ResultInvalidParameter  Indicates that the task ID is invalid.
*/
    nn::Result Initialize(const char* directoryName, StorageKind storageKind = BSKIND_NBDL);

/*!
@brief Initializes the instance.

@param[in]    slotNo     Specifies a slot in the target account.
@param[in]    directoryName The directory. If a directory is not explicitly specified when the task is registered, the task ID is usually the same as the directory name.
@param[in]    storageKind The storage type. If not specified, NBDL-type BOSS storage is specified by default. If you want to specify RawDL task storage, specify <tt>@ref BSKIND_RAWDL</tt>. If you want to specify <tt>DataStore</tt> task storage, specify <tt>@ref BSKIND_DATASTORE</tt>.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval ResultInvalidParameter  Indicates that the task ID is invalid.
*/
    nn::Result Initialize( u8 slotNo, const char* directoryName, StorageKind storageKind = BSKIND_NBDL);

    /*!
@brief Finalizes the class instance.

Also called from the destructor.
    */
    void Finalize( void );

/*!
@brief Copy constructor.
*/
    Storage( const Storage& obj );

/*!
@brief        Checks whether BOSS storage exists.

@return       Whether BOSS storage exists. (<tt>true</tt> indicates that it exists.)
*/
    bool Exist() const;


/*!
@brief        Returns a list of names for NS data in the BOSS storage.

When the storage type is <tt>@ref BSKIND_NBDL</tt>, the data names are stored in the order of most recently downloaded.

@param[out]   dataNameList   A buffer for storing a list of data names. When the storage type is <tt>@ref BSKIND_NBDL </tt>, all of the data names can be obtained in one call by specifying a buffer with a number of elements equal to or greater than <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>.
@param[in]    elementCount   The number of elements in <span class="argument">dataNameList</span>.
@param[out]   getDataCount   Buffer where the number of data names obtained is stored.
@param[in]    startPos       Specifies the position, among all data names, of the first element of the data name to get. You can call this function repeatedly, by using a <span class="argument">dataNameList</span> with a small number of elements, to get all of the data names. If omitted, elements are obtained starting with the first element in the list of the data names.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval       ResultNotExist              The specified storage or directory does not exist.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result GetDataList(DataName dataNameList[],  u32 elementCount, u32* getDataCount, u32 startPos = 0) const;

/*!
@brief        Returns a list of names of unread data in the BOSS storage.

When the storage type is <tt>@ref BSKIND_NBDL</tt>, the data names are stored in the order of most recently downloaded.

@param[out]   dataNameList   A buffer for storing a list of data names. For the <tt>BSKIND_NBDL</tt> type, you can reliably retrieve all of the data names at one time by specifying a buffer that has <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt> or more elements.
@param[in]    elementCount   The number of elements in <span class="argument">dataNameList</span>.
@param[out]   getDataCount   Buffer where the number of data names obtained is stored.
@param[in]    startPos       Specifies the position, among all data names, of the first element of the data name to get. You can call this function repeatedly, by using a <span class="argument">dataNameList</span> with a small number of elements, to get all of the data names. If omitted, elements are obtained starting with the first element in the list of the data names.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval       ResultNotExist              The specified directory does not exist.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result GetUnreadDataList(DataName dataNameList[],  u32 elementCount, u32* getDataCount, u32 startPos = 0) const;

/*!
@brief        <b>Note:</b> Do not use this function. Use the <tt>@ref ClearAllHistories</tt> function instead. This function remains for compatibility with an earlier version of the SDK.

Clears history information that is used to avoid duplicated downloads that are stored in BOSS storage. This method can only be used for NBDL-type BOSS storage.
*/
    void ClearHistory( void );

/*!
@brief        Clears history information recorded in BOSS storage for avoiding duplicated downloads. This method can only be used for NBDL-type BOSS storage.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that initialization succeeded.
@retval       ResultNotExist              The specified directory does not exist.
@retval       ResultNoSupport             Storage is not supported. History information is only recorded for NBDL-type BOSS storage.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result ClearAllHistories( void );

/*!
@brief        Returns the directory name.

@return       The directory name. The name specified in the constructor or the <tt>@ref Initialize</tt> function.
*/
    const char* GetDirectoryName() const{return m_directoryName;}

/*!
@brief        Returns the persistent ID for the target account.

@return       Persistent ID for the target account. The ID specified in the constructor or the <tt>@ref Initialize</tt> function.
*/
    AccountID   GetAccountId()     const{return m_accountId;}

/*!
@brief        Returns the title ID for the target account.

@return       Title ID for the target account. The ID specified in the constructor or the <tt>@ref Initialize</tt> function.
*/
    TitleID     GetTitleId()       const{return m_titleId;}

/*!
@brief        Returns the storage type.

@return       The storage type. The ID specified in the constructor or the <tt>@ref Initialize</tt> function.
*/
    StorageKind GetKind()          const{return m_storageKind;}

/*!
@brief        As a batch process, sets the already read flags for multiple data in storage to <tt>true</tt> or <tt>false</tt>.

@param[in]    nsDataNames  An array of data names to get the read flags for. The maximum size for a single data name is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. The maximum number of data names is <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>.
@param[in]    dataCount    The number of data names to set.
@param[in]    flag         The flag to set.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval       Other                   Unexpected error. For cases such as when an error is returned from FS.
*/
    nn::Result SetReadFlagToNsDatas(const DataName nsDataNames[], u32 dataCount, bool flag);

/*!
@brief        Sets the read flag for multiple data names in storage. Specifies the flag for each data file individually.

@param[in]    nsDataNames  An array of data names to get the read flags for. The maximum size for a single data name is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. The maximum number of data names is <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>.
@param[in]    dataCount    The number of data names to set.
@param[in]    pFlags       The flags to set. Each value is set according to the data in <span class="argument">nsDataNames</span>.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval       Other                   Unexpected error. For cases such as when an error is returned from FS.
*/
    nn::Result SetReadFlagToNsDatas(const DataName nsDataNames[], u32 dataCount, bool pFlags[]);

/*!
@brief        Gets the read flags for multiple data names in storage.

@param[in]    nsDataNames  An array of data names to get the read flags for. The maximum size for a single data name is <tt>@ref NSDATA_NAME_MAX_LENGTH_WITH_NULL</tt>. The maximum number of data names is <tt>@ref NBDL_DATA_MAX_COUNT_IN_DOWNLOAD_DIRECTORY</tt>.
@param[in]    dataCount  The number of data names.
@param[in]    pFlags     A buffer that holds the retrieved read flags. The number of elements must be equal to or greater than <span class="argument">dataCount</span>.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval       Other                   Unexpected error. For cases such as when an error is returned from FS.
*/
    nn::Result GetReadFlagFromNsDatas(const DataName nsDataNames[], u32 dataCount, bool pFlags[]) const;

/*!
@deprecated This API function is outdated. Do not use it.
*/
    explicit Storage( const char* directoryName, AccountID accountId, StorageKind storageKind = BSKIND_NBDL);

/*!
@deprecated This API function is outdated. Do not use it.
*/

    nn::Result Initialize(const char* directoryName, AccountID accountId, StorageKind storageKind = BSKIND_NBDL);

protected:
    AccountID m_accountId;
    StorageKind m_storageKind;
    u8 padding[3];
    char m_directoryName[BOSSSTORAGE_DIRECTORY_NAME_MAX_LENGTH_WITH_NULL];
    TitleID   m_titleId;


};

//! @}

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

#endif // __cplusplus

#endif /* NN_BOSS_BOSS_BOSSSTORAGE_H_ */