NWC24 Friend Roster API

Introduction

Each Wii console has a Wii Friend Roster to store your friends' IDs (Wii numbers) or e-mail addresses used for exchanging WiiConnect24 messages.
The Wii Friend Roster has the following characteristics:

The NWC24 library provides the function to access this Wii Friend Roster that is shared by the applications.

Wii Friend Roster Format

Each entry stored in the Wii Friend Roster consists of the following elements: 

typedef struct NWC24FriendAttr
{
    u32     type;
    u32     status;
    u16     name[12];
    u64     fdId;
    u32     reserved[6];
} NWC24FriendAttr;

typedef union NWC24FriendAddr
{
    NWC24UserId     wiiId;
    char            mailAddr[256];
} NWC24FriendAddr;

typedef struct NWC24FriendInfo
{
    NWC24FriendAttr     attr;
    NWC24FriendAddr     addr;
} NWC24FriendInfo;

NWC24FriendAttr Structure:

Stores the attributes (status, nickname, and so on) of the registered friend.

type Indicates the type of the registered address.
Value Description
NWC24_FI_TYPE_WIIWii number.
NWC24_FI_TYPE_PUBLICGeneral e-mail address.
status Indicates whether it is possible to communicate with the registered address (whether the friend relationship has been established).
Value Description
NWC24_FI_STAT_PENDINGRelationship is not yet established.
NWC24_FI_STAT_ESTABLISHEDRelationship is established.
NWC24_FI_STAT_DECLINEDRelationship was not established.
name Indicates the nickname locally given to the registered address by the user.
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 List of Characters that can be Input in the Address Book.
fdId If 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 RFLCreateID using RFLFaceLibrary. (For further details, see the function reference for RFLFaceLibrary.)
reserved Reserved region

NWC24FriendAddr Union:

Maintains different information according to the type of address registered.

wiiId This is used when the Wii number is specified with NWC24_FI_TYPE_WII. The Wii number is expressed as a 16-digit decimal number and maintained in 64-bit format.
addr This is used when a general e-mail address is specified with NWC24_FI_TYPE_PUBLIC. Address strings of up to 256 characters can be maintained (Including the 0x00 terminator.)
Note: The Address Book in the Wii menu actually holds only 99 characters.

NWC24FriendInfo Structure:

This is a combination of the NWC24FriendAttr structure and the NWC24FriendAddr union, so it is one set of registration information.

Establishing Friend Relationships

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

When 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 attr.status element of the NWC24FriendInfo 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).

Note: Do not send Wii messages to parties with whom a friendship relationship has not been established.

Wii Friend Roster Access Functions

The following functions have been prepared as an API for accessing the Wii Friend Roster:

For details, see the reference manual for each function.

User Operations for Registering Entries on the Wii Friend Roster

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

Accordingly, the application does not need to provide a sequence for registering Wii numbers and e-mail addresses to the console friend roster.(Note: 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.)

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

Revision History

2007/11/22 Added link to List of Characters that can be Input in the Address Book
2007/04/04 Added a warning note and corrected details.
2007/03/15 Added a warning note.
2007/02/14 Added an explanation of fdId
2006/09/16 Made revisions to match change in structure definitions
2006/09/01 Initial version.

CONFIDENTIAL