TWL DWC Function Reference Manual
(English Version)

Supports TWL-DWC-DL 5.6

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

Microsoft Internet Explorer 7.0 or Mozilla Firefox 3.0 or later versions are recommended.

Revision History

Function Reference Change Log (See Changelog.txt in this package for the library change logs.)

Table of Contents

Introduction

With TWL DWC, you can connect to the Internet using the wireless communications feature of the Nintendo DS system (infrastructure mode), register friends, access the status of friends, and connect with other Nintendo DS systems that meet the right conditions.

Note: TWL DWC-DL contains only the TWL DWC features that do not use the GameSpy library internally. Titles that can be developed with TWL DWC-DL must always use TWL DWC-DL instead of TWL DWC.

Notes

Structure of TWL DWC and TWL DWC-DL

TWL DWC is a set of resources and tools collected to enable standardized processing for the following features.

Of these features, only the following can be used with TWL DWC-DL.

Using the Tool

Notes

Transitioning from NITRO DWC

Matchmaking features in TWL DWC are not compatible with NITRO DWC implementations. Generally speaking, the following features have been added as compared to NITRO DWC.

For details, see Nintendo_WiFi_Connection_TWL-DWC_ProgrammingManual.pdf and the Function Reference Manual included in this package.

Note that specifications have changed for some TWL DWC download features since these features were implemented in NITRO DWC. For details, see Nintendo_WiFi_Connection_TWL-DWC_ProgrammingManual_Download.pdf and the Function Reference Manual included in this package.

There must be a link to libdwcnonport.*.a, the library newly added to TWL DWC.

Server Information

●Nintendo Server for Connection Tests

This server is intended to check if the Nintendo DS system is currently in an environment where it can connect to the Internet. It runs nonstop.

See the following link to confirm the operation status of each server. If the message "This is test.html page" appears, the server is running.

Test Connection Server  
● Nintendo Authentication Server

This server authenticates the user ID (Nintendo Wi-Fi Connection ID) that is set in the Nintendo DS system, and issues information for connecting to the GameSpy server.
This server is also used to check for illegal strings.

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. Use either the DWC_InitForDevelopment or DWC_InitForProduction function to select an authentication server. If a DWC library version with the prefix DEBUG is displayed in DS_MRC or the TWL MasterEditor, there is the possibility of connecting to a development server; be careful because you cannot submit this as the final ROM.

See 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
● GameSpy Server

This server is used for matchmaking, general-purpose ranking, data storage, and managing friends.
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 for managing friends, matchmaking, and data storage, no distinction is made between the development and production servers.There is a possibility, therefore, of matchmaking with titles already sold on the market when testing matchmaking during development of the remastered or localized version (even if the DWC_InitForDevelopment function is used to set the development authentication server).

To avoid this, it is necessary to use the conditions that can be specified when using friend-unspecified peer matchmaking and defining which players to search as matchmaking candidates. Use these conditions to make a distinction between acceptable matchmaking targets and players using production versions or debug/development versions of titles, so that production versions and debug/development versions are not included in matchmaking.

However, for general-purpose ranking, there are two versions of the server (one for development and one for retail products), as is the case with the authentication server. When the authentication server is switched, the general-purpose ranking server will also switch.

Note: Currently, there is no way to verify the operational status of the GameSpy servers.

● Nintendo Download Server

This server is used for Wi-Fi Download Service. For details, see the Nintendo Wi-Fi Connection TWL DWC Programming Manual: Download Edition.

As with the authentication server, there are two versions of the Nintendo download server: one for development and one for production. Switching between the servers matches the switching between authentication servers.

Note: Currently, there is no method available for checking the operating state of the download server.

● Comments

Licenses

About WEP Keys

Note: The Nintendo DSi system supports WPA. This can be specified in the high-level settings for connection target settings 4 through 6.

Documentation

The $TWLDWC_ROOT/docs directory contains the following programming-related documents.

To get Nintendo Wi-Fi Connection Programming Guidelines for DS (which describes cautions to be used in development) or the latest versions of the documents included in this package, visit the Nintendo Support Page.

Icon Image Data

The $TWLDWC_ROOT/data/Wi-Fi_icons directory contains the bitmap and NITRO-CHARACTER data for icons that show Wi-Fi signal strength and support for Nintendo Wi-Fi Connection. These icons are used by titles that support Nintendo Wi-Fi Connection.
For the use of the individual icons, see the Nintendo Wi-Fi Connection Programming Guidelines.

About the Sample Demos

The $TWLDWC_ROOT/build/demos directory contains sample demos to use as implementation references.
Keep the following in mind.

The objective of each sample demo is explained below.

Sample Name Overview TWL DWC TWL DWC-DL
dwc_sample This sample comprehensively uses TWL DWC features.
dwc_connect_inet_sample This is a simple sample of connecting to the Internet and checking the connection.
dwc_userdata_sample This sample handles user data.
dwc_frienddata_sample This sample handles friend information.
dwc_anybody_match_sample This sample automatically creates hybrid (star/mesh combination) connections for large numbers of unspecified participants, without regard for the connection order.
dwc_friend_match_sample This sample automatically creates hybrid (star/mesh combination) connections that are limited to friends, without regard for the connection order.
dwc_sc_match_sample This sample semi-automatically creates hybrid (star/mesh combination) connections that are limited to friends, using the server-client model.
dwc_eval_callback_sample This sample evaluates matchmaking candidate players during peer matchmaking.
rank_sample A sample of the general-purpose ranking feature.
dwc_naslogin_sample This is the Nintendo authentication server login sample.
dwc_nd_sample This sample demonstrates the download features (the Wi-Fi download service).
dwc_prof_sample This sample demonstrates the illegal string check.
dwc_svl_sample This sample gets Service Locator information.

Revision History

This is the function reference change log.
Note: Some of the minor terminology revisions may not be reflected in the revision histories.
For changes to libraries, see Changelog.txt in this package.

5.4
DWC_ConnectInetAsync: Added mention that this function should not be called when PXI interrupts are prohibited.
DWC_DebugConnectInetAsync: Added mention that this function should not be called when PXI interrupts are prohibited.
DWC_InitForDevelopment: Added description of the allocated work memory.
DWC_InitForProduction: Added description of the allocated work memory.

5.3 patch 3
DWC_CheckProfanityAsync: Added information for registered illegal strings

5.3 Patch 1
DWC_CheckProfanityAsync: Fixed the result that indicated illegal characters in the example where A is specified for all regions.

5.3
DWC_InitInetEx: Deleted Description because the DWC_SetAuthServer function has been deprecated.
DWC_InitForDevelopment: The specification was changed and the initialization function has been separated into two functions: One for development and one for production. Also updated to require specification of game name, game code, and allocator.
DWC_InitForProduction: The specification was changed and the initialization function has been separated into two functions: One for development and one for production. Also updated to require specification of game name, game code, and allocator.
DWC_Debug_DWCInitError: Added support for separation of the DWC_Init function into versions for development and production servers.
DWCAllocEx: The Note for operating in TWL mode was moved here from the deprecated DWC_SetMemFunc function.
DWC_Alloc: Revised the Description because the specification was changed to set the allocator using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetMemFunc function.
DWC_AllocEx: Revised the Description because the specification was changed to set the allocator using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetMemFunc function.
DWC_Free: Revised the Description because the specification was changed to set the allocator using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetMemFunc function.
DWC_Realloc: Revised the Description because the specification was changed to set the allocator using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetMemFunc function.
DWC_ReallocEx: Revised the Description because the specification was changed to set the allocator using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetMemFunc function.
DWC_NdInitAsync: The specification was changed to switch the authentication server using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetAuthServer function.
DWC_SVLGetTokenAsync: Revised the Description because the specification was changed to set the allocator using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetMemFunc function.
DWC_StartUtility: The specification was changed to switch the authentication server using either the DWC_InitForDevelopment or DWC_InitForProduction function, and not the DWC_SetAuthServer function.

5.3 PR1
DWC_Alloc:Revised the return value and the explanation of the existence of the header for internal management.
DWC_AllocEx:Revised the return value and the explanation of the existence of the header for internal management.
DWC_Realloc:Revised an explanation of the return value relating to the existence of the header for internal management.
DWC_ReallocExRevised an explanation of the return value relating to the existence of the header for internal management.

5.2
DWC_GetLastErrorEx: Removed invalid links.
DWC_SetReportLevel: Described possibility of delays occurring in the game, depending on the type of debug print.
DWCReportFlag: Explained the flags for outputting debugging information.

5.2 PR1
DWC_GetLastErrorEx: Removed asterisks that had no meaning.
DWCInetAuthType: Fixed the descriptions of DWC_CONNECTINET_AUTH_DEVELOP and DWC_CONNECTINET_AUTH_RELEASE because they had errors.

5.1 Patch 1
DWC_CheckProfanityAsync: Added support for testing with multi-region illegal strings.

5.1
DWCApInfo: Added that Wayports (North American hotspots) cannot currently be used.
DWC_SetRwinSize: Added that this is enabled only in TWL mode. Added mention of the relationship with MTU.
DWC_ConnectInetAsync: Changed "while connected..." to "during the autoconnect process..."
DWC_DebugConnectInetAsync: Changed "while connected..." to "during the autoconnect process..."
DWC_ProcessInet: Changed "while connected..." to "during the autoconnect process..."
DWC_GetLastErrorEx: Added that Wayports (North American hotspots) cannot currently be used.
DWC_InitForDevelopment: Revised the list of functions that must be called before using the DWC_Init function to include only the OS_Init function.
DWC_InitForProduction: Revised the list of functions that must be called before using the DWC_Init function to include only the OS_Init function.
DWC_CheckProfanityAsync: Added illegal strings for testing for the North American and European regions.
DWCApInfoType: Added that Wayports (North American hotspots) cannot currently be used.

5.1 PR2
DWCApInfo: Corrected incorrect values used in the description of the security and area members of the structure.
DWC_DebugConnectInetAsync: Revised the descriptions of the wep and wepmode arguments.
DWC_GetLastError: Added DWC_ERROR_NETWORK_LIGHT to the description of return values.
DWC_GetLastErrorEx: Added DWC_ERROR_NETWORK_LIGHT to the description of return values and added a description of the DS Network Error Code List.
DWC_NASLoginProcess: Added a description of the return values when the process completes or is aborted.
DWC_NdGetFileListNumAsync: Added a description of the necessity of a timeout process.
DWC_NdGetFileListAsync: Added a description of the necessity of a timeout process.
DWC_NdGetFileAsync: Deleted mention of "a minimum of 128 bytes" from the description of the size argument. Added an explanation of the necessity of a timeout process.
DWC_CheckProfanityProcess: Added a description of the return values when the process completes.
DWC_SVLProcess: Corrected a mistake in the definition name of a return value and added a description of the return values when the process completes or is aborted.


For the change log before version 5.1 PR2, click here.  


TWL-06-0153-001-F
CONFIDENTIAL