RVL DWC Function Reference Manual
(US Version)

Note: This document contains proprietary information. Please take strict measures to keep this information confidential.

Introduction
Configuration of RVL DWC
Method of Use
Precautions
About the Documentation
About the Sample Demo

Introduction

RVL DWC can be used for connecting to Nintendo Wi-Fi Connection, registering friends, accessing friend status, or connecting to another Wii or Nintendo DS with matching conditions.

RVL DWC Configuration

The RVL DWC Library allows formulaic processing of the following features:

Authentication using the Nintendo authentication server
A user management system that does not require the game user to be aware of the user name or password
A friend registration system that does not require the user to be aware of whether they are connected to the Internet
Creation of an automatic mesh connection without any awareness of the connection order for a large number of unspecified partners
Creation of an automatic mesh connection without any awareness of friend-exclusive connection order
Creation of a semi-automatic mesh connection with a friend-exclusive server-client method
General-purpose ranking
Download functionality (Wi-Fi Download Service)

Using the Library

To use the RVL DWC library, you must connect to the Nintendo Authentication Server and GameSpy server. Doing this requires an environment that can connect to the Internet.

The following environment variables must be set to build RVL DWC:

REVOLUTION_SDK_ROOT Revolution SDK root directory
REVOLUTION_EXT_ROOT Revo EX library root directory
CWFOLDER_RVL CodeWarrior for Revolution directory
LM_LICENSE_FILE CodeWarrior license file
RVLDWC_ROOT RVL DWC root directory

In addition, the following path must be added to the environment variable PATH:

PATH=%REVOLUTION_SDK_ROOT%\X86\bin;%CWFOLDER_RVL%\bin;%CYGWIN_PATH%\bin;%PATH%

To simplify these settings, shellrun.bat has been placed in the root directory. Running this batch file allows the startup of a shell for which environment variables have been set. Edit the contents as needed depending on the environment.

Notes

Maintenance information for each server:

Nintendo Authentication Server

This server authenticates the Nintendo Wi-Fi Connection ID that is set on the Wii console and issues information for connecting to the GameSpy server.

Two types of authentication servers are available: Use the development authentication server during development and debugging, and the product authentication server when creating the final ROM. Although both the development and the production authentication server are operating continuously, the development authentication server may go down because it does not have a redundant configuration. If the development authentication server goes down for any reason, the product authentication server may be used.

Refer to the following links to confirm the operation status of each authentication server. If "AuthServer is up" appears, the server is running.

Authentication Server for Production

Authentication Server for Development

IMPORTANT: By default, the authentication server for development is used. The authentication server is switched with the DWC_Init function. For more details, see the Function Reference.

GameSpy Server

The GameSpy server is down every Tuesday from 16:00 to 18:00 Japan time (UTC/GMT +9). Sometimes that maintenance work is not completed by 18:00, and the downtime lasts a little longer.

Note that there is no distinction between the development and product servers for friend management and the matchmaking process. When testing matchmaking during the development of a remastered or localized version, matchmaking will sometimes occur with titles that have already been released even if you specify DWC_AUTHSERVER_DEBUG in the DWC_Init function.

To avoid this, use a matchmaking filter to prevent peer matchmaking with friend specified between the release and development (debugging) versions. (Refer to the DWC_AddMatchKeyString function for more on matchmaking filters.)

General-purpose ranking and data storage have two server versions -- one for development and one for production -- as is the case with the authentication server. These servers will be switched when the authentication server is switched.

Note: At this time, no method is available for checking the GameSpy server's operating state.
Note: The general-purpose ranking feature also uses the GameSpy server.

Comments

Once a user ID has been created on the authentication server, it cannot be changed or deleted.
A server for local debug use is not provided.

Documentation

The following programming-related documents are included in $(RVLDWC_ROOT)/docs.

Nintendo Wi-Fi Connection Revolution DWC Programming Manual

In addition, you can also obtain the latest version of documentation, such as Nintendo Wi-Fi Connection Programming Guidelines for Wii, which includes precautions on creating code, and other documentation included in this package from the Nintendo Support Page.

About the Sample Demos

Function samples for use as reference during implementation are stored in $(RVLDWC_ROOT)/build/demos. The objective of each sample demo is explained below.

cfriend	Sample of the console friend link feature.
datastorage	Reads and writes data to/from the data storage server.
download	Sample of the download feature.
frienddata	Used for handling friend information.
match_anybody	Shows the creation of an automatic mesh connection without any awareness of the connection order for a large number of unspecified partners.
match_friends	Shows the creation of an automatic mesh connection without any awareness of friend-exclusive connection order.
match_lan	Performs matchmaking within the LAN for testing purposes.
match_menu	Implements a menu that can be used to test each type of matchmaking.
match_serverclient	Shows the creation of a semi-automatic mesh connection with a friend-exclusive server-client method.
naslogin	A sample of a login to the authentication server.
ranking	A sample of the general-purpose ranking feature.
userdata	Used for handling user data.
prof	Sample of an illegal string check.
template	Demo template.

Revision History

2.0.1: DWC_AddMatchKeyInt: Added information related to unusable key names.; DWC_AddMatchKeyString: Added information related to unusable key names.; DWC_RequestSuspendMatchAsync: Mentioned that the acceptance status will change after all hosts have called this function.; DWCErrorType: Removed a description related to calling the SOFinish function.
2.0.0: DWCSvlResult: Added Notes about the current operation of status and svlhost.; DWC_GetLastError: Specifications have changed so that SOFinish does not need to be called when a DWC_ETYPE_DISCONNECT error has been generated.; DWC_GetFriendStatus: Changed the return value specification.; DWC_GetFriendStatusSC: Changed the return value specification.; DWC_GetFriendStatusData: Changed the return value specification.; DWC_GetFriendStatusDataSC: Changed the return value specification.; DWC_ConnectToAnybodyAsync: Changed the return value specification.; DWC_ConnectToFriendsAsync: Changed the return value specification.; DWC_SetupGameServer: Changed the return value specification.; DWC_ConnectToGameServerAsync: Changed the return value specification.; DWC_ConnectToGameServerByGroupID: Initial addition.; DWC_GetNumConnectionHost: Added an explanation of the states in which this function can be used.; DWC_GetMyAID: Added an explanation of the states in which this function can be used.; DWC_GetAIDList: Added an explanation of the states in which this function can be used.; DWC_GetAIDBitmap: Added an explanation of the states in which this function can be used.; DWC_GetServerAID: Initial addition.; DWC_IsServerMyself: Initial addition.; DWC_GetDirectConnectedAIDBitmap: Initial addition.; DWCMatchedSCCallback: Made revisions in line with changes to the specifications used by all matchmaking types.; DWCNewClientCallback: Made revisions in line with changes to the specifications used by all matchmaking types.; DWCConnectAttemptCallback: Initial addition.; DWCSuspendCallback: Initial addition.; DWC_CancelMatch: Added a note directing to use this function only when the local host has not yet connected to anyone else.; DWC_CancelMatch: Removed the description of DWCMatchedCallback.; DWC_GetGroupID: Initial addition.; DWC_RequestSuspendMatchAsync: Initial addition.; DWC_GetSuspendMatch: Initial addition.; DWC_GetConnectionUserData: Initial addition.; DWC_SetDebugMeshNNRetryMax: Initial addition.; DWC_GetDebugMeshNNRetryMax: Initial addition.; DWCUserSendCallback: Specification change.; DWCUserRecvCallback: Specification change.; DWCUserRecvTimeoutCallback: Specification change.; DWCUserPingCallback: Specification change.; DWC_SetUserSendCallback: Specification change.; DWC_SetUserRecvCallback: Specification change.; DWC_SetUserRecvTimeoutCallback: Specification change.; DWC_SetUserPingCallback: Specification change.; DWC_SetConnectionKeepAliveTime: Initial addition.; DWC_GetConnectionKeepAliveTime: Initial addition.
1.4.21: DWC_GetLastError: Added a note about the fact that it is necessary to call DWC_Shutdown when DWC_ETYPE_DISCONNECT has been generated.; DWC_AddMatchKeyInt: Made it explicit that the key ID specified is fixed at 0 when getting a new key ID.; DWC_AddMatchKeyString: Made it explicit that the key ID specified is fixed at 0 when getting a new key ID.
1.4.20: DWC_CheckUserData: Added a precaution about the DWC_ClearDirtyFlag function.; DWC_ClearDirtyFlag: Mentioned that the CRC value included in user data will be recalculated.; DWCEvalPlayerCallback: Noted that it takes some time for the addition of a condition key to be propagated to the server.; DWC_AddMatchKeyInt: Corrected a typo in the maximum number of keys that can be used by the application.; DWC_AddMatchKeyInt: Corrected a typo in the key ID specified when a new key ID is obtained.; DWC_AddMatchKeyInt: Added a caution that identical key names cannot be used.; DWC_AddMatchKeyString: Noted that empty strings cannot be specified.; DWC_AddMatchKeyString: Corrected a typo in the maximum number of keys that can be used by the application.; DWC_AddMatchKeyString: Corrected a typo in the key ID specified when a new key ID is obtained.; DWC_AddMatchKeyString: Added a caution that identical key names cannot be used.; DWC_GetMatchIntValue: Noted that it takes some time for the addition of a condition key to be propagated to the server.; DWC_GetMatchStringValue: Noted that it takes some time for the addition of a condition key to be propagated to the server.; DWC_GetMatchStringValue: Noted that empty strings cannot be specified.; DWC_SendReliable: Added a precaution about the timing of send buffer rewrites.; DWC_SendReliableBitmap: Added a precaution about the timing of send buffer rewrites.
1.4.17: DWCErrorType: Added a note on calling the SOCleanup and SOFinish functions.
1.4.16: DWC_TestInternetConnection: Added a description related to timeouts.; DWC_GetLastError: Corrected a Nitro DWC description that was present.; DWC_ConnectToGameServerAsync: Added a note stating that DWCMatchedSCCallback may not always be called.
1.4.15: DWC_CreateFriendKey: Added a precaution to reflect modifications to the creation algorithm.; DWC_CreateFriendKeyLegacy: Initial version.; DWC_CheckFriendKey: Added a precaution to reflect modifications to the creation algorithm.; DWC_CheckFriendKeyLegacy: Initial version.; DWC_GetLastError: Following the removal of direct access to DWC_GHTTP, deleted the description of DWC_ShutdownGHTTP. Corrected an omission in download-related error codes. Added DWC_ECODE_TYPE_TRANS_SEND.; DWC_Shutdown: Following the removal of direct access to DWC_GHTTP, deleted the description of DWC_ShutdownGHTTP.; DWCNdCallback: Initial version.; DWC_NdInitAsync: Added callback to the arguments.; DWC_NdProcess: Added a description of the callback.; DWC_RnkInitialize: Following the removal of direct access to DWC_GHTTP, deleted the description of DWC_ShutdownGHTTP.; DWC_SvlInit: Added a note about submitting the Nintendo Wi-Fi Connection Original Server Application Form, and added a description of the procedure for using SVL.; DWC_SvlCleanup: Added a note about submitting the Nintendo Wi-Fi Connection Original Server Application Form.; DWC_SvlGetTokenAsync: Added a note about submitting the Nintendo Wi-Fi Connection Original Server Application Form.; DWC_SvlProcess: Added a note about submitting the Nintendo Wi-Fi Connection Original Server Application Form.; DWC_SvlAbort: Added a note about submitting the Nintendo Wi-Fi Connection Original Server Application Form.; DWC_SetRecvBuffer: Described invalidating the other party's buffer at disconnection.; DWCErrorType: Following the removal of direct access to DWC_GHTTP, deleted the description of DWC_ShutdownGHTTP.; DWCNdError: Initial version.; DWCNdCallbackReason: Initial version.
1.4.14: DWCRnkRegion: Added China (DWC_RNK_REGION_CH).
1.4.12: DWC_CfGetConsoleInfo: Added a description of function usage.; DWC_TestInternetConnection: Initial version.; DWC_LoadOwnPublicDataAsync: Added information specific to implementation of canceling.; DWC_LoadOwnPrivateDataAsync: Added information specific to implementation of canceling.; DWC_LoadOthersDataAsync: Added information specific to implementation of canceling.; DWC_GetLastError: Added a detailed error code description.; DWC_Init: Added a gamecode example.; DWC_LoginAsync: Added information specific to conflicts in NHTTP.; DWC_SetupGameServer: Added a description of DS wireless communications.; DWC_NasLoginAsync: Added information specific to conflicts in NHTTP.; DWC_NdInitAsync: Added information specific to conflicts in NHTTP.; DWC_NdCancelAsync: Revised error code descriptions.; DWC_CheckProfanityAsync: Added information specific to conflicts in NHTTP.; DWC_CheckProfanityExAsync : Added information specific to conflicts in NHTTP.; DWC_SvlInit: Added information specific to conflicts in NHTTP.; DWCTestInetResult: Initial version.; DWCReportFlag: Added DWC_REPORTFLAG_OPTION_CONNTEST.
1.4.11: DWC_RnkProcess: Added the timeout time.
1.4.10: tagDWCCfInfo: Added.; DWC_CfGetConsoleInfo: Added.; DWC_Init: Moved the process for creating the DNS cache to the DWC_LoginAsync function so that now this function can be called without being connected to the network.; DWCLanMatchedCallback: Noted that this cannot be used with the retail product.; DWCRecvLanMatchCallback: Noted that this cannot be used with the retail product.; DWCSendLanMatchCallback: Noted that this cannot be used with the retail product.; DWC_InitLanMatch: Noted that this cannot be used with the retail product.; DWC_SetRecvLanMatchCallback: Noted that this cannot be used with the retail product.; DWC_SetSendLanMatchCallback: Noted that this cannot be used with the retail product.; DWC_ProcessLanMatch: Noted that this cannot be used with the retail product.; DWC_SendLanMatch: Noted that this cannot be used with the retail product.; DWC_StartLanMatch: Noted that this cannot be used with the retail product.; DWC_ShutdownLanMatch: Noted that this cannot be used with the retail product.; DWC_GetMyAIDLanMatch: Noted that this cannot be used with the retail product.; DWC_GetConnectNumLanMatch: Noted that this cannot be used with the retail product.; DWC_LoginAsync: Added a section concerning the details of connecting to the network and a section concerning the creation of a DNS cache.; DWC_ConnectToAnybodyAsync: Added a section concerning the details of connecting to the network.; DWC_ConnectToFriendsAsync: Added a section concerning the details of connecting to the network.; DWC_SetupGameServer: Added a section concerning the details of connecting to the network.; DWC_ConnectToGameServerAsync: Added a section concerning the details of connecting to the network.; DWC_NasLoginAsync: Added a section concerning the details of connecting to the network.; DWC_RnkInitialize: Added text about the user data's dirty flag.; DWC_RnkProcess: Introduced timeouts.; DWCCfError: Added DWC_CF_ERROR_GETINFO.; DWCRnkError: Added DWC_RNK_PROCESS_TIMEOUT.; DWCRnkState: Added DWC_RNK_STATE_TIMEOUT.
1.4.8: DWC_RnkGetScoreAsync: Corrected text, changing the score is higher/lower than one's own to the ranking is higher/lower than one's own, and deleted the text Lists starting with data closest to your own score from Nearby Rankings.; DWCRnkGetMode: Changed ranking is above/below to ranking is higher/lower.
1.4.7: DWC_CanChangeFriendList: Added a description related to timeouts.; DWC_NdInitAsync: Described the uses of this function.; DWC_NdProcess: Described the uses of this function.; DWC_NdCleanupAsync: Described the uses of this function.; DWC_NdSetAttr: Described the uses of this function.; DWC_NdGetFileListNumAsync: Described the uses of this function.; DWC_NdGetFileListAsync: Described the uses of this function.; DWC_NdGetFileAsync: Described the uses of this function.; DWC_NdCancelAsync: Described the uses of this function.; DWC_NdGetProgress: Described the uses of this function.
1.4.6: DWC_CheckProfanityAsync: Made a correction by changing When 0 is specified to When 0 or below is specified.
1.4.5: DWCRnkGetParam: Added mention of DWC_RNK_GET_MODE_NEAR_*.; DWC_CreateExchangeToken: Initial version.; DWC_CreateFriendKeyToken: Described validation of friend registration keys.; DWC_IsValidAID: Added a description of behavior when one's own AID is specified.; DWC_RnkGetScoreAsync: Added DWC_RNK_GET_MODE_HI. Added DWC_RNK_GET_MODE_LOW.; DWCRnkGetMode: Added DWC_RNK_GET_MODE_NEAR_HI and DWC_RNK_GET_MODE_NEAR_LOW.
1.4.1: DWC_GetFriendKey: Added a precaution for getting data from friends with whom friend relationships have been established.; DWC_ReportFriendData: Corrected the text "Output with OS_TPrintf".; DWC_ReportUserData: Corrected the text "Output with OS_TPrintf".; DWC_CfSetAppFriendKeyToNWC24Msg: Corrected the description of the return values.; DWC_CfGetAppFriendKeyFromNWC24Msg: Corrected the description of the return values.; DWC_CfReset: Corrected the description of the return values.; DWC_Init: Added a description on disconnecting from the network.; DWC_InitFriendsMatch: Deleted the description of DWC_CreateExchangeToken.; DWC_CheckProfanityAsync: Initial version.; DWC_CheckProfanityProcess: Initial version.; DWC_SvlGetTokenAsync: Added a description of the "svc" parameter.; DWCProfState: Initial version.
1.4.0: DWC_IsCompatibleUserData: Initial version.; DWC_CfSetAppFriendKeyToNWC24Msg: Initial version.; DWC_CfGetAppFriendKeyFromNWC24Msg: Initial version.; DWC_CfReset: Initial version.; DWCStorageLoginCallback: Added text concerning the DWC_LogoutFromStorageServer function.; DWCSaveToServerCallback: Added text concerning the DWC_LogoutFromStorageServer function.; DWCLoadFromServerCallback: Added text concerning the DWC_LogoutFromStorageServer function.; DWC_Init: Added a section concerning the details of connecting to the network.; DWCCfError: Initial version.; DWCCfMsgType: Initial version.; DWCError: Added omitted explanations of the ND and SVL errors.; DWCErrorType: Added the choice to Return to Wii Menu when a fatal error occurs.; DWCRnkRegion: Added South Korea (DWC_RNK_REGION_KR).
1.3.2: DWC_Init: Changed to return -1 if it fails to create a DNS cache.; DWC_SetupGameServer: Corrected a typo, changing "DS wireless connection" to "DS wireless communication".; DWC_SetReportLevel: Removed the statement "only for debugging".; DWCReportFlag: Added DWC_REPORTFLAG_NONE.
1.3.0: DWCRnkGetParam_order: Corrected an error by changing second to minute.; DWCRnkGetParam_toplist: Corrected an error by changing second to minute.; DWCRnkGetParam_nearby: Corrected an error by changing second to minute.; DWCRnkGetParam_friends: Corrected an error by changing second to minute.; DWC_InitLanMatch: Removed the first argument.; DWC_InitFriendsMatch: Changed so that the first argument is ignored.; DWC_GetIngamesnCheckResult: Corrected a typo by changing "DWC_INGAMESN_NOTCHECKED" to "DWC_INGAMESN_NOT_CHECKED".
1.2.1: DWC_GetFriendStatus: Deleted precautions about execution speed.; DWC_GetFriendStatusSC: Deleted precautions about execution speed.; DWC_GetFriendStatusData: Deleted precautions about execution speed.; DWC_GetFriendStatusDataSC: Deleted precautions about execution speed.; DWC_ReallocEx: Changed so that newly released memory will not be initialized.
1.1.2: DWC_GetGsProfileId: Removed the statement "Use only for debugging".; DWC_Init: Changed so that the data storage server connection target can be changed.; DWC_InitFriendsMatch: Changed the DWCFriendsMatchControl definition from a structure to a pointer variable. Corrected a DWC_SetMemFunc-related error.; DWC_RnkResGetRow: Added an explanation of the conditions in which ranking is stored to the order field.
1.1.0: DWC_Init: Added a note that thread-exclusive control of the memory allocation and deallocation functions is required.; DWCMatchedSCCallback: Fixed a broken table.; DWCAllocEx: Made a note about thread-exclusive processing.; DWCFreeEx: Made a note about thread-exclusive processing.
1.0.0: DWC_CreateUserData: Removed gamecode from the arguments.; DWC_Init: Added a description related to NWC24 and changed specifications so that gamecode is now passed as an argument.; DWC_SetReportLevel: DWC_REPORTFLAG_ALL is now specified by default.
0.2.0: DWC_InitLanMatch: Deleted a typo regarding DWC_SetMemFunc, and replaced it with DWC_Init.
0.0.8: DWC_Init: Changed specifications so gamename is passed as an argument.
Changed specifications so an allocator is passed as an argument.
0.0.5: DWCLanMatchedCallback: Changed the type to DWCError.; DWCSendLanMatchCallback: Changed the argument order.; DWC_SendLanMatch: Fixed a bug asserted when the AID is zero.
0.0.3: DWC_SetReportLevel: Added a description related to the DWCReportFlag enumerator.; DWC_Printf: Changed the argument type from u32 to the DWCReportFlag enumerated type.

RVL DWC Function Reference Manual (US Version)

Table of Contents