1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) 2012 Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 #ifndef NN_BOSS_BOSS_TASK_H_ 14 #define NN_BOSS_BOSS_TASK_H_ 15 16 #include <nn/boss/boss_Const.h> 17 #include <nn/boss/boss_Result.h> 18 #include <nn/boss/boss_Types.h> 19 #include <nn/boss/boss_TaskSetting.h> 20 21 22 #ifdef __cplusplus 23 24 namespace nn { 25 namespace boss { 26 27 /*! 28 @addtogroup nn_boss_api 29 @{ 30 */ 31 32 /*! 33 @brief Represents a task. Used to register and start tasks and to manipulate them or access their attributes. 34 */ 35 class Task 36 { 37 friend class NbdlDataList; 38 39 public: 40 /*! 41 @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. 42 */ 43 explicit Task(void); 44 45 /*! 46 @brief Instantiates the object and calls <tt>@ref Initialize</tt>. This function targets the account that is logged in when the function is called. 47 48 @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>. 49 */ 50 explicit Task( const char* taskId ); 51 52 /*! 53 @brief Instantiates the object and calls <tt>@ref Initialize</tt>. Specifies a slot in the target account. 54 55 @param[in] slotNo Specifies a slot in the target account. 56 @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>. 57 */ 58 explicit Task( u8 slotNo, const char* taskId ); 59 60 /*! 61 @brief Destroys the object. 62 */ 63 virtual ~Task(void); 64 65 /*! 66 @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. 67 68 @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>. 69 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 70 @retval Result::IsSuccess Indicates that initialization succeeded. 71 @retval ResultInvalidParameter Indicates that the task ID is invalid. 72 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 73 */ 74 nn::Result Initialize(const char* taskId ); 75 76 /*! 77 @brief Initializes the registered task with the specified task ID. This initialization enables the reuse of objects. Specifies a slot in the target account. 78 79 @param[in] slotNo Specifies a slot in the target account. 80 @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>. 81 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 82 @retval Result::IsSuccess Indicates that initialization succeeded. 83 @retval ResultInvalidParameter Indicates that the task ID is invalid. 84 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 85 */ 86 nn::Result Initialize( u8 slotNo, const char* taskId ); 87 88 /*! 89 @brief Finalizes the class instance. 90 91 Also called from the destructor. 92 */ 93 void Finalize( void ); 94 95 /*! 96 @brief Checks whether a task is registered. 97 98 @return Returns whether the task is registered. <tt>true</tt> if the task is registered. 99 */ 100 bool IsRegistered( void ) const; 101 102 103 /*! 104 @brief Registers a task. 105 106 Use <tt>@ref Initialize</tt> to set the IDs (the task ID and persistent ID) of the task to register. 107 Set the attributes for the task to register in an instance of the <tt>@ref TaskSetting</tt> subclass specified in the parameters. 108 109 The information for tasks registered with this function is held in the system and made persistent. <br /> 110 This enables the task to run in the background even across being powered down, or while a menu or other application is running. <br /> 111 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 /> 112 113 Tasks do not operate just by being registered. <br /> 114 Depending on the desired operations, start by using either the <tt>@ref Task::StartScheduling</tt> or <tt>@ref Task::Run</tt> function. <br /> 115 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 /> 116 117 The success conditions for registering tasks are as follows. <br /> 118 - Invalid values are not set in the <tt>TaskSetting</tt> specified in the parameters. <br /> 119 - 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 /> 120 - 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 /> 121 122 The first condition is met as long as the <tt>TaskSetting</tt> member functions are being used correctly. <br /> 123 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 /> 124 125 126 @param[in] taskSetting Specifies the task settings. 127 128 @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. 129 @retval Result::IsSuccess Indicates that registration succeeded. <br /> 130 @retval ResultInvalidParameter Indicates that the task settings contain an invalid value. 131 @retval ResultInvalidFormat Indicates that the format of the task settings is invalid. 132 @retval ResultFull Indicates that the maximum number of tasks are already registered. 133 @retval ResultAlreadyExist Indicates that the same task (a task with the same task ID and the same persistent ID) has already been registered. 134 @retval ResultNotExist Indicates that there is no account with the specified persistent ID. 135 @retval ResultNotNetworkAccount Indicates that the account with the specified persistent ID is not associated with a network account. 136 @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. 137 @retval ResultLibraryNotInitialized Indicates that the session is not initialized. <br /> 138 If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br /> 139 Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library. 140 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 141 142 143 144 145 */ 146 nn::Result Register(TaskSetting& taskSetting ); 147 148 149 /*! 150 @brief Registers a dedicated immediate-execution task. 151 152 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. 153 For more information, see <tt>@ref Register</tt>. 154 155 @param[in] taskSetting Specifies the task settings. 156 157 @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. 158 @retval Result::IsSuccess Indicates that registration succeeded. <br /> 159 @retval ResultInvalidParameter Indicates that the task settings contain an invalid value. 160 @retval ResultInvalidFormat Indicates that the format of the task settings is invalid. 161 @retval ResultFull Indicates that the maximum number of tasks are already registered. 162 @retval ResultAlreadyExist Indicates that the same task (a task with the same task ID and the same persistent ID) has already been registered. <br /> 163 Alternately, indicates that a dedicated immediate-execution task with the same persistent ID has already been registered. 164 @retval ResultNotExist Indicates that there is no account with the specified persistent ID. 165 @retval ResultNotNetworkAccount Indicates that the account with the specified persistent ID is not associated with a network account. 166 @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. 167 @retval ResultLibraryNotInitialized Indicates that the session is not initialized. <br /> 168 If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br /> 169 Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library. 170 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 171 */ 172 nn::Result RegisterForImmediateRun(const TaskSetting& taskSetting ); 173 174 175 /*! 176 @brief Allows the settings information for a registered task to be changed. 177 178 @param[in] taskSetting Specifies the task settings. 179 180 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 181 @retval Result::IsSuccess Indicates that registration succeeded. <br /> 182 @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>. 183 @retval ResultNotExist Indicates that the specified task has not been registered. 184 @retval ResultLibraryNotInitialized Indicates that the session is not initialized. <br /> 185 If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br /> 186 Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library. 187 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 188 */ 189 nn::Result Reconfigure(const TaskSetting& taskSetting ); 190 191 192 193 /*! 194 @brief Deletes a registered task. 195 196 If the task is running, it is first canceled, and then deleted. <br /> 197 198 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 199 @retval Result::IsSuccess Indicates that deletion succeeded. 200 @retval ResultNotExist Indicates that the specified task has not been registered. 201 @retval ResultLibraryNotInitialized Indicates that the session is not initialized. <br /> 202 If this function is called before <tt>@ref boss::Initialize</tt> is called, this <tt>Result</tt> is returned. <br /> 203 Always call the <tt>@ref boss::Initialize</tt> function before you use the BOSS library. 204 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 205 */ 206 nn::Result Unregister(void); 207 208 209 /*! 210 @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. 211 212 @param[in] intervalHour Specifies the interval at which to execute the task. The unit is hours. 213 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 214 @retval Result::IsSuccess Indicates that the execution interval was updated successfully. 215 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 216 @retval ResultNotExist Indicates that the specified task has not been registered. 217 @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. 218 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 219 */ UpdateInterval(u32 intervalHour)220 inline nn::Result UpdateInterval(u32 intervalHour){return UpdateIntervalSec(intervalHour*60*60);} 221 222 /*! 223 @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. 224 225 @param[in] intervalSec Specifies the execution interval. The unit is seconds. 226 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 227 @retval Result::IsSuccess Indicates that the execution interval was updated successfully. 228 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 229 @retval ResultNotExist Indicates that the specified task has not been registered. 230 @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. 231 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 232 */ 233 nn::Result UpdateIntervalSec(u32 intervalSec); 234 235 /*! 236 @brief Updates the lifetime of a registered task. You can change this interval even after a task has been instructed to start executing. 237 238 @param[in] lifeTimeHourFromNow The time (in hours) from now at which to execute the task. 239 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 240 @retval Result::IsSuccess Indicates that the lifetime was updated successfully. 241 @retval ResultServiceFinished Indicates that the service related to the task has already terminated. 242 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 243 @retval ResultNotExist Indicates that the specified task has not been registered. 244 @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. 245 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 246 */ UpdateLifeTime(u32 lifeTimeHourFromNow)247 inline nn::Result UpdateLifeTime(u32 lifeTimeHourFromNow){return UpdateLifeTimeSec(lifeTimeHourFromNow*60*60);} 248 249 /*! 250 @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. 251 252 @param[in] lifeTimeSecFromNow The time (in seconds) from now at which to execute the task. 253 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 254 @retval Result::IsSuccess Indicates that the lifetime was updated successfully. 255 @retval ResultServiceFinished Indicates that the service related to the task has already terminated. 256 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 257 @retval ResultNotExist Indicates that the specified task has not been registered. 258 @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. 259 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 260 */ 261 nn::Result UpdateLifeTimeSec(s64 lifeTimeSecFromNow); 262 263 264 /*! 265 @brief Gets the execution interval. The unit is hours. 266 267 @return Returns the execution interval. <BR> 268 */ GetInterval(void)269 inline u32 GetInterval(void) const 270 { 271 const u32 intervalSec = GetIntervalSec(); 272 return (intervalSec / (60*60)); 273 } 274 275 /*! 276 @brief Gets the execution interval. The unit is seconds. 277 278 @return Returns the execution interval. <BR> 279 */ 280 u32 GetIntervalSec(void) const; 281 282 /*! 283 @brief Gets the lifetime of the task. The unit is hours. 284 285 @return Returns the lifetime. The unit is hours. <br /> 286 */ GetLifeTime(void)287 inline u32 GetLifeTime(void) const 288 { 289 const s64 secLifeTime = GetLifeTimeSec(); 290 return (secLifeTime / (60*60)); 291 } 292 293 /*! 294 @brief Gets the lifetime of the task. The unit is seconds. 295 296 @return Returns the lifetime. The unit is seconds. <br /> 297 */ 298 s64 GetLifeTimeSec(void) const; 299 300 301 /*! 302 @brief Gets the remaining lifetime of the task. The unit is seconds. 303 304 @return Returns the remaining lifetime of the task. The unit is seconds. <br /> 305 */ 306 s64 GetRemainingLifeTimeSec(void) const; 307 308 /*! 309 @brief Gets the target URL for task execution. 310 Returns an empty string for NBDL tasks. 311 312 @param[out] url Specifies the URL for which the task is executed. 313 @param[in] urlLength Specifies the length of <span class="argument">url</span>. 314 315 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 316 @retval Result::IsSuccess Indicates success. 317 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 318 @retval ResultNotExist Indicates that the specified task has not been registered. 319 @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. 320 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 321 */ 322 nn::Result GetUrl(char url[], u32 urlLength) const; 323 324 /*! 325 @brief Checks whether a task has finished executing. 326 327 For a task with a specified lifetime, returns <tt>true</tt> if the lifetime has completed. 328 <br /> 329 For a one-time execution task, only returns <tt>true</tt> after it has completed execution. <br /> 330 (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 /> 331 This method returns <tt>false</tt> when it is called while the task is running. <br /> 332 333 @return Returns whether task execution has completed. Returns <tt>true</tt> if it has completed. 334 */ 335 bool IsFinished(void) const; 336 337 /*! 338 @brief Renews the task lifetime. 339 340 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. 341 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 /> 342 343 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 344 @retval Result::IsSuccess Indicates success. 345 @retval ResultServiceFinished Indicates that the service related to the task has already terminated. 346 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 347 @retval ResultNotExist Indicates that the specified task has not been registered. 348 @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. 349 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 350 */ 351 nn::Result RestoreLifeTime(void); 352 353 354 /*! 355 @brief Gets the service status of a task. 356 357 Applications can check the status of a service when they detect a notification from the server that indicates that the service was discontinued. 358 <b>Note:</b> If the server has not been accessed since the task was registered, the status is <tt>@ref SERVICE_UNKNOWN</tt>. 359 360 @return Returns the service status of a task. <br /> 361 */ 362 TaskServiceStatus GetServiceStatus(void) const; 363 364 /*! 365 @brief Gives an instruction to start scheduled execution of the task. 366 367 The scheduled tasks automatically run in the background when infrastructure connections are enabled. <br /> 368 <br /> 369 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 /> 370 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> 371 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> 372 <BR> 373 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 /> 374 <br /> 375 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 /> 376 (A one-time execution task is not executed subsequently.)) 377 In the following circumstances, tasks are not executed even if a command is issued to start a task. <br /> 378 - The execution priority of the task is <tt>@ref PRIORITY_STOPPED</tt>. 379 - Parental Controls are enabled, and the attributes of the task do not override Parental Controls. 380 - The user has not accepted the EULA, and the attributes of the task do not override EULA acceptance. 381 - A policy list blocks task execution. 382 - The application has paused all tasks. 383 <br /> 384 The following methods can be used to wait for task completion. <br /> 385 - Use the <tt>@ref Wait</tt> function to wait until execution completes. 386 - Use the <tt>@ref Wait</tt> function to wait until execution completes, specifying a maximum wait time. 387 - Use the <tt>@ref GetTurnState</tt> function to poll for task completion. 388 <br /> 389 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 /> 390 <br /> 391 392 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 393 @retval Result::IsSuccess Indicates success. 394 @retval ResultNotInitialized Indicates that the instance has not been initialized. Call this method after calling <tt>@ref Initialize</tt>. 395 @retval ResultNotExist Indicates that the specified task has not been registered. 396 @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. 397 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 398 399 400 401 */ 402 nn::Result StartScheduling(bool isFirstRunImmediate = true); 403 404 /*! 405 @brief Immediately executes a task. 406 407 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. 408 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 /> 409 Use this method to run a task using the high-priority communication provided in the foreground. <br /> 410 <br /> 411 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 /> 412 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 /> 413 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 /> 414 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 /> 415 <br /> 416 When this method is used, if there is a task currently running, that task is suspended and the applicable task runs immediately. <br /> 417 <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. 418 419 420 @param[in] isForegroundRun Specify whether to run in the foreground. If omitted, the task is run in the background. 421 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 422 @retval Result::IsSuccess The instruction to start the task immediately succeeded. 423 @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. 424 @retval ResultInvalidTaskId Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string. 425 @retval ResultNotExist Indicates that the specified task ID was not found. Confirm whether it is registered yet. 426 @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. 427 @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. 428 @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. 429 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 430 */ 431 nn::Result Run(bool isForegroundRun = false); 432 433 434 /*! 435 @brief Stops scheduled execution of a task. 436 437 You can use the <tt>@ref StartScheduling</tt> function to restart a task that has been suspended. 438 If a task has been suspended, calling the <tt>@ref GetState</tt> function returns <tt>@ref STOP</tt> as the state of the task. 439 If the applicable task is currently running, the task is canceled. 440 441 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 442 @retval Result::IsSuccess Indicates success. 443 @retval ResultInvalidTaskId Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string. 444 @retval ResultNotExist Indicates that the specified task ID was not found. Confirm whether it is registered yet. 445 @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. 446 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 447 */ 448 nn::Result StopScheduling(void); 449 450 /*! 451 @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. 452 453 This function is provided to stop immediate execution tasks. 454 It does nothing for tasks in a state other than <tt>RUNNING</tt>, <tt>WAITING_RUN</tt>, and <tt>WAITING_RESUME</tt>. 455 456 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 457 @retval Result::IsSuccess Indicates success. 458 @retval ResultInvalidTaskId Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string. 459 @retval ResultNotExist Indicates that the specified task ID was not found. Confirm whether it is registered yet. 460 @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. 461 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 462 */ 463 void Cancel(CancelMode cancelModel = CANCEL_TO_STOP); 464 465 /*! 466 @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. 467 468 This function is provided to stop immediate execution tasks. 469 It does nothing for tasks in a state other than <tt>RUNNING</tt>, <tt>WAITING_RUN</tt>, and <tt>WAITING_RESUME</tt>. 470 471 @return Returns the result of the function. Returns one of the following <tt>Result</tt> values. 472 @retval Result::IsSuccess Indicates success. 473 @retval ResultInvalidTaskId Indicates that the task ID pointer is <tt>NULL</tt> or a zero-length string. 474 @retval ResultNotExist Indicates that the specified task ID was not found. Confirm whether it is registered yet. 475 @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. 476 @retval Other Indicates an unexpected error. (For more information, see <tt>@ref nn_boss_result</tt>.) 477 */ 478 void CancelSync(CancelMode cancelModel = CANCEL_TO_STOP); 479 480 /*! 481 @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. 482 483 For more information, see the <tt>@ref CancelSync</tt> function, which is the same, but without a timeout feature. 484 485 It does nothing for tasks in a state other than <tt>RUNNING</tt>, <tt>WAITING_RUN</tt>, and <tt>WAITING_RESUME</tt>. 486 This function is provided to stop immediate execution tasks. 487 488 */ 489 bool CancelSync(u32 timeoutMsec, CancelMode cancelModel = CANCEL_TO_STOP); 490 491 492 493 /*! 494 @brief Waits until a task assumes a certain state. 495 496 This method blocks until the applicable task enters the specified state. 497 @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. 498 */ 499 void Wait(TaskWaitState waitState = TWS_DONE); 500 501 /*! 502 @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. 503 504 For more information, see the version of the <tt>@ref Wait</tt> function that does not take a timeout value. 505 506 @param[in] timeoutSec Specifies the timeout. The unit is seconds. 507 @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. 508 @return Returns the reason for returning from the method. Either the task entered the specified state, or the timeout occurred. 509 @retval true Indicates the task reached the specified state. 510 @retval false Indicates that the task timed out. 511 512 */ 513 bool Wait(u32 timeoutSec, TaskWaitState waitState = TWS_DONE); 514 515 516 /*! 517 @brief Gets the state of a task. 518 519 @param[out] pExecCount Returns the task execution count for the status code being obtained. 520 @return Returns the task state. <br /> 521 */ 522 TaskState GetState( u32* pExecCount = NULL ) const; 523 524 /*! 525 @brief Gets the HTTP status code from the last time a task executed. 526 527 @param[out] pExecCount Returns the task execution count for the status code being obtained. 528 @return Returns the HTTP status code from the last time a task executed. <br /> 529 @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.) 530 */ 531 s32 GetHttpStatusCode( u32* pExecCount = NULL ) const; 532 533 /*! 534 @brief Gets the detailed result for the last time a task executed. 535 536 For more information about task results, see <tt>@ref TaskResult</tt>. <br /> 537 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 /> 538 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 /> 539 540 @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). 541 @return Returns the result from the last task execution. <br /> 542 */ 543 TaskResult GetResult( u32* pExecCount = NULL ) const; 544 545 /*! 546 @brief Gets the state of the currently executing task turn. 547 548 If the task cannot yet be run (<tt>@ref TTS_WAITING_RUN</tt>), returns the result from the previous task turn. 549 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. 550 551 @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). 552 @return Returns the state for the currently running task turn or the previously run task turn. 553 554 */ 555 TaskTurnState GetTurnState( u32* pExecCount = NULL ) const; 556 557 558 /*! 559 @brief Clears the task turn state. 560 561 Immediately after calling this method, <tt>@ref GetTurnState</tt> returns the state or result of the task turn at that point. 562 To check for the end of execution of a task turn by polling, call this method followed by the <tt>@ref GetTurnState</tt> method. 563 */ 564 void ClearTurnState( void ); 565 566 /*! 567 @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. 568 569 @return Returns the number of times the task has executed. 570 571 */ 572 u32 GetExecCount( void ) const; 573 574 /*! 575 @brief Gets the priority for current task execution. 576 577 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. 578 579 @return Returns the current task execution priority. 580 */ 581 TaskPriority GetPriority(void) const; 582 583 584 585 /*! 586 @brief Gets the size of the task's data. 587 588 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 /> 589 In the <tt>Running</tt> state, it is initially reset to zero. When a data size is defined, the value can be obtained. 590 591 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 /> 592 Use <tt>Task::GetTurnState</tt> to verify that the task processing has completed. 593 594 @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). 595 @return Returns the size of the task's data. 596 */ 597 s64 GetContentLength( u32* pExecCount = NULL ) const; 598 599 /*! 600 @brief Gets the size of data already sent or received by the task. 601 602 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 /> 603 When this function runs, the value is first reset to zero, and then it is updated periodically as data is processed. 604 605 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 /> 606 Use <tt>Task::GetTurnState</tt> to verify that the task processing has completed. 607 608 @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). 609 @return Returns the size of data already processed by the task. 610 */ 611 s64 GetProcessedLength( u32* pExecCount = NULL ) const; 612 613 /*! 614 @brief Gets the task ID. 615 616 Returns the task ID set for this instance using the <tt>@ref Initialize</tt> function. 617 618 @return Returns the task ID. 619 */ 620 TaskID GetTaskID( void ) const; 621 622 623 /*! 624 @brief Gets the title ID of the task. 625 626 This ID cannot be specified in the <tt>@ref Task</tt> class, so this function always returns the value <tt>TitleID(0)</tt>. 627 628 @return Returns the title ID of the task. 629 */ 630 TitleID GetTitleID( void ) const; 631 632 633 634 /*! 635 @brief Gets the execution state of the task. 636 637 @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). 638 @return Returns the execution state of the task. 639 */ 640 TaskRunningState GetRunningState( u32* pExecCount = NULL ) const; 641 642 643 /*! 644 @brief Gets the option execution results from the last time a task executed. 645 646 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 /> 647 The availability of option execution results depends on the task type. <br /> 648 For more information about the availability and types of option execution results for each task, see the programming manual. 649 650 @param[in] optionKind Specifies the option type. The type of value that can be set depends on the task type. 651 @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). 652 @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> 653 */ 654 u64 GetOptionResult( u32 optionKind, u32* pExecCount = NULL ) const; 655 656 657 /*! 658 @deprecated This API function is outdated. Do not use it. 659 */ 660 explicit Task( const char* taskId, AccountID accountId ); 661 662 /*! 663 @deprecated This API function is outdated. Do not use it. 664 */ 665 nn::Result Initialize(const char* taskId, AccountID accountId ); 666 667 /*! 668 @deprecated This API function is outdated. Do not use it. 669 */ 670 AccountID GetAccountID( void ) const; 671 672 protected: 673 AccountID m_accountId; 674 u8 padding[4]; 675 TaskID m_taskId; 676 TitleID m_titleId; 677 }; 678 679 //! @} 680 681 } // end of namespace boss 682 } // end of namespace nn 683 684 #endif // __cplusplus 685 686 #endif /* NN_BOSS_BOSS_TASK_H_ */ 687 688