xref: /CafeSDK-2.12.13/system/include/nn/boss/boss_Task.h

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

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_TASK_H_
#define NN_BOSS_BOSS_TASK_H_

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


#ifdef __cplusplus

namespace nn {
namespace boss {

/*!
@addtogroup nn_boss_api
  @{
*/

/*!
@brief Represents a task. Used to register and start tasks and to manipulate them or access their attributes.
*/
class Task
{
    friend class NbdlDataList;

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 Task(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]    taskId     Specifies the task ID. The maximum length, including the terminating null character, is defined by <tt>@ref TASK_ID_LENGTH_WITH_NULL</tt>.
*/
    explicit Task( const char* taskId );

/*!
@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]    taskId     Specifies the task ID. The maximum length, including the terminating null character, is defined by <tt>@ref TASK_ID_LENGTH_WITH_NULL</tt>.
*/
    explicit Task( u8 slotNo, const char* taskId );

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

/*!
@brief Initializes the registered task with the specified task ID. This initialization enables the reuse of objects. This function targets the account that is logged in when the function is called.

@param[in]    taskId     Specifies the task ID. The maximum length, including the terminating null character, is defined by <tt>@ref TASK_ID_LENGTH_WITH_NULL</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.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result Initialize(const char* taskId );

/*!
@brief Initializes the registered task with the specified task ID. This initialization enables the reuse of objects. Specifies a slot in the target account.

@param[in]    slotNo     Specifies a slot in the target account.
@param[in]    taskId     Specifies the task ID. The maximum length, including the terminating null character, is defined by <tt>@ref TASK_ID_LENGTH_WITH_NULL</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.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result Initialize( u8 slotNo, const char* taskId );

/*!
@brief Finalizes the class instance.

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

/*!
@brief Checks whether a task is registered.

@return Returns whether the task is registered. <tt>true</tt> if the task is registered.
*/
    bool       IsRegistered( void ) const;


/*!
@brief        Registers a task.

Use <tt>@ref Initialize</tt> to set the IDs (the task ID and persistent ID) of the task to register.
Set the attributes for the task to register in an instance of the <tt>@ref TaskSetting</tt> subclass specified in the parameters.

The information for tasks registered with this function is held in the system and made persistent. <br />
This enables the task to run in the background even across being powered down, or while a menu or other application is running. <br />
Do not use this function if you only want to use the task in the foreground (that is, you want to register this task and execute it immediately only while the application is running, and you do not want to run it in the background while the menu or other application is running). Instead, use the <tt>@ref RegisterForImmediateRun</tt> function to register it as a dedicated immediate-execution task. <br />

Tasks do not operate just by being registered. <br />
Depending on the desired operations, start by using either the <tt>@ref Task::StartScheduling</tt> or <tt>@ref Task::Run</tt> function. <br />
To halt a started task, use the <tt>@ref Task::StopScheduling</tt> function if you started the task using <tt>@ref Task::StartScheduling</tt>, or use <tt>@ref Task::Cancel (CANCEL_TO_STOP)</tt> or <tt>@ref Task::CancelSync (CANCEL_TO_STOP)</tt> if you started the task using <tt>@ref Task::Run</tt>. <br />

The success conditions for registering tasks are as follows. <br />
- Invalid values are not set in the <tt>TaskSetting</tt> specified in the parameters. <br />
- The account from which the task was registered is tied to the network account. (If no account was explicitly specified, it is the account that was logged in when the task was registered.) <br />
- The <b>Online Interaction in Games</b> option is not prohibited by the Parental Controls of the account from which the task was registered. <br />

The first condition is met as long as the <tt>TaskSetting</tt> member functions are being used correctly. <br />
If these conditions are not being met, this function returns an error. If you want to register a task that does not match these conditions, please contact Nintendo. <br />


@param[in] taskSetting  Specifies the task settings.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values. Something other than <tt>Result::IsSuccess</tt> is an error, and the task registration has failed.
@retval Result::IsSuccess  Indicates that registration succeeded. <br />
@retval ResultInvalidParameter  Indicates that the task settings contain an invalid value.
@retval ResultInvalidFormat  Indicates that the format of the task settings is invalid.
@retval ResultFull  Indicates that the maximum number of tasks are already registered.
@retval ResultAlreadyExist  Indicates that the same task (a task with the same task ID and the same persistent ID) has already been registered.
@retval ResultNotExist  Indicates that there is no account with the specified persistent ID.
@retval ResultNotNetworkAccount  Indicates that the account with the specified persistent ID is not associated with a network account.
@retval ResultRestrictedByParentalControl  Indicates that Internet communication, including the SpotPass service, is restricted by the <b>Online Interaction in Games</b> option in Parental Controls for the account with the specified persistent ID.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. <br />
If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br />
Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)




*/
    nn::Result Register(TaskSetting& taskSetting );


/*!
@brief Registers a dedicated immediate-execution task.

Tasks registered with this function are exclusively for immediate execution. They are not persistent and are deleted if the system is restarted. In all other respects, they have the same specifications as tasks registered with the <tt>@ref Register</tt> function.
For more information, see <tt>@ref Register</tt>.

@param[in] taskSetting  Specifies the task settings.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values. Something other than <tt>Result::IsSuccess</tt> is an error, and the task registration has failed.
@retval Result::IsSuccess  Indicates that registration succeeded. <br />
@retval ResultInvalidParameter  Indicates that the task settings contain an invalid value.
@retval ResultInvalidFormat  Indicates that the format of the task settings is invalid.
@retval ResultFull  Indicates that the maximum number of tasks are already registered.
@retval ResultAlreadyExist  Indicates that the same task (a task with the same task ID and the same persistent ID) has already been registered. <br />
Alternately, indicates that a dedicated immediate-execution task with the same persistent ID has already been registered.
@retval ResultNotExist  Indicates that there is no account with the specified persistent ID.
@retval ResultNotNetworkAccount  Indicates that the account with the specified persistent ID is not associated with a network account.
@retval ResultRestrictedByParentalControl  Indicates that Internet communication, including the SpotPass service, is restricted by the <b>Online Interaction in Games</b> option in Parental Controls for the account with the specified persistent ID.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. <br />
If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br />
Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result RegisterForImmediateRun(const TaskSetting& taskSetting );


/*!
@brief Allows the settings information for a registered task to be changed.

@param[in] taskSetting  Specifies the task settings.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that registration succeeded. <br />
@retval ResultInvalidParameter  Indicates a failure to register the task because the task settings are invalid. Details of the cause are stored in <span class="argument">pResultDetail</span>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. <br />
If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br />
Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result Reconfigure(const TaskSetting& taskSetting );



/*!
@brief Deletes a registered task.

If the task is running, it is first canceled, and then deleted. <br />

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that deletion succeeded.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. <br />
If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br />
Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result Unregister(void);


/*!
@brief Updates the execution interval for a task after registration. You can change this interval even after a task has been instructed to start executing.

@param[in] intervalHour  Specifies the interval at which to execute the task. The unit is hours.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the execution interval was updated successfully.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    inline nn::Result UpdateInterval(u32 intervalHour){return UpdateIntervalSec(intervalHour*60*60);}

/*!
@brief [For debugging only. In production, execution intervals are only approved if they are measured in hours. Use the <tt>@ref UpdateInterval</tt> function when you are not debugging. ] Updates the execution interval for a task after registration. The unit is seconds. You can change this interval even after a task has been instructed to start executing.

@param[in] intervalSec  Specifies the execution interval. The unit is seconds.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the execution interval was updated successfully.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result UpdateIntervalSec(u32 intervalSec);

/*!
@brief Updates the lifetime of a registered task. You can change this interval even after a task has been instructed to start executing.

@param[in]    lifeTimeHourFromNow       The time (in hours) from now at which to execute the task.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the lifetime was updated successfully.
@retval ResultServiceFinished  Indicates that the service related to the task has already terminated.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    inline nn::Result UpdateLifeTime(u32 lifeTimeHourFromNow){return UpdateLifeTimeSec(lifeTimeHourFromNow*60*60);}

/*!
@brief [For debugging only. In production, the task lifetime must be in hours. Use the <tt>@ref UpdateLifeTime</tt> function when you are not debugging. ] Updates the task lifetime after task registration. You can change this interval even after a task has been instructed to start executing.

@param[in]    lifeTimeSecFromNow       The time (in seconds) from now at which to execute the task.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess  Indicates that the lifetime was updated successfully.
@retval ResultServiceFinished  Indicates that the service related to the task has already terminated.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result UpdateLifeTimeSec(s64 lifeTimeSecFromNow);


/*!
@brief Gets the execution interval. The unit is hours.

@return Returns the execution interval. <BR>
*/
    inline u32 GetInterval(void) const
    {
        const u32 intervalSec = GetIntervalSec();
        return (intervalSec / (60*60));
    }

/*!
@brief Gets the execution interval. The unit is seconds.

@return Returns the execution interval. <BR>
*/
    u32 GetIntervalSec(void) const;

/*!
@brief Gets the lifetime of the task. The unit is hours.

@return Returns the lifetime. The unit is hours. <br />
*/
    inline u32 GetLifeTime(void) const
    {
        const s64 secLifeTime = GetLifeTimeSec();
        return (secLifeTime / (60*60));
    }

/*!
@brief Gets the lifetime of the task. The unit is seconds.

@return Returns the lifetime. The unit is seconds. <br />
*/
    s64 GetLifeTimeSec(void) const;


/*!
@brief Gets the remaining lifetime of the task. The unit is seconds.

@return Returns the remaining lifetime of the task. The unit is seconds. <br />
*/
    s64 GetRemainingLifeTimeSec(void) const;

/*!
@brief Gets the target URL for task execution.
Returns an empty string for NBDL tasks.

@param[out] url  Specifies the URL for which the task is executed.
@param[in] urlLength  Specifies the length of <span class="argument">url</span>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result GetUrl(char url[], u32 urlLength) const;

/*!
@brief Checks whether a task has finished executing.

For a task with a specified lifetime, returns <tt>true</tt> if the lifetime has completed.
<br />
For a one-time execution task, only returns <tt>true</tt> after it has completed execution. <br />
(This relates only to whether execution has completed, and not the task result. <tt>true</tt> is returned if execution has completed, even if the result is an error.)<br />
This method returns <tt>false</tt> when it is called while the task is running. <br />

@return Returns whether task execution has completed. Returns <tt>true</tt> if it has completed.
*/
    bool IsFinished(void) const;

/*!
@brief Renews the task lifetime.

For a task with a specified lifetime, calling this method gives the task a new lifetime equal in length to the lifetime of the task when it was initially registered, and starting from the time the method is called.
For a one-time task, the task enters a state to be run once more, and is executed one execution interval after the method is called. <br />

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval ResultServiceFinished  Indicates that the service related to the task has already terminated.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result RestoreLifeTime(void);


/*!
@brief Gets the service status of a task.

Applications can check the status of a service when they detect a notification from the server that indicates that the service was discontinued.
<b>Note:</b> If the server has not been accessed since the task was registered, the status is <tt>@ref SERVICE_UNKNOWN</tt>.

@return  Returns the service status of a task. <br />
*/
    TaskServiceStatus GetServiceStatus(void) const;

/*!
@brief Gives an instruction to start scheduled execution of the task.

The scheduled tasks automatically run in the background when infrastructure connections are enabled. <br />
<br />
The <span class="argument">isFirstRunImmediate</span> parameter setting affects the timing of when the task right after <tt>RegisterTask</tt> runs for the first time. <br />
If <span class="argument">isFirstRunImmediate</span> is set to <tt>true</tt> (or if the argument is omitted), the task is immediately ready to run for the first time when the function is called. The task runs as soon as the system makes an infrastructure connection following the function call. <BR>
If <span class="argument">isFirstRunImmediate</span> is <tt>false</tt>, the task is executed for the first time one execution interval after this method is called. <BR>
<BR>
If this method is called to resume a task that was stopped by the <tt>@ref StopScheduling</tt> function, the <span class="argument">isFirstRunImmediate</span> parameter is ignored and the task resumes from the state it was in when it was stopped by the <tt>@ref StopScheduling</tt> function. <br />
<br />
When execution of a task completes, if the time at one execution interval after that point is within the task lifetime, the task runs again after one execution interval. <br />
(A one-time execution task is not executed subsequently.))
In the following circumstances, tasks are not executed even if a command is issued to start a task. <br />
- The execution priority of the task is <tt>@ref PRIORITY_STOPPED</tt>.
- Parental Controls are enabled, and the attributes of the task do not override Parental Controls.
- The user has not accepted the EULA, and the attributes of the task do not override EULA acceptance.
- A policy list blocks task execution.
- The application has paused all tasks.
<br />
The following methods can be used to wait for task completion. <br />
- Use the <tt>@ref Wait</tt> function to wait until execution completes.
- Use the <tt>@ref Wait</tt> function to wait until execution completes, specifying a maximum wait time.
- Use the <tt>@ref GetTurnState</tt> function to poll for task completion.
<br />
After completion has been detected, you can use the <tt>@ref GetState</tt> function to check the task's status, the <tt>@ref GetResult</tt> function to check its result code, and the <tt>@ref GetHttpStatusCode</tt> function to check the HTTP communication result code. <br />
<br />

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval ResultNotInitialized  Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>.
@retval ResultNotExist  Indicates that the specified task has not been registered.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)



*/
    nn::Result StartScheduling(bool isFirstRunImmediate = true);

/*!
@brief Immediately executes a task.

If <span class="argument">isForegroundRun</span> is <tt>true</tt>, the task runs in the foreground. In this case, the user must already have connected to the infrastructure network, and the task is run on that connection.
If a task running in the foreground is canceled—for example, because of loss of connection—the task generates an error and does not enter a waiting-for-retry state. <br />
Use this method to run a task using the high-priority communication provided in the foreground. <br />
<br />
If <span class="argument">isForegroundRun</span> is <tt>false</tt> (or is omitted), the task runs in the background. In this case, an infrastructure network connection is created in the background, and the task runs according to the permissions for using BOSS. <br />
If a task running in the background is canceled—for example, because of loss of connection—the task enters a waiting-for-retry state and no error is generated. <br />
A task in the waiting-for-retry state creates a connection to the infrastructure network in the background, and resumes execution according to permissions for using BOSS. <br />
This function can be used when the user wants to run a task immediately, when it would normally be run periodically in the background. <br />
<br />
When this method is used, if there is a task currently running, that task is suspended and the applicable task runs immediately. <br />
<b>Note:</b> There is a limit to the number of tasks that BOSS can run simultaneously in parallel. If multiple tasks are already running with this method at the same time, the task may not run immediately in some cases.


@param[in]    isForegroundRun      Specify whether to run in the foreground. If omitted, the task is run in the background.
@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval       Result::IsSuccess               The instruction to start the task immediately succeeded.
@retval       ResultNotConnectNetwork         Not connected to the infrastructure network. When running in the foreground, the user must connect to the infrastructure network before using this method.
@retval ResultInvalidTaskId  Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string.
@retval ResultNotExist  Indicates that the specified task ID was not found. Confirm whether it is registered yet.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval       ResultNotConnectNetwork         Although foreground execution was specified, the console is not connected to the infrastructure network. When running in the foreground, the call originator must have infrastructure network connection implemented using the AC library.
@retval       nn::ac::ResultNotAcInitialized  Although foreground execution was specified, the <tt>nn::ac::Initialize</tt> function has not been called. When running in the foreground, the call originator must have infrastructure network connection implemented using the AC library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result Run(bool isForegroundRun = false);


/*!
@brief Stops scheduled execution of a task.

You can use the <tt>@ref StartScheduling</tt> function to restart a task that has been suspended.
If a task has been suspended, calling the <tt>@ref GetState</tt> function returns <tt>@ref STOP</tt> as the state of the task.
If the applicable task is currently running, the task is canceled.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval ResultInvalidTaskId  Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string.
@retval ResultNotExist  Indicates that the specified task ID was not found. Confirm whether it is registered yet.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    nn::Result StopScheduling(void);

/*!
@brief Cancels execution of a task that is in progress. Unlike <tt>@ref CancelSync</tt>, this is an asynchronous function, only triggering a cancel and returning immediately.

This function is provided to stop immediate execution tasks.
It does nothing for tasks in a state other than <tt>RUNNING</tt>, <tt>WAITING_RUN</tt>, and <tt>WAITING_RESUME</tt>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval ResultInvalidTaskId  Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string.
@retval ResultNotExist  Indicates that the specified task ID was not found. Confirm whether it is registered yet.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    void Cancel(CancelMode cancelModel = CANCEL_TO_STOP);

/*!
@brief Cancels execution of a task that is in progress. Unlike <tt>@ref Cancel</tt>, this synchronous function blocks until cancellation of execution is completed.

This function is provided to stop immediate execution tasks.
It does nothing for tasks in a state other than <tt>RUNNING</tt>, <tt>WAITING_RUN</tt>, and <tt>WAITING_RESUME</tt>.

@return Returns the result of the function. Returns one of the following <tt>Result</tt> values.
@retval Result::IsSuccess Indicates success.
@retval ResultInvalidTaskId  Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string.
@retval ResultNotExist  Indicates that the specified task ID was not found. Confirm whether it is registered yet.
@retval ResultLibraryNotInitialized  Indicates that the session is not initialized. If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library.
@retval Other  Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.)
*/
    void CancelSync(CancelMode cancelModel = CANCEL_TO_STOP);

/*!
@brief Cancels execution of a task that is in progress. This function is the same as <tt>@ref CancelSync</tt>, except that it also has a timeout feature.

For more information, see the <tt>@ref CancelSync</tt> function, which is the same, but without a timeout feature.

It does nothing for tasks in a state other than <tt>RUNNING</tt>, <tt>WAITING_RUN</tt>, and <tt>WAITING_RESUME</tt>.
This function is provided to stop immediate execution tasks.

*/
    bool CancelSync(u32 timeoutMsec, CancelMode cancelModel = CANCEL_TO_STOP);



/*!
@brief Waits until a task assumes a certain state.

This method blocks until the applicable task enters the specified state.
@param[in] waitState  Specifies the waiting state. If this argument is omitted, the function waits for the default <tt>@ref TWS_DONE</tt> (task completed) state.
*/
    void Wait(TaskWaitState waitState = TWS_DONE);

/*!
@brief Waits until a task assumes a certain state. This is a version of the <tt>@ref Wait</tt> function that takes a time-out value as an argument.

For more information, see the version of the <tt>@ref Wait</tt> function that does not take a timeout value.

@param[in] timeoutSec  Specifies the timeout. The unit is seconds.
@param[in] waitState  Specifies the waiting state. If this argument is omitted, the function waits for the default <tt>@ref TWS_DONE</tt> (task completed) state.
@return Returns the reason for returning from the method. Either the task entered the specified state, or the timeout occurred.
@retval true  Indicates the task reached the specified state.
@retval false  Indicates that the task timed out.

*/
    bool Wait(u32 timeoutSec, TaskWaitState waitState = TWS_DONE);


/*!
@brief Gets the state of a task.

@param[out] pExecCount  Returns the task execution count for the status code being obtained.
@return Returns the task state. <br />
*/
    TaskState GetState( u32* pExecCount = NULL ) const;

/*!
@brief Gets the HTTP status code from the last time a task executed.

@param[out] pExecCount  Returns the task execution count for the status code being obtained.
@return Returns the HTTP status code from the last time a task executed. <br />
@retval 0  Indicates the status code could not be obtained. (Occurs when the task has not executed even once, or the task does not use HTTP communication.)
*/
    s32 GetHttpStatusCode( u32* pExecCount = NULL ) const;

/*!
@brief Gets the detailed result for the last time a task executed.

For more information about task results, see <tt>@ref TaskResult</tt>. <br />
This function cannot be used on tasks that have not yet been registered or executed. For example, if the <tt>@ref Task::Register</tt> function fails, this function cannot be used on that instance of that task. <br />
If this function is used on such a task, it returns a <tt>@ref TaskResult</tt> indicating that the result of the task is unknown. <br />

@param[out] pExecCount  Returns a number indicating which task execution the detailed results are for (1 for the first execution, 2 for the second, and so on).
@return Returns the result from the last task execution. <br />
*/
    TaskResult GetResult( u32* pExecCount = NULL ) const;

/*!
@brief Gets the state of the currently executing task turn.

If the task cannot yet be run (<tt>@ref TTS_WAITING_RUN</tt>), returns the result from the previous task turn.
Returns the task turn state at that time if the task has not run even once, or <tt>@ref ClearTurnState</tt> has just been run, even if the task is not in a runnable state.

@param[out] pExecCount  Returns a number indicating which task execution the results are for (1 for the first execution, 2 for the second, and so on).
@return Returns the state for the currently running task turn or the previously run task turn.

*/
    TaskTurnState GetTurnState(  u32* pExecCount = NULL ) const;


/*!
@brief Clears the task turn state.

Immediately after calling this method, <tt>@ref GetTurnState</tt> returns the state or result of the task turn at that point.
To check for the end of execution of a task turn by polling, call this method followed by the <tt>@ref GetTurnState</tt> method.
*/
    void ClearTurnState( void );

/*!
@brief Gets the number of executions of a task at the time the function is called. This value also gives the number of times a task executed after it has executed for the last time.

@return Returns the number of times the task has executed.

*/
    u32 GetExecCount( void ) const;

/*!
@brief Gets the priority for current task execution.

If the priority has been temporarily set by a policy list to something different from when the task was registered, the temporary priority level is returned.

@return Returns the current task execution priority.
*/
    TaskPriority GetPriority(void) const;



/*!
@brief Gets the size of the task's data.

Until a task enters the <tt>Running</tt> state, it holds the data size for the previous time it ran, and zero if it has not run at all. <br />
In the <tt>Running</tt> state, it is initially reset to zero. When a data size is defined, the value can be obtained.

Note that even if the values obtained by <tt>GetContentLength</tt> and <tt>GetProcessedLength</tt> match, the task processing after the communication completes may not have completed. <br />
Use <tt>Task::GetTurnState</tt> to verify that the task processing has completed.

@param[out] pExecCount  Returns a number indicating which task execution the obtained size is for (1 for the first execution, 2 for the second, and so on).
@return Returns the size of the task's data.
*/
    s64 GetContentLength( u32* pExecCount = NULL ) const;

/*!
@brief Gets the size of data already sent or received by the task.

Until a task enters the <tt>Running</tt> state, this function holds the size of the received data from the previous time it completed the task execution. (If it has not executed the task at all, the function holds a data size of zero.) <br />
When this function runs, the value is first reset to zero, and then it is updated periodically as data is processed.

Note that even if the values obtained by <tt>GetContentLength</tt> and <tt>GetProcessedLength</tt> match, the task processing after the communication completes may not have completed. <br />
Use <tt>Task::GetTurnState</tt> to verify that the task processing has completed.

@param[out] pExecCount  Returns a number indicating which task execution the obtained size is for (1 for the first execution, 2 for the second, and so on).
@return Returns the size of data already processed by the task.
*/
    s64 GetProcessedLength( u32* pExecCount = NULL ) const;

/*!
@brief Gets the task ID.

Returns the task ID set for this instance using the <tt>@ref Initialize</tt> function.

@return Returns the task ID.
*/
    TaskID GetTaskID( void ) const;


/*!
@brief Gets the title ID of the task.

This ID cannot be specified in the <tt>@ref Task</tt> class, so this function always returns the value <tt>TitleID(0)</tt>.

@return Returns the title ID of the task.
*/
    TitleID GetTitleID( void ) const;



/*!
@brief Gets the execution state of the task.

@param[out] pExecCount  Returns a number indicating which task execution the obtained size is for (1 for the first execution, 2 for the second, and so on).
@return Returns the execution state of the task.
*/
    TaskRunningState GetRunningState( u32* pExecCount = NULL ) const;


/*!
@brief Gets the option execution results from the last time a task executed.

Unlike the common task execution results that are retrieved from <tt>@ref GetResult</tt>, the execution results of an option have different meanings depending on the task type. <br />
The availability of option execution results depends on the task type. <br />
For more information about the availability and types of option execution results for each task, see the programming manual.

@param[in] optionKind  Specifies the option type. The type of value that can be set depends on the task type.
@param[out] pExecCount  Returns a number indicating which task execution the detailed results are for (1 for the first execution, 2 for the second, and so on).
@return Returns the option execution results from the last task execution. Returns <tt>0</tt> if the target task has no option execution results for the specified <span class="argument">optionKind</span>. <BR>
*/
    u64 GetOptionResult( u32 optionKind, u32* pExecCount = NULL ) const;


/*!
@deprecated This API function is outdated. Do not use it.
*/
    explicit Task( const char* taskId, AccountID accountId );

/*!
@deprecated This API function is outdated. Do not use it.
*/
    nn::Result Initialize(const char* taskId, AccountID accountId );

/*!
@deprecated This API function is outdated. Do not use it.
*/
    AccountID GetAccountID( void ) const;

protected:
    AccountID m_accountId;
    u8 padding[4];
    TaskID    m_taskId;
    TitleID   m_titleId;
};

//! @}

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

#endif // __cplusplus

#endif /* NN_BOSS_BOSS_TASK_H_ */