Wii has a feature for synchronizing the automatic downloading of content from the server and saving to NAND memory while an application is running or while the console is in standby mode.
With this function, applications can receive additional data without making the user wait.
The download task refers to the collection of settings necessary for download reservation, such as the URL and check intervals for content updates.
The download task list is a list of enabled download tasks.
A download task is enabled through registration to the download task list. The download task list is a file in NAND memory controlled through NWC24 functions.
Download tasks can be deleted from the task list automatically. (Details are described below.))
The download box is the storage location of the downloaded data. There is one download box for each application.
An application must create a download box at initial startup and keep it in a usable state so that it is available for task registration. Create the download box in the application save area.
WiiConnect24 automatically verifies the signature to ensure that the downloaded contents have not been falsified.
To ensure security, contents acquired through HTTP must always have the correct signature.
See also: NWC24 Download Signatures
The WiiConnect24 download feature is designed to avoid interference with the server, network, and applications running in the foreground. Therefore, users typically need to keep only certain parameters in mind, although detailed parameters settings are also possible.
Specifies the content acquisition source. Although the HTTP and HTTPS protocols are supported, the following restrictions are set to ensure security.
The signature verification functionality in WiiConnect24 must always be enabled.
This restriction may be disabled through NWC24EnableDlLaxParameterChecking() only for debugging.
The target server must have a server certificate that was issued by the Nintendo CA.
WiiConnect24 queries the HTTP servers for content updates, using functions preset by HTTP. If the contents have been updated, they are downloaded. The interval for this update query is set in the update check interval.
Determining this value is extremely important. Setting a shorter update check interval allows users to acquire the updated contents sooner, but this also increases the server and network load. This value must therefore be determined with the scale of operation and the frequency of content update in mind. Since there is no way to change the update check interval later, the servers and network must be upgraded if they are inadequate. Therefore, be careful when choosing this value.
Keep in mind that the update check is not always performed as set by this value. Various factors may cause a delay in the operation.
When the update check timing overlaps with another, the task with the highest priority goes through. The update check for the remaining tasks is carried over to the next time (approximately two minutes later). (For more information on launch timing, see the NWC24 Scheduler Operation Functions.
For this reason, if the update check interval is short, set the priority low so other tasks are given priority.
There are restrictions that depend on the number of registered tasks and the update check interval. For details, see the WiiConnect24 Programming Guidelines.
Smaller values indicate higher priority.
The download count is decremented each time a content update check is performed, and the task disappears once the count reaches zero. When a task disappears, the update check is no longer performed until the task is reregistered by the application.
The download count decrements by 1 when the update check is successful. In other words,
Specifies the file name used to save to the download box. This item is effective when you want to keep past files. Directories other than the root directory may be specified as long as they are created first.
Normally there is no need to specify this.
Specifies the update interval of the specified URL.
This setting will be used in a future upgrade. Currently, this value is not used, even if it is configured.
If the Wii is turned off or a game application with WiiConnect24 operation prohibited is running, contents update check set by tasks is not performed. This may result in a substantial delay in the update check. The allowed margin of delay is set in the retry margin.
When a delay beyond the allowed margin is detected, the next update check is performed at update check interval counting from the time of delay detection.
If WiiConnect24 cannot operate for a long period of time, multiple update checks are more likely to overlap once WiiConnect24 is operational again. This may also cause continuous download operations for an extended period of time, which may adversely affect other network operations.
In the following situations, set a smaller retry margin, as needed, so that other tasks have higher priority:
Since an appropriate value is automatically set by the library, this value typically does not need to be set. When changing the value, be sure you understand operations well enough to do so.
Various additional functions becomes usable through flags.
This is the ID of the application that registered the task. It is automatically set when a new task is created and cannot be changed. This is mainly used to restrict task access.
When ID of the application that registered the task does not match ID of the application that read the task, the reading application cannot alter the task's contents.
This does not apply if the task has group-writable settings on. Also, this limit is not imposed on the same application in different regions.
These are items that are set for each application that handles download tasks. Each task stores information for the application that registered it; this information is used for accessing the task.
The application must provide a VF archive that can store the contents retrieved by tasks that it registered.
Public keys are used to verify content signatures. Shared keys are used to decrypt encrypted content.
Although WiiConnect24 has public and shared keys in internal system regions that cannot be accessed, during normal use each application should separately provide a key. The key for the application can be set using NWC24SetDlKeys() and are stored in the Home directory.
At each application startup, the following registration sequence is performed:
Attempt to acquire tasks to check whether previously registered download tasks remain. If successful, go to 4. ((Re-)register tasks to the list.)
NWC24DlTask Structure, NWC24GetDlTask(), NWC24GetDlTaskMine(), NWC24GetDlTaskByAppId()
Create and configure new download task(s). (See Download Task Configuration Items for the configuration items.) Usually, setting only the URL and the update check interval is sufficient.
There is no download box when the application starts up for the first time, so it must be created at that time. The size of downloadable files is limited by the available space in the download box. The application needs to determine the download box size, based on the size of the data it needs to handle. (Size restrictions follow the Wii Programming Guidelines.))
The download box is, in fact, an archive file handled by the VF library. The VF archive files for the download box have file permissions that allows view/update from other applications.
NWC24InitDlTask(), NWC24CreateDlVf(), NWC24SetDlUrl(), NWC24SetDlInterval(), NWC24SetDlPriority(), ...
Reset the remaining download count.
The remaining download count is decremented each time a content update check is performed until the task disappears. Applications must reset the remaining download count to the original value at each startup. This is not the case for download tasks that need to be performed only once.
Register/re-register created or acquired tasks to the task list.
Use NWC24AddDlTask() if the task was created in step 2, and NWC24UpdateDlTask() if the task was successfully acquired in step 1. See the function reference for the differences between the two.
The download box is a VF library archive file. Use the VF API to extract data.
Get the archive file path name using NWC24GetDlVfPath(). To get or delete downloaded files, the NWC24 library must be set in advance to a usable state by calling NWC24OpenLib(). There is no guarantee of operations if you manipulate VF archive files when the library is not open and in a usable state.
To avoid duplicate retrieval of the same content, WiiConnect24 uses the prescribed HTTP 1.1 method (If-Modified-Since header) for checking for updates on the server. The time of the most recent update to previously received content is stored in the task list. As a result, even if files in the download box are deleted, these update checks will work correctly.
However, depending on the proxy server settings and other aspects of the user environment, there will be rare occasions when HTTP update checks will not work properly and duplicate content will be downloaded. Consequently, do not design a program such that it fails to operate if the same content is received. Consider this synchronizing feature using the update checks as a feature for limiting the server's transfer volume.
We recommend that you embed sequence numbers in the content, and implement some process that ignores times, when the sequence number of received content is not larger than the number of the previously downloaded content.
Example of use where embedded sequence numbers is recommended:
Example of use where embedded sequence numbers is not necessary:
Various factors may cause a delay in the operation of downloading contents. Consequently, it is safest not to expect that new content will be downloaded at a specific time or to allow the user to see a date or time included in downloaded content.
To halt the delivery of content, you can delete files from the server or prohibit access. However, this will also cause update inquiries to fail. Internally you will no longer be able to differentiate in error processing between scheduling that uses the final update time and positive errors.
Therefore, we recommend that you define empty content that can be ignored by the application, containing only the control header used by the application, to halt delivery by delivering the empty content instead.
The settings and data of the download task are stored in the following locations:
The NWC24 API maintains consistency, but certain operations performed during development can cause inconsistencies and result in states not anticipated by the developer. Be very careful when conducting operations like those described below.
Apart from the ID of the application that registered it, a download task internally stores the home directory path; these values are decided when the task is newly created. These values limit access and are used when accessing the download box.
The download API assumes that each application has a different ID and home directory, so if the ID or home directory is changed during the development of an application, it may result in operations unintended by the developer.
Specifically, cases such as the following require caution:
ddf fileIn situations like these, we recommend deleting all download tasks once.
In the DEVKIT menu and the Wii Menu 2 and earlier versions, when the Save Data was deleted the download tasks remained behind but were referencing keys and Download Boxes that no longer existed.
In Wii Menu 3 and later versions, the result and behavior of deleting is different from that of the DEVKIT menu. The specification has been changed so that when the Save Data is deleted, the registered download tasks are searched out and deleted at the same time.
2007/11/12 Added text specific to the use of empty content.
2007/09/26 Added information on deleting saved data.
2007/07/24 Added notes on changing the development environment, etc.
2007/06/06 Added notes on designing receivable content.
2006/11/17 Initial version.fc
CONFIDENTIAL