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 FriendList API Introduction</TITLE>
7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
8</HEAD>
9<BODY>
10<H1>NWC24 Friend Roster API</H1>
11
12<H2>Introduction</H2>
13<P>
14Each Wii console has a Wii Friend Roster to store your friends' IDs (Wii numbers) or e-mail addresses used for exchanging WiiConnect24 messages.<BR>The Wii Friend Roster has the following characteristics:
15</P>
16<P>
17  <UL>
18<LI>Accessible from each application
19<LI>A maximum of 100 Wii numbers or e-mail addresses can be registered
20<LI>In principle, the Wii console does not accept messages from senders who are not registered there
21  </UL>
22</P>
23<P>
24The NWC24 library provides the function to access this Wii Friend Roster that is shared by the applications.
25</P>
26
27<H2>Wii Friend Roster Format</H2>
28<P>
29Each entry stored in the Wii Friend Roster consists of the following elements:
30</P>
31<TABLE border="1" width="80%">
32  <TBODY>
33    <TR>
34      <TD width="100%">
35      <PRE><CODE>typedef struct NWC24FriendAttr
36{
37    u32     type;
38    u32     status;
39    u16     name[12];
40    u64     fdId;
41    u32     reserved[6];
42} NWC24FriendAttr;
43
44typedef union NWC24FriendAddr
45{
46    NWC24UserId     wiiId;
47    char            mailAddr[256];
48} NWC24FriendAddr;
49
50typedef struct NWC24FriendInfo
51{
52    NWC24FriendAttr     attr;
53    NWC24FriendAddr     addr;
54} NWC24FriendInfo;</CODE></PRE>
55      </TD>
56    </TR>
57  </TBODY>
58</TABLE>
59
60<P>
61<H4>NWC24FriendAttr Structure:</H4>
62Stores the attributes (status, nickname, and so on) of the registered friend.
63</P>
64<TABLE border="1" cellpadding="3" cellspacing="0.1">
65  <TR>
66<TD width="120" bgcolor="#ffffe8"><code><em><strong>type</strong></em></code></TD>
67    <TD width="520">
68Indicates the type of the registered address.<BR>
69      <TABLE width="500" border="1" cellspacing="0.1">
70          <TR>
71<TD width="150" bgcolor="#C0C0C0">Value</TD>
72<TD width="350" bgcolor="#C0C0C0">Description</TD>
73          </TR>
74          <TR>
75<TD>NWC24_FI_TYPE_WII</TD><TD>Wii number.</TD>
76          </TR>
77          <TR>
78<TD>NWC24_FI_TYPE_PUBLIC</TD><TD>General e-mail address.</TD>
79          </TR>
80      </TABLE>
81    </TD>
82  </TR>
83  <TR>
84<TD width="120" bgcolor="#ffffe8"><code><em><strong>status</strong></em></code></TD>
85    <TD width="520">
86Indicates whether it is possible to communicate with the registered address (whether the friend relationship has been established).<BR>
87      <TABLE width="500" border="1" cellspacing="0.1">
88          <TR>
89<TD width="150" bgcolor="#C0C0C0">Value</TD>
90<TD width="350" bgcolor="#C0C0C0">Description</TD>
91          </TR>
92          <TR>
93<TD>NWC24_FI_STAT_PENDING</TD><TD>Relationship is not yet established.</TD>
94          </TR>
95          <TR>
96<TD>NWC24_FI_STAT_ESTABLISHED</TD><TD>Relationship is established.</TD>
97          </TR>
98          <TR>
99<TD>NWC24_FI_STAT_DECLINED</TD><TD>Relationship was not established.</TD>
100          </TR>
101      </TABLE>
102    </TD>
103  </TR>
104  <TR>
105<TD width="120" bgcolor="#ffffe8"><code><em><strong>name</strong></em></code></TD>
106    <TD width="520">
107Indicates the nickname locally given to the registered address by the user.<BR>The character code is expressed in UTF-16BE format. Although the number of elements in the array is set to 12, the character limit is 10. The remainder must be padded with zeroes. For more on characters that can be used here, see the <A HREF="nickname_char_list.html">List of Characters that can be Input in the Address Book</A>.
108    </TD>
109  </TR>
110  <TR>
111<TD width="120" bgcolor="#ffffe8"><code><em><strong>fdId</strong></em></code></TD>
112    <TD width="520">
113If a Mii is set when registering an address in the system address book, that ID will be stored for searching. In order to get the data for such Miis, perform a search of this 64-bit value as <code>RFLCreateID</code> using RFLFaceLibrary. (For further details, see the function reference for RFLFaceLibrary.)
114    </TD>
115  </TR>
116  <TR>
117<TD width="120" bgcolor="#ffffe8"><code><em><strong>reserved</strong></em></code></TD>
118    <TD width="520">
119Reserved region
120    </TD>
121  </TR>
122</TABLE>
123
124<P>
125<H4>NWC24FriendAddr Union:</H4>
126Maintains different information according to the type of address registered.
127</P>
128<TABLE border="1" cellpadding="3" cellspacing="0.1">
129  <TR>
130<TD width="120" bgcolor="#ffffe8"><CODE><STRONG><EM>wiiId</EM></STRONG></CODE></TD>
131<TD width="520">This is used when the Wii number is specified with <CODE>NWC24_FI_TYPE_WII</CODE>. The Wii number is expressed as a 16-digit decimal number and maintained in 64-bit format.</TD>
132  </TR>
133  <TR>
134<TD width="120" bgcolor="#ffffe8"><CODE><STRONG><EM>addr</EM></STRONG></CODE></TD>
135<TD width="520">This is used when a general e-mail address is specified with <CODE>NWC24_FI_TYPE_PUBLIC</CODE>. Address strings of up to 256 characters can be maintained (Including the 0x00 terminator.)<BR> <B>Note: </B>The Address Book in the Wii menu actually holds only 99 characters.</TD>
136  </TR>
137</TABLE>
138
139<P>
140<H4>NWC24FriendInfo Structure:</H4>
141This is a combination of the <CODE>NWC24FriendAttr</CODE> structure and the <CODE>NWC24FriendAddr</CODE> union, so it is one set of registration information.
142</P>
143
144<H2>Establishing Friend Relationships</H2>
145<P>
146To allow users to safely communicate with WiiConnect24, in principle, exchanging messages with unknown or unfamiliar users is not permitted. All messages from Wii consoles not registered in the console friend list or messages from outside mail addresses are blocked.<BR>This means that when you want to communicate between Wii consoles, messages do not arrive unless both parties have registered each other on their respective Wii Friend Roster.
147</P>
148<P>
149When registering a new party on the console friend roster, the WiiConnect24 system automatically sends a message to verify where a friendship relationship has been established between the two parties. The result is stored in the <CODE>attr.status</CODE> element of the <CODE>NWC24FriendInfo</CODE> structure. The user or application can reference this information to determine whether communication is possible or not possible (that is, there is high probability of the message not being received even if sent).
150</P>
151<P>
152<B>Note: </B>Do not send Wii messages to parties with whom a friendship relationship has not been established.
153</P>
154
155<H2>Wii Friend Roster Access Functions</H2>
156<P>
157The following functions have been prepared as an API for accessing the Wii Friend Roster:
158</P>
159<P>
160  <UL>
161<LI><A HREF="NWC24ReadFriendInfo.html">NWC24ReadFriendInfo</A>: Gets an entry in the list
162<LI><A HREF="NWC24WriteFriendInfo.html">NWC24WriteFriendInfo</A>: Registers an entry in the list
163<LI><A HREF="NWC24UpdateFriendInfo.html">NWC24UpdateFriendInfo</A>: Updates the attributes of an entry in the list
164<LI><A HREF="NWC24DeleteFriendInfo.html">NWC24DeleteFriendInfo</A>: Deletes an entry in the list
165<LI><A HREF="NWC24SearchFriendInfoById.html">NWC24SearchFriendInfoById</A>: Searches for an entry in the list (Wii number)
166<LI><A HREF="NWC24SearchFriendInfoByAddr.html">NWC24SearchFriendInfoByAddr</A>: Searches for an entry in the list (e-mail address)
167<LI><A HREF="NWC24IsFriendInfoThere.html">NWC24IsFriendInfoThere</A>: Checks whether an entry is registered at the specified location in the list
168<LI><A HREF="NWC24GetNumFriendInfos.html">NWC24GetNumFriendInfos</A>: Gets the maximum number of entries that can be registered in the list
169<LI><A HREF="NWC24GetNumRegFriendInfos.html">NWC24GetNumRegFriendInfos</A>: Gets the number of entries registered in the list
170<LI><A HREF="NWC24GetNumEstFriendInfos.html">NWC24GetNumEstFriendInfos</A>: Gets the number of registered entries in the list for which friendship relationships have been established
171<LI><A HREF="NWC24CheckFriendInfo.html">NWC24CheckFriendInfo</A>: Confirms the validity of Friend information
172  </UL>
173</P>
174<P>
175For details, see the reference manual for each function.
176</P>
177
178<H2>User Operations for Registering Entries on the Wii Friend Roster</H2>
179<P>
180Among the Wii console menu items is a Wii Message Board feature that provides an easy way of checking the information exchanged using WiiConnect24. As part of this framework, a feature to edit the console friend roster has been provided in an Address Book format. Users will primarily use this to register Wii numbers and e-mail addresses.
181</P>
182<P>
183Accordingly, the application does not need to provide a sequence for registering Wii numbers and e-mail addresses to the console friend roster.(<B>Note:</B> Although the NWC24 library has functions for adding and deleting items to the console friend roster, please do not incorporate these in the production versions of your applications unless there is a special reason for doing so.)
184</P>
185<P>
186Also be aware that the information stored in the console friend roster in the form of an Address Book is not necessarily always stored in order starting from the 0th index.
187</P>
188
189<H2>Revision History</H2>
190<P>
1912007/11/22 Added link to List of Characters that can be Input in the Address Book
192<BR> 2007/04/04 Added a warning note and corrected details.<BR>2007/03/15 Added a warning note.<BR>2007/02/14 Added an explanation of <CODE>fdId</CODE><BR>2006/09/16 Made revisions to match change in structure definitions<BR>2006/09/01 Initial version.</P>
193
194<hr><p>CONFIDENTIAL</p></body>
195</HTML>