nn::boss::Task Class

Syntax

class Task

Description

Class for representing tasks. Use this to do such things as register or unregister a task, or for task operations.

Member Functions

Task Constructor.
V ~Task Destructor.
Initialize Initializes the registered task with the specified task ID. This initialization makes it possible to reuse objects.
UpdateInterval Updates the execution interval for a task after registration. This can be changed even after a task has been instructed to start executing. The valid execution interval ranges from 1 to 3 hours.
UpdateIntervalWithSec Updates the execution interval for a task after registration. The units are seconds. This can be changed even after a task has been instructed to start executing.
UpdateCount Updates the execution count for a task after registration. This can be changed even after a task has been instructed to start executing.
GetInterval Gets the execution interval. The units are hours. This can be changed even after a task has been instructed to start executing.
GetIntervalSec Gets the execution interval. The units are seconds.
GetCount Gets the execution count.
GetServiceStatus Gets the service status of a task. Applications can check a service's status when they detect a notification from the server indicating that the service was discontinued. If the server has not been accessed since the task was registered, the status will be SERVICE_UNKNOWN.
Start Starts a task. The scheduled tasks will automatically run in the background when infrastructure connections are enabled. When a task finishes running, the execution count specified in the task's attributes will be decremented by 1, regardless of whether the execution resulted in an error. As a result, unless the execution count is 0, the task will be run again after the execution interval specified in the task's attributes. Note that tasks whose execution counts reach zero may be deleted automatically if the internal database is filled to capacity. In the following circumstances, tasks won't be scheduled for execution even if a command is issued to start a task.
• The task's execution count is 0.
• The task's execution priority is PRIORITY_STOPPED.
• Parental Controls are in force on the task and are not disabled in the task attributes.
• The user has not yet agreed to the EULA, and the EULA agreement requirement is not disabled in the task attributes.
• Task execution was stopped in the policy list that was downloaded from a Nintendo Zone access point.
• The server hosting the download service issued a "service suspended" notice.
• The administrator has temporarily suspended all tasks.

One way to check for these common cases is to use the GetCount function to confirm the execution count. Parental Controls and the EULA agreement can be configured with the Config tool and other utilities. It is possible to tell when the administrator has temporarily paused all tasks because TASK_PAUSED is returned by the GetState function.

The following methods can be used to wait for task completion.

·Wait for execution to complete with the WaitFinish function.
·Specify a maximum waiting time and wait for execution to complete with the WaitFinish function.
·Use the GetState function to poll for completed tasks.
·Wait for a new arrival event using an Event registered by the RegisterNewArrivalEvent function.

Once you detect that a task is completed, you can confirm the task state with the GetState function, the task execution results code with the GetResult function, and the HTTP communication results code with the GetHttpStatusCode function. You can also get other details with the GetStateDetail function.
StartImmediate Starts a task immediately. This can only be called after infrastructure connections are enabled. Because this allows a task to be executed before its scheduled time, it is suitable for as-needed immediate execution of tasks that would normally run in the background. When you specify immediate execution, you can run a task at the highest priority even if it means interrupting other running tasks. The Start function differs from this one in that its execution time has already arrived and, if communications are interrupted, it does not enter the "resume" state but instead gives an error for the task execution result. Another point to note is that when you want to execute only the target task and only once, you must set its execution count to 1. Setting it to a value more than 1 will cause it to auto-run in the background like a normal task until its execution count reaches zero. See ac::Connect for information about how to enable infrastructure connections.
Cancel Cancels a running task. You can use the Start function to restart a task that has been canceled. If a task has been canceled, calling the GetState function will return TASK_STOPPED as the task's state. If the task in question was running when it was canceled, task execution is canceled and TASK_CANCELED is returned as the task's execution result.
WaitFinish Waits for a task to finish within the specified time. This is the same as WaitFinish except that it also has a timeout feature. If the timestamp indicating when the URL was modified is the same as the previous timestamp, the task downloads nothing and fails to complete.
GetState Gets the task state. In most cases, tasks transition from step 1 through 5 below.
(1) TASK_REGISTERED (task registered)
(2) TASK_WAITING_TIMER (waiting for time after Start function is called)
(3) TASK_WAITING (waiting for execution)
(4) TASK_RUNNING or TASK_RETRY (task is running)
(5) TASK_DONE or TASK_ERROR (task is complete)

There are also two special states, TASK_PAUSED (paused) and TASK_STOPPED (stopped due to a call to Cancel). State transitions may occur in a short period of time. Accordingly, the function may not always return all states.
GetHttpStatusCode Gets the communication error code. The following examples show common HTTP response codes.
200 OK: HTTP request successful.
206 Partial Content: HTTP GET request partially fulfilled, with more data still to come.
401 Unauthorized: Basic authentication required, or authorization credentials refused by server. Basic authentication is not supported, so do not use this.
404 Not Found: Specified URL not found. Check whether the URL is correct or whether the content has been deleted.
403 Forbidden: User does not have access to the specified URL. Check that the URL is correct.
500 Internal Server Error: An error on the server has prevented it from fulfilling the request. Contact the server administrator.
GetCommErrorCode This is the old (deprecated) name for nn::boss::GetHttpStatusCode. Avoid using this: it only exists for compatibility.
GetResult Gets the task result code. For more information on task result codes, see TaskResultCode.
Notes about common errors that occur during task execution:

(1) When infrastructure communication was interrupted:
HTTP_ERROR_RECV
HTTP_ERROR_CONNECT

(2) When the connection to the server failed because the server indicated by the URL could not be found:
HTTP_ERROR_DNS
HTTP_ERROR_CONNECT

(3) When the connection to the server failed because HTTPS negotiation failed:
SSL_ERROR_FAILED
SSL_ERROR_VERIFY_COMMON_NAME
SSL_ERROR_VERIFY_ROOT_CA
SSL_ERROR_VERIFY_CHAIN
SSL_ERROR_VERIFY_DATE

(4) When an NSA download failed because there is insufficient space in NSA storage:
NSA_ERROR_STORAGE_INSUFFICIENCY

(5) When an NSA download failed because the file was either not in NSA format or was corrupted due to a communication error:
NSA_ERROR_INVALID_FORMAT
NSA_ERROR_VERIFY_HASH
NSA_ERROR_VERIFY_SIGNATURE
NSA_NSD_ERROR_VERIFY_HASH
NSA_NSD_ERROR_VERIFY_SIGNATURE
NSA_NSD_ERROR_INVALID_FORMAT
GetStateDetail Gets the task status. You must prepare a TaskStatus instance beforehand. Note that this instance requires approximately 128 bytes of memory. See the GetProperty member function of the TaskStatus class for more information about obtaining the values of the attributes.
GetStatus This is the old (deprecated) name for nn::boss::GetStateDetail. Avoid using this: it only exists for compatibility.
GetError Gets the task error state. You must prepare a TaskError instance beforehand. Note that this instance requires approximately 136 bytes of memory.
GetInfo Gets information about a registered task. You must prepare instances of the TaskPolicy, TaskAction, and TaskOption classes beforehand. See the GetProperty member function of each class for more information about obtaining the values of the attributes.
GetTaskId Gets the task ID.

Revision History

2010/09/16
Initial version.

CONFIDENTIAL