nwc24/Download/intro.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<META http-equiv="Content-Style-Type" content="text/css">
<TITLE>NWC24 Download API Introduction</TITLE>
<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
<LINK rel="stylesheet" type="text/css" href="../nwc24.css">
</HEAD>
<BODY>
<H1>NWC24 Download API</H1>

<H2>Introduction</H2>
<P>
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.<BR>With this function, applications can receive additional data without making the user wait.
</P>

<UL>
<LI>The URL for the synchronized content must be pre-registered in the application.
<LI>Wii automatically checks for updates to the content on the server at fixed intervals. (The interval is specified at the same time the URL is registered in the application.)
<LI>If the content on the server has been updated, Wii automatically downloads and saves the content to its NAND flash.
<LI>If the user does not start the application that registered the URL, automatic synchronization will be stopped.
</UL>
<P>
</P>

<H2><a name="idea">Overview</a></H2>

<DL>
	<DT>Download Task (Task)</DT>
	<DD>
		<P>
		The download task refers to the collection of settings necessary for download reservation, such as the URL and check intervals for content updates.
		</P>
	</DD>
	<DT>Download Task List (Task List)</DT>
	<DD>
		<P>
		The download task list is a list of enabled download tasks.
		</P>
		<P>
		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.
		</P>
		<P>
		Download tasks can be deleted from the task list automatically. (Details are described below.))
		</P>
	</DD>

	<DT>Download Box</DT>
	<DD>
		<P>
		The download box is the storage location of the downloaded data. There is one download box for each application.
		</P>
		<P>
		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.
		</P>
	</DD>

	<DT>Signature</DT>
	<DD>
		<P>
		  WiiConnect24 automatically verifies the signature to ensure that the downloaded contents have not been falsified.<BR>To ensure security, contents acquired through HTTP must always have the correct signature.
		</P>
		<P>
		  See also: <A href="sign.html">NWC24 Download Signatures</A>
		</P>
	</DD>

</DL>


<H2><a name="parameter">Download Task Configuration Items</a></H2>
<P>
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.
</P>

<DL>


<DT><a name="parameter_url">URL</a></DT>
<DD>
	<P>
		Specifies the content acquisition source. Although the HTTP and HTTPS protocols are supported, the following restrictions are set to ensure security.
	</P>
	<DL>
		<DT>a. When using HTTP</DT>
		<DD>
			<P>
			  The signature verification functionality in WiiConnect24 must always be enabled.<BR>This restriction may be disabled through <A href="NWC24EnableDlLaxParameterChecking.html"><CODE>NWC24EnableDlLaxParameterChecking()</CODE></A> only for debugging.
			</P>
		</DD>
		<DT>b. When using HTTPS</DT>
		<DD>
		  <P>The target server must have a server certificate that was issued by the Nintendo CA.</P>
		</DD>
	</DL>
	<P>
	  <A href="NWC24SetDlUrl.html"><CODE>NWC24SetDlUrl()</CODE></A>, <A href="NWC24GetDlUrl.html"><CODE>NWC24GetDlUrl()</CODE></A>
	</P>
</DD>

<DT><a name="parameter_interval">Update Check Interval</a></DT>
<DD>
  <P>
	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.
	</P>
	<P>
	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.
	</P>
	<P>
	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.
	</P>
	<P>
	  <A href="NWC24SetDlInterval.html"><CODE>NWC24SetDlInterval()</CODE></A>, <A href="NWC24GetDlInterval.html"><CODE>NWC24GetDlInterval()</CODE></A>
	</P>
</DD>

<DT>Priority</DT>
<DD><P>
	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 <A href="../Scheduler/intro.html">NWC24 Scheduler Operation Functions</A>.
	</P>
	<P>
	For this reason, if the update check interval is short, set the priority low so other tasks are given priority.<BR>There are restrictions that depend on the number of registered tasks and the update check interval. For details, see the <I>WiiConnect24 Programming Guidelines</I>.
	</P>
	<P>
	Smaller values indicate higher priority.
	</P>
	<P>
	  <A href="NWC24SetDlPriority.html"><CODE>NWC24SetDlPriority()</CODE></A>, <A href="NWC24GetDlPriority.html"><CODE>NWC24GetDlPriority()</CODE></A>
	</P>
</DD>

<DT>Download Count</DT>
<DD>
	<P>
	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.
	</P>
	<P>
	The download count decrements by 1 when the update check is successful. In other words,
	</P>
	<UL>
	<LI>you know if the Wii has connected to the server but there is no updated content, since the count decrements by 1 even if nothing was downloaded
	<LI>If there is a network error or a server error and the process fails, the count will not change.
	</UL>
	<P>
	  <A href="NWC24SetDlCount.html"><CODE>NWC24SetDlCount()</CODE></A>, <A href="NWC24GetDlCount.html"><CODE>NWC24GetDlCount()</CODE></A>
	</P>
</DD>

<DT>File Name</DT>
<DD>
  <P>
	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.
	</P>
	<P>
	Normally there is no need to specify this.
  </P>
	<P>
	  <A href="NWC24SetDlFilename.html"><CODE>NWC24SetDlFilename()</CODE></A>, <A href="NWC24GetDlFilename.html"><CODE>NWC24GetDlFilename()</CODE></A>
	</P>
</DD>

<DT><a name="parameter_serverinterval">Server-side Update Interval</a></DT>
<DD>
	<P>
	Specifies the update interval of the specified URL.
	</P>
	<P>
	This setting will be used in a future upgrade. Currently, this value is not used, even if it is configured.
	</P>
	<P>
	  <A href="NWC24SetDlServerInterval.html"><CODE>NWC24SetDlServerInterval()</CODE></A>, <A href="NWC24GetDlServerInterval.html"><CODE>NWC24GetDlServerInterval()</CODE></A>
	</P>
</DD>

<DT>Retry Margin</DT>
<DD>
	<P>
	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.<BR>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.
	</P>
	<P>
	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.
	</P>
	<P>
	In the following situations, set a smaller retry margin, as needed, so that other tasks have higher priority:
	</P>
	<UL>
		<LI>When the update check interval is short</LI>
		<LI>When the priority is high</LI>
		<LI>When you want to avoid running an application immediately after startup, such as for a large download</LI>
	</UL>
	<P>
	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.
	</P>
	<P>
	  <A href="NWC24SetDlRetryMargin.html"><CODE>NWC24SetDlRetryMargin()</CODE></A>, <A href="NWC24GetDlRetryMargin.html"><CODE>NWC24GetDlRetryMargin()</CODE></A>
	</P>
</DD>

<DT>Flag</DT>
<DD>
	<P>
	Various additional functions becomes usable through flags.
	</P>
	<P>
	  <A href="NWC24SetDlFlags.html"><CODE>NWC24SetDlFlags()</CODE></A>, <A href="NWC24GetDlFlags.html"><CODE>NWC24GetDlFlags()</CODE></A>
	</P>
</DD>

<DT>Application ID</DT>
<DD>
  <P>
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.
  </P>
	<P>
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. <BR>This does not apply if the task has <A href="NWC24SetDlFlags.html">group-writable settings</A> on. Also, this limit is not imposed on the same application in different regions.
  </P>
	<P>
	  <A href="NWC24GetDlAppId.html"><CODE>NWC24GetDlAppId()</CODE></A>
	</P>
</DD>
</DL>


<H2><a name="parameter_application">Per-Application Setting Items</a></H2>
<P>
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.
</P>

<DL>

<DT>Download Box</DT>
<DD>
  <P>
The application must provide a VF archive that can store the contents retrieved by tasks that it registered.
	</P>
</DD>

<DT><a name="">Public Keys and Shared Keys</a></DT>
<DD>
	<P>
	Public keys are used to verify content signatures. Shared keys are used to decrypt encrypted content.
  </P>
	<P>
	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 <A href="NWC24GetDlAppId.html"><CODE>NWC24SetDlKeys()</CODE></A> and are stored in the Home directory.
	</P>
</DD>
</DL>


<H2>Flow of Download API Usage</H2>
<H4>Download Task Registration</H4>

<P>At each application startup, the following registration sequence is performed:</P>
<OL>
	<LI>Check for registered tasks
	<LI>Create new task(s)
	<LI>Update the remaining download count
	<LI>(Re-)register tasks to the list
</OL>

<DL class="sequence">
<DT>1. Check for Registered Tasks</DT>
<DD>
	<P>
	Attempt to acquire tasks to check whether previously registered download tasks remain. If successful, go to 4. ((Re-)register tasks to the list.)
	</P>
	<P><A href="../Types/NWC24DlTask.html"><CODE>NWC24DlTask</CODE> Structure</A>, <A href="NWC24GetDlTask.html"><CODE>NWC24GetDlTask()</CODE></A>, <A href="NWC24GetDlTaskMine.html"><CODE>NWC24GetDlTaskMine()</CODE></A>, <A href="NWC24GetDlTaskByAppId.html"><CODE>NWC24GetDlTaskByAppId()</CODE></A></P>
</DD>

<DT>2. Create New Task(s)</DT>
<DD>
	<P>
	Create and configure new download task(s). (See <a href="#parameter">Download Task Configuration Items</a> for the configuration items.) Usually, setting only the URL and the update check interval is sufficient.
	</P>
	<P>
	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.))
	</P>
	<P>
	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.
	</P>
	<P><A href="NWC24InitDlTask.html"><CODE>NWC24InitDlTask()</CODE></A>, <A href="NWC24CreateDlVf.html"><CODE>NWC24CreateDlVf()</CODE></A>, <A href="NWC24SetDlUrl.html"><CODE>NWC24SetDlUrl()</CODE></A>, <A href="NWC24SetDlInterval.html"><CODE>NWC24SetDlInterval()</CODE></A>, <A href="NWC24SetDlPriority.html"><CODE>NWC24SetDlPriority()</CODE></A>, ...</P>
</DD>

<DT>3. Update the Remaining Download Count</DT>
<DD>
	<P>Reset the remaining download count.</P>
	<P>
	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.
	</P>
	<P><A href="NWC24SetDlCount.html"><CODE>NWC24SetDlCount()</CODE></A></P>
</DD>

<DT>4. (Re-)register Tasks to the List</DT>
<DD>
	<P>
	Register/re-register created or acquired tasks to the task list.
	</P>
	<P>
	Use <A href="NWC24AddDlTask.html"><CODE>NWC24AddDlTask()</CODE></A> if the task was created in step 2, and <A href="NWC24AddDlTask.html"><CODE>NWC24UpdateDlTask()</CODE></A> if the task was successfully acquired in step 1. See the function reference for the differences between the two.
	</P>
</DD>
</DL>

<H4>Acquisition of Downloaded File</H4>
<P>
The download box is a VF library archive file. Use the <A href="../../vf/index.html" target="_top">VF API</a> to extract data.
</P>

<P>
Get the archive file path name using <A href="NWC24GetDlVfPath.html"><CODE>NWC24GetDlVfPath()</CODE></A>. To get or delete downloaded files, the NWC24 library must be set in advance to a usable state by calling <CODE><A href="../Misc/NWC24OpenLib.html">NWC24OpenLib()</A></CODE>. There is no guarantee of operations if you manipulate VF archive files when the library is not open and in a usable state.
</P>

<H2>Precautions When Designing Content Reception</H2>

<H3>How to Check Content Update from an Application</H3>
<P>
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.<BR>
</P>
<P>
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.
</P>

<P>
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.
</P>


<P>Example of use where embedded sequence numbers is recommended:</P>
<UL>
<LI>For delivery of items and other cases where obtained content is reflected in the Save Data<BR>If there is a process that deletes an existing file in the Download Box when new data arrives, so that the new data is reflected in the game, there will be cases where valuable items can be obtained multiple times.

</UL>

<P>Example of use where embedded sequence numbers is not necessary:</P>
<UL>
<LI>For delivery of ranking data and other such content that is downloaded for display purposes only
</UL>


<H3>Do Not Depend on Acquisition Timing</H3>
<P>
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.
</P>


<H3>Preparing for Empty Content</H3>
<P>
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.
</P>
<P>
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.
</P>


<H2>Notes for Developers</H2>

<P>
The settings and data of the download task are stored in the following locations:
</P>

<OL>
<LI>The Save Data directory of each application (Public key, Secret key, Download Box)</LI>
<LI>The WiiConnect24 system region (Items besides those of 1. that are accessed by special functions) </LI>
</OL>

<P>
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.
</P>

<H3>Changing the Development Environment</H3>
<P>
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.<BR>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.
</P>

<P>
Specifically, cases such as the following require caution:
</P>
<UL>
<LI>Switching the DVD library and CNT library while developing a NAND application</LI>
<LI>Overwriting the GameCode in a <CODE>ddf</CODE> file</LI>
</UL>

<P>
In situations like these, we recommend deleting all download tasks once.
</P>

<H3>Deleting Save Data</H3>
<P>
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.
</P>

<P>
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.
</P>

<H2>Revision History</H2>
<P>
2007/11/12 Added text specific to the use of empty content.
<BR> 2007/09/26 Added information on deleting saved data. <BR> 2007/07/24 Added notes on changing the development environment, etc. <BR> 2007/06/06 Added notes on designing receivable content.<BR> 2006/11/17 Initial version.fc<BR></P>

<hr><p>CONFIDENTIAL</p></body>
</HTML>