nwc24/Message/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 Message 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 Message API</H1>

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

<H2>Overview</H2>
<DL>
<DT>WiiConnect24 Message</DT>
<DD>
<P>
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 <STRONG>Wii Messages</STRONG> and messages exchanged between a Wii console and an external e-mail environment are called <STRONG>Public Messages</STRONG>.
</P>
<P>
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.
</P>
<P>
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).
</P>
</DD>

<DT>Outbox/Inbox</DT>
<DD>
<P>
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.
</P>
<P>
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.)
</P>
<P>
The Outbox has a capacity of around 2 MB and can hold up to a maximum of 127 messages.
</P>
<P>
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.
</P>
<P>
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.)
</P>
<P>
The Inbox has a capacity of around 7 MB and can hold a maximum of 255 messages.
</P>
</DD>
</DL>

<H2>Using the NWC24 Message Function</H2>

<H4>Initializing the NWC24 Message Library</H4>
<P>
The library must be open in order to use the NWC24 message function. Use <A href="../Misc/NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A> 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.
</P>
<P>
Use <A href="../Misc/NWC24CloseLib.html"><CODE>NWC24CloseLib</CODE></A> to close the library once the series of processing is complete. <B>Note:</B> Automatic send/receive processing will not launch if the library is not closed.
</P>

<H4>Procedure to Create WiiConnect24 Messages</H4>
<P>
The actual procedure used to create a WiiConnect24 message and store it in the Outbox is given below:
</P>
<OL>
<LI>Allocate and initialize an NWC24MsgObj object (<A href="NWC24InitMsgObj.html"><CODE>NWC24InitMsgObj</CODE></A>)
<LI>Set all information for the object (<CODE>NWC24SetMsg*</CODE> functions)
<LI>Create a message and store it in the Outbox (<A href="NWC24CommitMsg.html"><CODE>NWC24CommitMsg</CODE></A>)
</OL>
<P>
Set information such as the destination address and body text using an <A href="../Types/NWC24MsgObj.html"><CODE>NWC24MsgObj</CODE> object</A>. <CODE>NWC24MsgObj</CODE> holds pointers to individual data items temporarily.
</P>
<P>
Once all required information has been registered, call the <A href="NWC24CommitMsg.html"><CODE>NWC24CommitMsg()</CODE> function</A> to create a message in e-mail format corresponding to the information set for this object and store it in the Outbox.
</P>
<P>
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 <A HREF="NWC24SetMsgSubjectAndTextPublic.html"><CODE>NWC24SetMsgSubjectAndTextPublic()</CODE></A> 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.)
</P>

<H4>Procedure to Obtain a List of WiiConnect24 Messages</H4>
<P>
The procedure for getting a list of messages stored in the Outbox or Inbox is given below:
</P>
<OL>
<LI>Get the list of message IDs maintained by the box in question
<LI>Get management information for each ID retrieved (<A href="NWC24GetMsgObj.html"><CODE>NWC24GetMsgObj</CODE></A>)
<LI>Extract each element from the management information retrieved (<CODE>NWC24GetMsg*</CODE> functions)
</OL>
<P>
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 <CODE><A href="NWC24GetMsgIdList.html">NWC24GetMsgIdList()</A></CODE> function to get a list of IDs being maintained by the box.
</P>
<P>
Next, specify one of the IDs in the ID list and call the <A href="NWC24GetMsgObj.html"><CODE>NWC24GetMsgObj()</CODE> function</A>, which gets the meta-information for the message specified and stores it in a <A href="../Types/NWC24MsgObj.html"><CODE>NWC24MsgObj</CODE> structure</A>.
</P>
<P>
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.
</P>
<P>
The <A href="../Search/intro.html">Message Search Utility Function</A> has been prepared as a method to more simply obtain the list of messages.
</P>

<H4>Procedure to Obtain WiiConnect24 Messages</H4>
<P>
The procedure for getting messages is simply an extension of the procedure described above for getting a list of messages.
</P>
<P>
After retrieving the list of message IDs for the box in question, call the <A href="NWC24GetMsgObj.html"><CODE>NWC24GetMsgObj()</CODE> function</A> and store meta information for the message having the specified ID in an <A href="../Types/NWC24MsgObj.html"><CODE>NWC24MsgObj</CODE> object</A>.
</P>
<P>
As described above, meta-information such as the sender ID, date, etc. can be retrieved at this point by using the <CODE>NWC24GetMsg*</CODE> functions without accessing actual message files.
</P>
<P>
Get variable length parts of the message, such as body text and attached files, using the <CODE>NWC24ReadMsg*</CODE> functions based on the <A href="../Types/NWC24MsgObj.html">NWC24MsgObj object</A>, that includes the meta-information that was retrieved. These functions actually access message files internally and read the data.
</P>

<H4>Procedure to Delete WiiConnect24 Messages</H4>
<P>
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).
</P>
<P>
Use the <A href="NWC24DeleteMsg.html"><CODE>NWC24DeleteMsg() </CODE>function</A> to delete messages by simply specifying the box in question and the message ID.
</P>
<P>
This function can be used to delete messages stored in the Outbox as well as those stored in the Inbox.
</P>
<P>
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.
</P>

<H2>Access Rights to WiiConnect24 Messages</H2>

<H4>Application ID and Group ID</H4>
<P>
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.
</P>
<P>
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 <code><A href="NWC24GetMsgAppId.html">NWC24GetMsgAppId</A></code> and <code><A href="NWC24GetMsgGroupId.html">NWC24GetMsgGroupId</A></code>.
</P>
<P>
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.
</P>
<P>
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.
</P>

<H4>Access Rights for Different Message Types</H4>
<P>
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 <A HREF="../MsgBoard/intro.html">NWC24API and Wii Message Board</A>In such cases, be sure to specify <A href="../Types/NWC24MsgType.html"><CODE>NWC24_MSGTYPE_WII_MENU</CODE></A> or <A href="../Types/NWC24MsgType.html"><CODE>NWC24_MSGTYPE_WII_MENU_SHARED</CODE></A> as the message type when performing initialization with <A href="NWC24InitMsgObj.html"><CODE>NWC24InitMsgObj()</CODE></A>.
</P>
<UL>
<LI>Messages specifying <A href="../Types/NWC24MsgType.html"><CODE>NWC24_MSGTYPE_WII_MENU</CODE></A> cannot be accessed from a standard application.</LI>
<LI>If <CODE>NWC24_MSGTYPE_WII_MENU_SHARED</CODE> is specified, the message is read-only.</LI>
<LI><A href="../Types/NWC24MsgType.html">NWC24_MSGTYPE_PUBLIC</A> is for messages that come from external e-mail addresses. These messages are also processed by the Wii Message Board, and applications can only read these messages.</LI>
</UL>
<P>
To exchange data between applications, create a &quot;for application&quot; message. In such cases, be sure to specify <A href="../Types/NWC24MsgType.html"><CODE>NWC24_MSGTYPE_WII_APP</CODE></A> as the message type when performing initialization with <A href="NWC24InitMsgObj.html"><CODE>NWC24InitMsgObj()</CODE></A>. In addition, when <A href="../Types/NWC24MsgType.html"><CODE>NWC24_MSGTYPE_WII_APP_HIDDEN</CODE></A> is specified, access from other applications is completely prohibited, allowing communication only within an application.
</P>

<H4>Keeping the content of messages secret</H4>
<P>
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.
</P>
<P>
If you want to implement stricter data security, specify <A href="../Types/NWC24MsgType.html"><CODE>NWC24_MSGTYPE_WII_APP_HIDDEN</CODE></A> and take additional measures, such as using the NET library to encrypt the data.
</P>

<H2>WiiConnect24 Message Size Restrictions</H2>
<P>
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.
</P>
<P>
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 <CODE>NWC24_BASE64_ENCODED_SIZE()</CODE>.
</P>

<H2>Certainty of Sending and Receiving WiiConnect24 Messages</H2>
<P>
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.
</P>
<P>
Furthermore, the sending of the message may fail due to such factors as:
</P>
<UL>
<LI>The server's message box is full.
<LI>The Wii console's Inbox is full.
</UL>
<P>
 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.
</P>
<P>
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.
</P>

<H2>Revision History</H2>
<P>
2007/11/27 Made revisions in conjunction with the present implementation.
<BR> 2007/10/15 Added text relevant to the certainty of sending and receiving messages. <BR> 2007/04/04 Added a section about the maximum number of messages to store.<BR>2007/03/15 Added a section about access rights.<BR>2007/01/30 Minor revisions.<BR>2007/01/12 Added a section about size restrictions.<BR>2006/12/08 Separated section out from the overall introduction.</P>

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