The NWC24 message API provides an environment to create, view, and manage messages that are exchanged between Wii consoles or between a Wii console and an external e-mail environment.
WiiConnect24 messages can be exchanged between Wii consoles or between a Wii console and an external e-mail environment using standard e-mail technology. Specifically, messages exchanged between Wii consoles are called Wii Messages and messages exchanged between a Wii console and an external e-mail environment are called Public Messages.
Just like a standard e-mail message, a WiiConnect24 message consists of information about the sender and recipient, a subject, and body text. It can also handle up to two binary data files as attachments. Each application can communicate by including messages to friends, images, game data, and other information in these messages.
Although the internal format of a WiiConnect24 message conforms to the standard e-mail format, because the library performs all format processing, output can be simplified by using a format where only text strings and data are passed to a function (as seen from the perspective of the application).
The Outbox and Inbox are temporary storage locations for messages allocated from part of Wii console NAND memory. They are allocated in a special location that cannot be accessed using standard NAND functions.
The Outbox is used to store WiiConnect24 messages created by an application. Messages located here are sent periodically by automatic send/receive firmware upon connection to the server. (With some exceptions, messages are deleted after they are sent.)
The Outbox has a capacity of around 2 MB and can hold up to a maximum of 127 messages.
The Outbox can become full in certain cases, such as when the automatic send/receive feature is stopped or when communications are interrupted. When this happens the Outbox will not accept any new messages.
The Inbox is used to store messages received from the server via the automatic send/receive function. Each message is saved until the application opens and deletes it or until the Inbox becomes full. (If the Inbox becomes full, messages are deleted in the order of oldest message first.)
The Inbox has a capacity of around 7 MB and can hold a maximum of 255 messages.
The library must be open in order to use the NWC24 message function. Use NWC24OpenLib to open the library. If the library is not completely open, an error will result when an attempt is made to execute some NWC24 functions.
Use NWC24CloseLib to close the library once the series of processing is complete. Note: Automatic send/receive processing will not launch if the library is not closed.
The actual procedure used to create a WiiConnect24 message and store it in the Outbox is given below:
NWC24InitMsgObj)
NWC24SetMsg* functions)
NWC24CommitMsg)
Set information such as the destination address and body text using an NWC24MsgObj object. NWC24MsgObj holds pointers to individual data items temporarily.
Once all required information has been registered, call the NWC24CommitMsg() function to create a message in e-mail format corresponding to the information set for this object and store it in the Outbox.
Character strings such as the message body and subject are merely passed to the internal format as they are. The use of a dedicated function like NWC24SetMsgSubjectAndTextPublic() to handle multiple language responses in public messages will automatically convert text encoding internally. (Internally, the ENC library included in the Revolution SDK is called.)
The procedure for getting a list of messages stored in the Outbox or Inbox is given below:
NWC24GetMsgObj)
NWC24GetMsg* functions)
The WiiConnect24 messages stored in each box are assigned individual 32-bit message IDs. If you want to get a list of messages, first call the NWC24GetMsgIdList() function to get a list of IDs being maintained by the box.
Next, specify one of the IDs in the ID list and call the NWC24GetMsgObj() function, which gets the meta-information for the message specified and stores it in a NWC24MsgObj structure.
The meta-information obtained here includes information required for searching messages, such as the sender, date of creation, application ID, etc. Use separate functions to get that information to determine whether an application needs to handle the message.
The Message Search Utility Function has been prepared as a method to more simply obtain the list of messages.
The procedure for getting messages is simply an extension of the procedure described above for getting a list of messages.
After retrieving the list of message IDs for the box in question, call the NWC24GetMsgObj() function and store meta information for the message having the specified ID in an NWC24MsgObj object.
As described above, meta-information such as the sender ID, date, etc. can be retrieved at this point by using the NWC24GetMsg* functions without accessing actual message files.
Get variable length parts of the message, such as body text and attached files, using the NWC24ReadMsg* functions based on the NWC24MsgObj object, that includes the meta-information that was retrieved. These functions actually access message files internally and read the data.
Once the application has retrieved a message from the inbox and is done with it, the message must be deleted quickly in order to maintain storage capacity (unless there is some reason to keep the message).
Use the NWC24DeleteMsg() function to delete messages by simply specifying the box in question and the message ID.
This function can be used to delete messages stored in the Outbox as well as those stored in the Inbox.
However, as a rule, deletion can be performed only from the application that created the message. Also, messages handled by the Wii Menu's Wii Message Board is deleted automatically by the Wii Message Board.
When a message is exchanged between Wii consoles, the Application ID and Group ID of the application sending the message is incorporated into the message automatically.
The Application ID is 4 bytes of information, and the actual value specified for this information is the application's game code. The Group ID is 2 bytes of information, and the actual value specified for this information is the application's company code. You can get the ID information embedded in each message using NWC24GetMsgAppId and NWC24GetMsgGroupId.
When an application reads a received message, it checks whether the ID in the message matches its own ID and uses this to determine whether the message was sent by the same or a different application. If the only difference in the Application ID is the destination region (the fourth character of the game code), the application assumes the sender application is the same as itself.
Given the above specifications, the same application can handle WiiConnect24 messages regardless of the destination region. Conversely, to handle only closed messages for a specific destination region, you must assign based on the application ID value for the received message.
The Wii Menu includes a feature called the Wii Message Board for viewing WiiConnect24 messages received by the Wii console. This allows users to view messages from a particular application without starting (or owning) that application. For details on how to output messages onto the Wii Message Board, see NWC24API and Wii Message BoardIn such cases, be sure to specify NWC24_MSGTYPE_WII_MENU or NWC24_MSGTYPE_WII_MENU_SHARED as the message type when performing initialization with NWC24InitMsgObj().
NWC24_MSGTYPE_WII_MENU cannot be accessed from a standard application.NWC24_MSGTYPE_WII_MENU_SHARED is specified, the message is read-only.
To exchange data between applications, create a "for application" message. In such cases, be sure to specify NWC24_MSGTYPE_WII_APP as the message type when performing initialization with NWC24InitMsgObj(). In addition, when NWC24_MSGTYPE_WII_APP_HIDDEN is specified, access from other applications is completely prohibited, allowing communication only within an application.
Although the WiiConnect24 mechanism maintains a certain level of communication security, no special measures have been taken regarding the possibility of data being read by other applications.
If you want to implement stricter data security, specify NWC24_MSGTYPE_WII_APP_HIDDEN and take additional measures, such as using the NET library to encrypt the data.
The maximum size of messages that can be created using the NWC24 API is 200 KB (more specifically, 203,776 bytes). The message body and any attachment data must fall within this size restriction. The header size is not included in this restriction.
The use of attachments and body text that is MIME-encoded may result in sizes larger than the original data, which will mean that the actual size of usable data will be smaller than the restriction. (When encoded in Base64 format, the increase in data size over the original, for example, will be by a factor of 78/57. Thus, when the body is left blank, a maximum of roughly 140 KB of data can be attached. To calculate the size after Base64 encoding, use the macro NWC24_BASE64_ENCODED_SIZE().
WiiConnect24 messages are sent and received using standard e-mail technologies. In other words, there is no system to guarantee with 100% certainty that a sent message has reached the other party.
Furthermore, the sending of the message may fail due to such factors as:
These factors do not arise often with normal messaging, but you should make sure to design your applications to not fail when messages don't reach the other party.
Note also that it is possible for messages to arrive significantly late, and when multiple messages are sent, for the order of reception to differ from the order of transmission.
2007/11/27 Made revisions in conjunction with the present implementation.
2007/10/15 Added text relevant to the certainty of sending and receiving messages.
2007/04/04 Added a section about the maximum number of messages to store.
2007/03/15 Added a section about access rights.
2007/01/30 Minor revisions.
2007/01/12 Added a section about size restrictions.
2006/12/08 Separated section out from the overall introduction.
CONFIDENTIAL