DWC_StartUtility

Syntax

#include <dwc.h> 
int DWC_StartUtility(void *work,
                     int language,
                     int param);

Arguments

work Pointer to a 32-byte aligned DWC_UTILITY_WORK_SIZE byte buffer. Can be deleted after the function completes.
language Language of the Nintendo Wi-Fi Connection setup utility.
As a general rule, specify the same language being used for the application. However, depending on the market region specified by param, certain languages are not selectable. If the application is using a language that is not supported by this function (*), select the most suitable language from among those that the function supports.
  • DWC_LANGUAGE_JAPANESE // Japanese
  • DWC_LANGUAGE_ENGLISH // English
  • DWC_LANGUAGE_FRENCH // French
  • DWC_LANGUAGE_GERMAN // German
  • DWC_LANGUAGE_ITALIAN // Italian
  • DWC_LANGUAGE_SPANISH // Spanish
  • DWC_LANGUAGE_HANGUL // Korean*
param Market (region) and where in the Nintendo Wi-Fi Connection setup utility to start. Depending on the market, the Easy Wireless Start feature may or may not be enabled.
  • Starting from the top menu.Implementation is required.
    • DWC_UTILITY_TOP_MENU_FOR_USA // North American market
    • DWC_UTILITY_TOP_MENU_FOR_EUR // European market
    • DWC_UTILITY_TOP_MENU_FOR_JPN // Japanese market
    • DWC_UTILITY_TOP_MENU_COMMON //Common value for all markets other than those listed above

  • Starting from the selection of connection target. Implementation is optional.
    • DWC_UTILITY_SETTING_FOR_USA // North American market
    • DWC_UTILITY_SETTING_FOR_EUR // European market
    • DWC_UTILITY_SETTING_FOR_JPN // Japan market
    • DWC_UTILITY_SETTING_COMMON // Common value for all markets other than those listed above

Return Values

DWC_UTIL_RESULT_SUCCESS Function completes successfully.
DWC_UTIL_RESULT_FAILED Argument error.
DWC_UTIL_RESULT_ERROR_TWL Errors when run on TWL hardware.

Description

Starts the Nintendo Wi-Fi Connection setup utility.

The DWC_StartUtility function is available to provide outside buffers as needed, and the DWC_StartUtilityEx function is available to make use of the items stored in static.

The Wi-Fi Connection setup utility does not need to be implemented with builds that specify LIMITED for TWL_ARCHGEN (TWL-exclusive mode). Because Wi-Fi Connection settings can be made from System Settings when using TWL, have the user use those settings.

In builds where HYBRID is specified for TWL_ARCHGEN (NITRO/TWL dual compatibility mode), this function executes normally on a Nintendo DS or DS Lite system but always results in a DWC_UTIL_RESULT_ERROR_TWL error when executed on TWL hardware. When this DWC_UTIL_RESULT_ERROR_TWL error is returned, always be sure to display a message conforming to the Guidelines.

The Wi-Fi connection setup utility is a common interface used to provide the player with the following features:

When calling this function, be aware of the following.

Although you can use the param argument to specify where in the Nintendo Wi-Fi Connection setup to start from, the application must have a scene where players can open the utility from the Top Menu.
This is because players cannot use all of the Nintendo Wi-Fi Connection setup features if the utility starts from the selection of connection targets.
The option to start from the selection of connection targets does not need to be implemented. It is provided as a means, for example, for players to be guided directly to the connection target settings when an error occurs while connecting to the Internet.

Call this function after shutting down all processes.
The following are specific cautions for using this function.

In addition to TWL-DWC, the function internally calls various TWL-SDK, TWL-System, and TWL-WiFi libraries.
Because these libraries must be loaded into memory in advance before running Nintendo Wi-Fi Connection Setup, you need to be careful about using the libraries listed below as overlay modules. Also, be aware that this function may not operate correctly if these libraries have been customized.

For FINALROM versions, use the production authentication server regardless of the setting made with the DWC_InitForDevelopment and DWC_InitForProduction functions.

The Nintendo Wi-Fi Connection setup utility has been created to start with a white screen. For this reason, if the utility is called after the application displays a white screen, the transition will be natural.

After the function ends normally, be aware of the following (nothing is processed if it ends as a result of an argument error).

The Nintendo Wi-Fi Connection settings reference files on the DS card by using the TWL-SDK file system. Place $(TWLDWC_ROOT)/file/dwc/utility.bin in the dwc/ directory below the root directory. If the application does not use the file system, add the following code to the RomSpec section in the ROM spec file and call the FS_Init function from the application to enable file system use.

RomSpec
{
  ...
  #From here
  HostRoot  ./file/dwc   #File directory name on the PC
  Root  /dwc
  File  utility.bin
  #To here
}


Reference: Easy Wireless Start Availability (Depending on the Combination of Language and Market)

Language Destination Easy Wireless Start Comments
Japanese Japan Yes ---
Japanese Outside Japan ---Errors
Non-Japanese North America / Europe / Common None ---
Non-Japanese Japan ---Errors

Revision History

5.3
Revised Description because the specification was changed to switch the authentication server using either the DWC_InitForDevelopment or the DWC_InitForProduction functions, and not with the DWC_SetAuthServer function.

For the change log before 5.1 PR2, click here.   


CONFIDENTIAL