NWC24 Error Handling Sequence

Introduction

When 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.

Please 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.

Functions that are Particularly Important to Error Handling

Error handling is particularly important for the following two functions in the NWC24 API.

NWC24OpenLib 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.

NWC24Check 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.

Error handling for these two functions is necessary to execute most operations that use NWC24.

Examples of Error Handling for Various Processes

Reading a received message

The NWC24OpenLib error handling sequence 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 NWC24Check is not necessary.

NWC24OpenLib error handling: 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.
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 NWC24OpenLib is called, as well.
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.

Creating a message to send

When creating a message to send to another Wii console or to an e-mail address, both the NWC24OpenLib and NWC24Check (NWC24_USE_MESSAGES) error handling sequences are required.

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.
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.
For explicit use cases, it is desirable to also display an error message when NWC24CommitMsg returns a file-related error, but it is not required.

Creating a message for the Wii Message Board

When creating a message for the local Wii Message Board, the only requirement is the NWC24OpenLib error handling sequence. Verification with NWC24Check 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.)

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.
File-related errors in NWC24CommitMsg should be handled in the same manner as when creating a message to send.

Reading the Friend Roster (Address Book)

The 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 NWC24OpenLib error handling sequence.

However, we recommend performing error checks using NWC24Check (NWC24_USE_MESSAGES) before reading the friend roster, because accessing the console friend roster is normally followed by the transmission of a message.

Confirmation of agreement for automatic transmissions

As 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, NWC24Check (NWC24_USE_SETTING) must be executed to avoid any conflict with the console WiiConnect24 settings. If an error is returned, the feature must be disabled.

To execute NWC24Check, you must first execute NWC24OpenLib. As a result, error handling in NWC24OpenLib will also be inevitably added.
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.

Adding a new download task

Both the NWC24OpenLib and NWC24Check (NWC24_USE_DOWNLOADS) error handling sequences are necessary when adding a new download task.

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.
Likewise, an error message must also be displayed for a sequence wherein a download task is added by a user operation.

Confirming downloaded data

It 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 NWC24OpenLib in advance is required to access the VF file, so the error handling sequence for NWC24OpenLib is also required.

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 NWC24Check (NWC24_USE_DOWNLOADS) to check if the environment in which a download task is run is ready. Next, call NWC24GetDlError 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.
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.
Another consideration for applications that always require the most recent data is to call NWC24ExecDownloadTask 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 NWC24ExecDownloadTask.

Displaying Error Messages and Error Codes

When 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.

The six-digit error code can be obtained by executing NWC24GetErrorCode immediately after a function has returned an error. If NWC24GetErrorCode 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 NWC24_ERRCODE_UNDEFINED (-109999) error code, which indicates a "miscellaneous error".

There 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.

Operations After the Error Handling Sequence Runs

When 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.

Although 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 OSReturnToMenu to return to the Wii Menu or to run OSRestart to restart the application.

Revision History

2007/11/27 Made minor revisions in text.
2007/08/23 Initial version.

CONFIDENTIAL