1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META http-equiv="Content-Style-Type" content="text/css"> 6<TITLE>NWC24 Download API Introduction</TITLE> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<LINK rel="stylesheet" type="text/css" href="../nwc24.css"> 9</HEAD> 10<BODY> 11<H1>NWC24 Download API</H1> 12 13<H2>Introduction</H2> 14<P> 15Wii 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. 16</P> 17 18<UL> 19<LI>The URL for the synchronized content must be pre-registered in the application. 20<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.) 21<LI>If content on the server has been updated, it will be saved to Wii console NAND memory. 22<LI>If the user does not start the application that registered the URL, automatic synchronization will be stopped. 23</UL> 24<P> 25</P> 26 27 28<H2><a name="idea">Terminology Descriptions</a></H2> 29 30<DL> 31 <DT>Download Task (Task)</DT> 32 <DD> 33 <P> 34 The download task refers to the collection of settings necessary for download reservation, such as the URL and check intervals for content updates. 35 </P> 36 </DD> 37 <DT>Download Task List (Task List)</DT> 38 <DD> 39 <P> 40 The download task list is a list of enabled download tasks. 41 </P> 42 <P> 43 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. 44 </P> 45 <P> 46 Download tasks can be deleted from the task list automatically. (Details are described below.)) 47 </P> 48 </DD> 49 50 <DT>Download Box</DT> 51 <DD> 52 <P> 53 The download box is the storage location of the downloaded data. There is one download box for each application. 54 </P> 55 <P> 56 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. 57 </P> 58 </DD> 59 60 <DT>Signature</DT> 61 <DD> 62 <P> 63 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. 64 </P> 65 <P> 66 Use the website called NWCWMS to apply a signature to the content. For details, see "Applying for and Using the System that Handles Download Content" in the WiiConnect24 Overview. <BR> 67 </P> 68 </DD> 69 70</DL> 71 72 73<H2><a name="parameter">Download Task Configuration Items</a></H2> 74<P> 75The 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. 76</P> 77 78<DL> 79 80 81<DT><a name="parameter_url">URL</a></DT> 82<DD> 83 <P> 84 Specifies the content acquisition source. Although the HTTP and HTTPS protocols are supported, the following restrictions are set to ensure security. 85 </P> 86 <DL> 87 <DT>a. When using HTTP</DT> 88 <DD> 89 <P> 90 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. 91 </P> 92 </DD> 93 <DT>b. When using HTTPS</DT> 94 <DD> 95 <P>The target server must have a server certificate that was issued by the Nintendo CA.</P> 96 </DD> 97 </DL> 98 <P> 99 The standard ports will be used for each protocol during communications. (Port 80 for http and port 443 for https.) If a connection is unsuccessful, check for restrictions on connecting through these ports. 100 </P> 101 <P> 102 <A href="NWC24SetDlUrl.html"><CODE>NWC24SetDlUrl()</CODE></A>, 103 <A href="NWC24GetDlUrl.html"><CODE>NWC24GetDlUrl()</CODE></A> 104 </P> 105</DD> 106 107<DT><a name="parameter_interval">Update Check Interval</a></DT> 108<DD> 109 <P> 110 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. 111 </P> 112 <P> 113 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. 114 </P> 115 <P> 116 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. 117 </P> 118 <P> 119 <A href="NWC24SetDlInterval.html"><CODE>NWC24SetDlInterval()</CODE></A>, 120 <A href="NWC24GetDlInterval.html"><CODE>NWC24GetDlInterval()</CODE></A> 121 </P> 122</DD> 123 124<DT>Priority</DT> 125<DD><P> 126 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 startup timing, see the <A href="../Scheduler/intro.html">NWC24 Scheduler Operation Functions</A>.) 127 </P> 128 <P> 129 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>. 130 </P> 131 <P> 132 Smaller values indicate higher priority. 133 </P> 134 <P> 135 <A href="NWC24SetDlPriority.html"><CODE>NWC24SetDlPriority()</CODE></A>, 136 <A href="NWC24GetDlPriority.html"><CODE>NWC24GetDlPriority()</CODE></A> 137 </P> 138</DD> 139 140<DT>Download Count</DT> 141<DD> 142 <P> 143 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. 144 </P> 145 <P> 146 The download count decrements by 1 when the update check is successful. In other words, 147 </P> 148 <UL> 149 <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 150 <LI>If there is a network error or a server error and the process fails, the count will not change. 151 </UL> 152 <P> 153 <A href="NWC24SetDlCount.html"><CODE>NWC24SetDlCount()</CODE></A>, 154 <A href="NWC24GetDlCount.html"><CODE>NWC24GetDlCount()</CODE></A> 155 </P> 156</DD> 157 158<DT>File Name</DT> 159<DD> 160 <P> 161 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. 162 </P> 163 <P> 164 Normally there is no need to specify this. 165 </P> 166 <P> 167 <A href="NWC24SetDlFilename.html"><CODE>NWC24SetDlFilename()</CODE></A>, 168 <A href="NWC24GetDlFilename.html"><CODE>NWC24GetDlFilename()</CODE></A> 169 </P> 170</DD> 171 172<DT><a name="parameter_serverinterval">Server-side Update Interval</a></DT> 173<DD> 174 <P> 175 Specifies the update interval of the specified URL. 176 </P> 177 <P> 178 This setting will be used in a future upgrade. Currently, this value is not used, even if it is configured. 179 </P> 180 <P> 181 <A href="NWC24SetDlServerInterval.html"><CODE>NWC24SetDlServerInterval()</CODE></A>, 182 <A href="NWC24GetDlServerInterval.html"><CODE>NWC24GetDlServerInterval()</CODE></A> 183 </P> 184</DD> 185 186<DT>Retry Margin</DT> 187<DD> 188 <P> 189 When power to the Wii console is turned off or the <a href="../Scheduler/intro.html">NWC24 scheduler</a> has been stopped, the scheduled content update checks for each task will stop. This might result in a substantial delay of the update check.<BR>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. 190 </P> 191 <P> 192 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. 193 </P> 194 <P> 195 In the following situations, set a smaller retry margin, as needed, so that other tasks have higher priority: 196 </P> 197 <UL> 198 <LI>When the update check interval is short</LI> 199 <LI>When the priority is high</LI> 200 <LI>When you want to avoid running an application immediately after startup, such as for a large download</LI> 201 </UL> 202 <P> 203 Since an appropriate value is automatically set by the library, this value typically does not need to be set. Change this value only when necessary, and be sure you understand operations well enough to do so. 204 </P> 205 <P> 206 <A href="NWC24SetDlRetryMargin.html"><CODE>NWC24SetDlRetryMargin()</CODE></A>, 207 <A href="NWC24GetDlRetryMargin.html"><CODE>NWC24GetDlRetryMargin()</CODE></A> 208 </P> 209</DD> 210 211<DT>Flag</DT> 212<DD> 213 <P> 214 Various additional functions becomes usable through flags. 215 </P> 216 <P> 217 <A href="NWC24SetDlFlags.html"><CODE>NWC24SetDlFlags()</CODE></A>, 218 <A href="NWC24GetDlFlags.html"><CODE>NWC24GetDlFlags()</CODE></A> 219 </P> 220</DD> 221 222<DT>Application ID.</DT> 223<DD> 224 <P> 225This 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. 226 </P> 227 <P> 228If the ID of the application that registered the task does not match that of the application that read the task, the reading application cannot alter the task's contents.<BR><BR>This does not apply if the task has the <A href="NWC24SetDlFlags.html">group-writable setting</A> turned on. Also, this limit is not imposed on the same application in different regions. 229 </P> 230 <P> 231 <A href="NWC24GetDlAppId.html"><CODE>NWC24GetDlAppId()</CODE></A> 232 </P> 233</DD> 234</DL> 235 236 237<H2><a name="parameter_application">Per-Application Setting Items</a></H2> 238<P> 239These 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. 240</P> 241 242<DL> 243 244<DT>Download Box</DT> 245<DD> 246 <P> 247The application must provide a VF archive that can store the contents retrieved by tasks that it registered. 248 </P> 249</DD> 250 251<DT><a name="">Public Keys and Shared Keys</a></DT> 252<DD> 253 <P> 254 Public keys are used to verify content signatures. Shared keys are used to decrypt encrypted content. 255 </P> 256 <P> 257 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 keys for the application can be set using the <A href="NWC24SetDlKeys.html"><CODE>NWC24SetDlKeys</CODE></A> function and are stored in the Home directory. 258 </P> 259</DD> 260</DL> 261 262 263 264<H2>Flow of Download API Usage</H2> 265<H4>Download Task Registration</H4> 266 267<P>At each application startup, the following registration sequence is performed:</P> 268<OL> 269 <LI>Check for registered tasks 270 <LI>Create new task(s) 271 <LI>Update the remaining download count 272 <LI>(Re-)register tasks to the list 273</OL> 274 275<DL class="sequence"> 276<DT>1. Check for Registered Tasks</DT> 277<DD> 278 <P> 279 Attempt to acquire tasks to check whether previously registered download tasks remain. If successful, go to 4. ((Re-)register tasks to the list.) 280 </P> 281 <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> 282</DD> 283 284<DT>2. Create New Task(s)</DT> 285<DD> 286 <P> 287 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. 288 </P> 289 <P> 290 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.)) 291 </P> 292 <P> 293 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. 294 </P> 295 <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> 296</DD> 297 298<DT>3. Update the Remaining Download Count</DT> 299<DD> 300 <P>Reset the remaining download count.</P> 301 <P> 302 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. 303 </P> 304 <P><A href="NWC24SetDlCount.html"><CODE>NWC24SetDlCount()</CODE></A></P> 305</DD> 306 307<DT>4. (Re-)register Tasks to the List</DT> 308<DD> 309 <P> 310 Register/re-register created or acquired tasks to the task list. 311 </P> 312 <P> 313 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. 314 </P> 315</DD> 316</DL> 317 318<H4>Acquisition of Downloaded File</H4> 319<P> 320The download box is a VF library archive file. Use the <A href="../../vf/index.html" target="_top">VF API</a> to extract data. 321</P> 322 323<P> 324Get 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. 325</P> 326 327 328 329<H2>Revision History</H2> 330<P> 3312008/02/01 Added a note on the ports that are used and moved the following items to the programming manual: <B>Precautions When Designing Receivable Content</B> and <B>Notes for Developers</B>. <BR>2007/11/12 Added information specific to the use of empty content. <BR>2007/09/26 Added information on deleting save data. <BR>2007/07/24 Added a note on changing the development environment and made other minor changes. <BR>2007/06/06 Added <B>Precautions When Designing Receivable Content</B>. <BR>2006/11/17 Initial version. 332</P> 333 334<hr><p>CONFIDENTIAL</p></body> 335</HTML>