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. Specify UNLIMITED_COUNT for an unlimited execution count.
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. Checks the execution count. This function can be used to check whether the count has decreased, so it can be changed.
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. 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 enabled and not deactivated through the task attributes.
• The user has not yet agreed to the EULA, and agreement to the EULA hasn't been disabled through 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.
As a confirmation method for common cases, it is possible to use the GetCount function to confirm the execution count. Parental controls and the EULA consent can be configured with the Config tool. When the administrator has temporarily paused all tasks, TASK_PAUSED will be returned by the GetState function, so identification is possible.
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. ・The use of polling of the execution completion task is possible by using the GetState function. ・Wait for a new arrival event with a registered Event using the RegisterNewArrivalEvent function, and then when completion is detected, you can confirm task status with the GetState function, task execution results code with the GetResult function amd HTTP communication results code with the GetHttpStatusCode function. More detailed information is available at GetStateDetail.
StartImmediate Starts a task immediately. This can only be called after infrastructure connections are enabled. Advance task execution is possible at scheduled times, so this is applicable for immediate execution of tasks that would have normally run in the background. However, execution priority is inherited as an attribute value when a task is registered, so if there if a task arrives with higher priority, note that it will take precedence. The difference with Start is that if the execution time has already come and communication has been disconnected, the task execution result will be an error without waiting for a resume state. Another point to note is that when you want to execute the target task only once, you should set the execution count to 1. Setting it to a higher value will mean it will 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. For the cancel state task, calling the GetState function will return TASK_STOPPED as the task state.
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 (wait for time after calling Start)
(3) TASK_WAITING (waiting for execution)
(4) TASK_RUNNING or TASK_RETRY (task running)
(5) TASK_DONE or TASK_ERROR (task 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 is an example of common response codes in HTTP communication.
200: A normal HTTP communication result.
206: A normal HTTP communication result, but still continuing to receive data.
401: The basic authentication result was not correct. Do not use because basic authentication is not supported.
404: The URL content could not be found. Check whether the URL was correct, or whether the content has been deleted.
403: A URL has been specified for which access is not granted. Check that the URL is correct.
500: An error occurred as a result of a server problem. 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