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 error handling sequence</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 Error Handling Sequence</H1> 12 13<H2>Introduction</H2> 14<P> 15When creating applications that support WiiConnect24, processing must take into account the restrictions and operation status of WiiConnect24. NWC24 functions may return errors depending on these restrictions and status. When one of these errors is returned, the features that use WiiConnect24 cannot be made available. You must notify the user by displaying the error message and error code (a six-digit number) to the screen. 16</P> 17<P> 18Please refer to WiiConnect24 Programming Guidelines for the type of notification required for a specific error. This document describes error sequence examples based on the guidelines, including possible specific use. 19</P> 20 21 22<H2>Functions that are Particularly Important to Error Handling</H2> 23<P> 24Error handling is particularly important for the following two functions in the NWC24 API. 25</P> 26<P> 27 <UL> 28<LI><A href="../Misc/NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A> 29 <UL> 30<LI><A HREF="ERR_NWC24OpenLib.html"> Error Handling Sequence</A> 31 </UL> 32<LI><A href="../Misc/NWC24Check.html"><CODE>NWC24Check</CODE></A> 33 <UL> 34<LI><A HREF="ERR_NWC24CheckMsg.html"> Error Handling Sequence (Message)</A> 35<LI><A HREF="ERR_NWC24CheckDl.html"> Error Handling Sequence (Download)</A> 36 </UL> 37 </UL> 38</P> 39<P> 40<A href="../Misc/NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A> determines whether the NWC24 library itself can be used. For example, it will return an error in situations such as a failure occurring in a system file and usage no longer being possible. 41</P> 42<P> 43<A href="../Misc/NWC24Check.html"><CODE>NWC24Check</CODE></A> determines availability of the NWC24 feature, including console settings and network connection. When it is not available, NWC24Check returns an error corresponding to that state. 44</P> 45<P> 46Error handling for these two functions is necessary to execute most operations that use NWC24. 47</P> 48 49<H2>Examples of Error Handling for Various Processes</H2> 50 51<H4>Reading a received message</H4> 52 53<P> 54The <A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE> error handling sequence</A> is the only item required when an application checks for a received message in the inbox. Because this check only involves messages that are already in the inbox, verification by <CODE>NWC24Check</CODE> is not necessary. 55</P> 56 57<UL> 58<LI><A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE> error handling</A>: For example, when an application automatically checks for new messages at startup, this operation does not fall under "explicit use" with respect to the user, so it is not necessary to display an error message on screen. Even if an error is returned, you may consider the error to indicate that no messages were received, and continue processing. On the other hand, if it is clear to the user that a certain game sequence checks for data received by WiiConnect24, it is necessary to display an error message and notify the user that the feature or mode is not available. 59 60<LI>If a file-related error occurs while obtaining the message list or performing a search, the message acquisition itself will fail, but you may or may not display an error message at that point. In cases like these, an error will occur the next time <CODE>NWC24OpenLib</CODE> is called, as well. 61 62<LI>If a file-related error occurs when reading a body or attached binary of an individual message, it is possible that the message alone is corrupted. Because there will be no effect on other messages, abandon processing of that message and, if possible, delete it. You do not need to display an error message. 63</UL> 64 65<H4>Creating a message to send</H4> 66 67<P> 68When creating a message to send to another Wii console or to an e-mail address, both the <A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A> and <A HREF="ERR_NWC24CheckMsg.html"><CODE>NWC24Check (NWC24_USE_MESSAGES)</CODE></A> error handling sequences are required. 69</P> 70 71<UL> 72<LI>For example, if a game has a feature to "Send Edited Data to a Friend", wherein the user selects a Friend and then sends the data, that sequence would fall under "explicit use" by the user. It is required to display an error message on the screen if an error occurs in the functions mentioned above. 73 74<LI>As another example, an error message does not need to be displayed for a feature that automatically sends the user's scores at regular intervals to a friend that was specified in advance, because the timing at which messages are generated is not explicit with respect to the user. However, when implementing a feature that involves automatic data transmissions, it is a prerequisite that the user give consent and turn the feature on. 75 76<LI>For explicit use cases, it is desirable to also display an error message when <A HREF="../Message/NWC24CommitMsg.html"><CODE>NWC24CommitMsg</CODE></A> returns a file-related error, but it is not required. 77</UL> 78 79<H4>Creating a message for the Wii Message Board</H4> 80 81<P> 82When creating a message for the local Wii Message Board, the only requirement is the <A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE> error handling sequence</A>. Verification with <CODE>NWC24Check</CODE> is not necessary because this process does not involve network communication, and this feature is not restricted by the console settings related to WiiConnect24. (There is no restriction on messages to another console's Wii Message Board.) 83</P> 84 85<UL> 86<LI>When implementing a feature that, for example, leaves a message on the Wii Message Board to commemorate clearing a level in a game, the message is not necessarily created intentionally by the user and therefore does not fall under "explicit use." As a result, an error message does not need to be displayed. 87 88<LI>File-related errors in <A HREF="../Message/NWC24CommitMsg.html"><CODE>NWC24CommitMsg</CODE></A> should be handled in the same manner as when creating a message to send. 89</UL> 90 91<H4>Reading the Friend Roster (Address Book)</H4> 92 93<P> 94The action of reading the console friend roster is not itself restricted by network communications or WiiConnect24 settings. Consequently, it is acceptable to perform only the <A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE> error handling sequence</A>. 95</P> 96 97<UL> 98<LI>However, we recommend performing <A HREF="ERR_NWC24CheckMsg.html">error checks using <CODE>NWC24Check (NWC24_USE_MESSAGES)</CODE></A> before reading the friend roster, because accessing the console friend roster is normally followed by the transmission of a message. 99</UL> 100 101<H4>Confirmation of agreement for automatic transmissions</H4> 102 103<P> 104As described in Creating a Message to Send, the user's consent must be obtained in advance, and then the user must turn on a feature that automatically sends that user's scores at regular intervals to a specified Friend. During the setting sequence to turn the feature ON, <CODE>NWC24Check (NWC24_USE_SETTING)</CODE> must be executed to avoid any conflict with the console WiiConnect24 settings. If an error is returned, the feature must be disabled. 105</P> 106 107<UL> 108<LI> To execute <CODE>NWC24Check</CODE>, you must first execute <CODE>NWC24OpenLib</CODE>. As a result, <A HREF="ERR_NWC24OpenLib.html">error handling in <CODE>NWC24OpenLib</CODE></A> will also be inevitably added. 109 110<LI>If an error occurs here, the error indicates a problem with the user's attempt to turn the feature ON, so this falls under "explicit use." Consequently, an error message must be displayed. 111</UL> 112 113<H4>Adding a new download task</H4> 114 115<P> 116Both the <A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A> and <A HREF="ERR_NWC24CheckDl.html"><CODE>NWC24Check (NWC24_USE_DOWNLOADS)</CODE></A> error handling sequences are necessary when adding a new download task. 117</P> 118 119<UL> 120<LI>An error message does not need to be displayed when a download task is automatically added at application startup time. However, an error message must be displayed if the application itself does not work without the download task registered. 121 122<LI>Likewise, an error message must also be displayed for a sequence wherein a download task is added by a user operation. 123</UL> 124 125<H4>Confirming downloaded data</H4> 126 127<P> 128It is theoretically possible for data that was obtained by a download task to be verified independently of NWC24, because verification only references a VF file. However, calling <CODE>NWC24OpenLib</CODE> in advance is required to access the VF file, so the <A HREF="ERR_NWC24OpenLib.html">error handling sequence for <CODE>NWC24OpenLib</CODE></A> is also required. 129</P> 130 131<UL> 132<LI>In addition to this, you must determine whether or not the most recent data has properly arrived. As a way of making a determination, go through the following steps. First, use <A HREF="ERR_NWC24CheckDl.html"><CODE>NWC24Check (NWC24_USE_DOWNLOADS)</CODE></A> to check if the environment in which a download task is run is ready. Next, call <A href="../Download/NWC24GetDlError.html"><CODE>NWC24GetDlError</CODE></A> for the download task that is being used to check if a problem occurred when obtaining data from the server. To make absolutely certain that the data is the latest, we recommend including information for verifying the version inside the data. 133 134<LI>If the application has been designed to expect that the most recent data is always obtained, verification by the aforementioned steps and display of the consequent error messages are both required. Even in other situations, if a problem occurs while obtaining data, although it is not required, a courteous design will do well to convey that state to the user in some fashion. 135 136<LI>Another consideration for applications that always require the most recent data is to call <A href="../Scheduler/NWC24ExecDownloadTask.html"><CODE>NWC24ExecDownloadTask</CODE></A> when that data could not be obtained, and perform data acquisition then. In this case, an error message is not displayed until an error results when executing <A href="../Scheduler/NWC24ExecDownloadTask.html"><CODE>NWC24ExecDownloadTask</CODE></A>. 137</UL> 138 139<BR><BR> 140 141<H2>Displaying Error Messages and Error Codes</H2> 142 143<P> 144When an on-screen notification is necessary during an error handling sequence, refer to WiiConnect24 Programming Guidelines and WiiConnect24 Message List for error messages, and display an appropriate message. 145</P> 146<P> 147The six-digit error code can be obtained by executing <A href="../Misc/NWC24GetErrorCode.html"><CODE>NWC24GetErrorCode</CODE></A> immediately after a function has returned an error. If <A href="../Misc/NWC24GetErrorCode.html"><CODE>NWC24GetErrorCode</CODE></A> returns 0, this means that either a notification is not necessary for that error or the error code is not defined. In the event that it is necessary to display an error message when an error code is undefined, use the general-purpose <CODE>NWC24_ERRCODE_UNDEFINED (-109999)</CODE> error code, which indicates a "miscellaneous error". 148</P> 149<P> 150There is no particular restriction on the screen layout for displaying error messages and error codes, as long as it is in a format that can be read normally. 151</P> 152 153<BR><BR> 154 155<H2>Operations After the Error Handling Sequence Runs</H2> 156 157<P> 158When an error is generated through non-explicit user actions, it is not necessary to display an error message. The application can simply continue to run, given that the desired process that used WiiConnect24 did not occur. 159</P> 160<P> 161Although it is necessary to display an error message for an explicit user error, the application can simply continue to run as in the previous case, given that the desired process that used WiiConnect24 failed. However, should the application be unable to proceed without the desired process, it is acceptable either to run <CODE>OSReturnToMenu</CODE> to return to the Wii Menu or to run <CODE>OSRestart</CODE> to restart the application. 162</P> 163 164<BR><BR> 165 166<H2>See Also</H2> 167<P> 168<A href="../Misc/NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A><BR><A href="../Misc/NWC24Check.html"><CODE>NWC24Check</CODE></A><BR> <A href="../Misc/NWC24GetErrorCode.html"><CODE>NWC24GetErrorCode</CODE></A><BR><A href="../Message/NWC24CommitMsg.html"><CODE>NWC24CommitMsg</CODE></A><BR> <A href="../Download/NWC24GetDlError.html"><CODE>NWC24GetDlError</CODE></A><BR><A href="../Scheduler/NWC24ExecDownloadTask.html"><CODE>NWC24ExecDownloadTask</CODE></A><BR> <BR> <A HREF="ERR_NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE> Error Handling Sequence</A><BR> <A HREF="ERR_NWC24CheckMsg.html"><CODE>NWC24Check</CODE> (Message) Error Handling Sequence</A><BR> <A HREF="ERR_NWC24CheckDl.html"><CODE>NWC24Check</CODE> (Download) Error Handling Sequence</A><BR> 169 170<H2>Revision History</H2> 171<P> 1722007/11/27 Made minor revisions in text. 173<BR> 2007/08/23 Initial version.</P> 174 175<hr><p>CONFIDENTIAL</p></body> 176</HTML>