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

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_TITLE_H_
#define NN_BOSS_BOSS_TITLE_H_


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

#ifdef __cplusplus

namespace nn {
namespace boss {

/*!
@addtogroup  nn_boss_api
  @{
*/

/*!
@brief  Represents titles that use BOSS.
*/
class Title {
public:
/*!
@brief  Instantiates an object. Uses the title that initialized this instance, and the logged-in account at the time of the call.
*/
    explicit Title( void );

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

/*!
@brief  Changes the account the instance covers. Specifies the slot number of the account to change.

@param[in] slotNo  Specifies a slot in the target account. (A value of <tt>0</tt> specifies the current account.)
@return  Returns the execution result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates success.
@retval ResultInvalidParameter();  Indicates that an invalid slot number was specified in the parameter.
*/
    nn::Result ChangeAccount( u8 slotNo );


/*!
@brief  Sets the new arrival flag for the title to <tt>false</tt>.  

If for any reason the new arrival flag is set back to <tt>true</tt> after this function is called, new data for the title is received.
*/
    void SetNewArrivalFlagOff(void);


/*!
@brief  Gets the new arrival flag for the title.  

If the function returns <tt>true</tt>, new data for the title has been received.

@return  Returns the new arrival flag for the title. (Returns <tt>false</tt> if there is no title information.)
*/
    bool GetNewArrivalFlag( void ) const;


/*!
@brief  Sets the <tt>OptOut</tt> flag of the title.

The act of enabling this flag (setting it to <tt>true</tt>) is called "notification opt-out." This setting causes notifications for the title to not be received.
The act of disabling this flag (setting it to <tt>false</tt>) is called "notification opt-in." This setting causes notifications for the title to be received.
Notifications for a title are received if this flag has never been set. (The default value of this flag is <tt>false</tt>.)

The value of the <tt>OptOut</tt> flag is recorded in a database for managing title information on the system.
Registering an NBDL task for a title is a trigger for the creation of a new database and the addition of a title entry to the database.
(If this is the first time an NBDL task has been registered for an account on the system, a new database is created and a new entry for the title is added.
After that, new title entries are added when NBDL tasks are registered for those new titles.)
As a result, this function returns either the <tt>@ref ResultRecordNotExist</tt> error or the <tt>@ref ResultDbNotExist</tt> error if called on a title for which no NBDL tasks have ever been registered.
(The title entry for a title is removed from the database if you delete the title in Download Management. This function returns an error if called on that title.)
Only use this function on titles for which an NBDL task has been registered.

@param[in] flag  Specifies the <tt>OptOut</tt> flag. If <tt>true</tt>, notifications for the corresponding title are not received.
@return  Returns the execution result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Successfully set.
@retval ResultRecordNotExist  The specified title information does not exist.
@retval ResultDbNotExist  There is no database for managing the title information.

*/
    nn::Result SetOptoutFlag(bool flag);

/*!
@brief  Gets the <tt>OptOut</tt> flag for the title.

If the <tt>OptOut</tt> flag is set to <tt>true</tt>, notifications for that title are not received when they are sent out.
This is disabled if the flag is set to <tt>false</tt>. Notifications associated with the title in question are received.
Notifications for a title are received if this flag has never been set. (The default value of this flag is <tt>false</tt>.)

The value of the <tt>OptOut</tt> flag is recorded in a database for managing title information on the system.
For more information, see the <tt>@ref SetOptoutFlag</tt> reference material.
As explained in the API reference, this function cannot be used on titles for which there are no entries in the database (such as titles for which no NBDL tasks have been registered).
If you call this function on such titles, it returns <tt>false</tt> and you cannot get the value of the <tt>OptOut</tt> flag.
(A BOSS library error log may also be output.)
Only use this function on titles for which an NBDL task has been registered.

@return  Returns the <tt>OptOut</tt> flag value. (Returns <tt>false</tt> if there is no title information.)
*/
    bool GetOptoutFlag( void ) const;

/*!
@deprecated  This API function is outdated. Do not use.
*/
    explicit Title( AccountID accountId, TitleID titleId);

protected:
/*!
@brief  Specifies the account ID.
*/
    AccountID m_accountId;
    u8 padding[4];

/*!
@brief  Specifies the title ID.
*/
    TitleID m_titleId;
}; //end of class

//! @}

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

#endif // __cplusplus

#endif /* NN_BOSS_BOSS_TITLE_H_ */