11. System Settings

This chapter describes how applications can get settings, such as user information and sound settings, from the system settings.

11.1. Initialization

Use the CFG library to access information handled by System Settings or about the 3DS system itself.

You must call the nn::cfg::Initialize function to initialize the CFG library before you can use its functionality, with the exception of a few functions not bound by this restriction. After initialization, CFG library functions can be called up until finalization occurs.

Code 11-1. Initializing the CFG Library
void nn::cfg::Initialize(void); 

11.2. Getting Information

After initializing the library, call the provided functions to access various kinds of information.

11.2.1. User Name

You can get the user name configured in the system settings.

Code 11-2. Getting the User Name
void nn::cfg::GetUserName(nn::cfg::UserName* pUserName);

struct nn::cfg::UserName
{
    wchar_t userName[CFG_USER_NAME_LENGTH];
    bool isNgUserName;
    NN_PADDING1;
}; 

For the pUserName parameter, specify a pointer to an nn::cfg::UserName structure for storing the user name.

The user name is stored as a wide character string in the userName member of the nn::cfg::UserName structure, and true is stored in the isNgUserName member if the user’s name includes any words that fail a profanity check.

In the Japan region, the profanity check uses Japanese, in the North American region it uses American English and the System Settings language, and in Europe it uses British English and the System Settings language.

11.2.2. Birthday

You can get the user’s birthday configured in the system settings.

Code 11-3. Getting the User’s Birthday
void nn::cfg::GetBirthday(nn::cfg::Birthday* pBirthday);

struct nn::cfg::Birthday
{
    s8  month;
    s8  day;
}; 

For the pBirthday parameter, specify a pointer to an nn::cfg:Birthday structure for storing the birthday.

11.2.3. Country Code

You can get the country code for the user’s country and region of residence configured in the system settings.

Code 11-4. Getting the Country Code
nn::cfg::CfgCountryCode nn::cfg::GetCountry(void); 

For more information about the country codes defined in the system, see the nn/cfg/CTR/cfg_CountryCode.h header file.

Use the following function to make conversions between country codes and country name codes (ISO 3166-1 alpha-2 format).

Code 11-5. Converting Between Country Codes and Country Name Codes
nn::Result nn::cfg::ConvertCountryCodeToIso3166a2(
    char* iso3166a2, nn::cfg::CfgCountryCode countryCode);
nn::Result nn::cfg::ConvertIso3166a2ToCountryCode(
    nn::cfg::CfgCountryCode* pCountryCode, const char* iso3166a2); 
Note:

The nn::cfg::GetCountryCodeA2 function will be removed from CTR-SDK.

Warning:

Applications that use the function for converting between country codes and country name codes must be sure to handle the nn::cfg::ResultNotFound return value if it is returned.

11.2.4. Language Code

You can get the language code for the language used for display configured in the system settings.

Code 11-6. Getting the Language Code
nn::cfg::CfgLanguageCode nn::cfg::GetLanguage(void); 

The following table shows the language codes defined in the system.

Table 11-1. Language Codes

Values

Language

Language Name (ISO 639-1 alpha-2)

CFG_LANGUAGE_JAPANESE

Japanese

ja

CFG_LANGUAGE_ENGLISH

English

en

CFG_LANGUAGE_FRENCH

French

fr

CFG_LANGUAGE_GERMAN

German

de

CFG_LANGUAGE_ITALIAN

Italian

it

CFG_LANGUAGE_SPANISH

Spanish

es

CFG_LANGUAGE_SIMP_CHINESE

Chinese (Simplified)

zh

CFG_LANGUAGE_KOREAN

Korean

ko

CFG_LANGUAGE_DUTCH

Dutch

nl

CFG_LANGUAGE_PORTUGUESE

Portuguese

pt

CFG_LANGUAGE_RUSSIAN

Russian

ru

CFG_LANGUAGE_TRAD_CHINESE

Chinese (Traditional)

zh

Use the following function to covert the obtained language code to a language name in ISO 639-1 alpha-2 format.

Code 11-7. Converting From Language Code to Language Name
const char* nn::cfg::GetLanguageCodeA2(CfgLanguageCode cfgLanguageCode); 

The function returns NULL if there is no string corresponding to the language code specified in the cfgLanguageCode parameter.

Note:

This function can be called without initialization occurring beforehand.

11.2.5. Simple Address Information

You can get the user’s simple address information (country, region, latitude, longitude) configured in System Settings.

Code 11-8. Getting Simple Address Information
void nn::cfg::GetSimpleAddress(nn::cfg::SimpleAddress* pSimpleAddress);

struct nn::cfg::SimpleAddress
{
    u32 id;
    wchar_t countryName[CFG_SIMPLE_ADDRESS_NUM_LANGUAGES]
                       [CFG_SIMPLE_ADDRESS_NAME_LENGTH];
    wchar_t regionName[CFG_SIMPLE_ADDRESS_NUM_LANGUAGES]
                      [CFG_SIMPLE_ADDRESS_NAME_LENGTH];
    u16 latitude;
    u16 longitude;
}; 

For the pSimpleAddress parameter, specify a pointer to an nn::cfg::SimpleAddress structure for storing the simple address information.

The countryName and regionName members of the nn::cfg::SimpleAddress structure store the country name and region name as wide-character strings, and the latitude and longitude members store the latitude and longitude.

The latitude and longitude member values are displayed in increments of 360° ÷ 65546 (approximately 0.005°). Northern latitudes from 0° through 90° are stored as values from 0x0000 through 0x4000, southern latitudes from 0.005° through 90° as values from 0xFFFF through 0xC000, eastern longitudes from 0° through 179.995° as values from 0x0000 through 0x7FFF, and western longitudes from 0.005° through 180° as values from 0xFFFF through 0x8000.

11.2.5.1. Simple Address Information ID

The following function gets only the simple address information ID.

Code 11-9. Getting Simple Address Information ID
void nn::cfg::GetSimpleAddressId(nn::cfg::SimpleAddressId* pSimpleAddressId);

struct nn::cfg::SimpleAddressId
{
    u32 id;

    nn::cfg::CfgCountryCode GetCountryCode(void) const;
    u8 GetRegionCode(void) const;
}; 

For the pSimpleAddressId parameter, specify a pointer to an nn::cfg::SimpleAddressId structure.

The nn::cfg::SimpleAddressId structure has a GetCountryCode member function to get the country code and a GetRegionCode member function to get the region code. For the values available from these respective member functions, see 11.2.3. Country Code.

11.2.5.2. Getting the Simple Address Information From the ID

The simple address information can be obtained from the simple address information ID

Code 11-10. Getting Simple Address Information From the ID
nn::Result nn::cfg::GetSimpleAddress(nn::cfg::SimpleAddress* pSimpleAddress, 
                                     nn::cfg::SimpleAddressId simpleAddressId, 
                                     uptr pWorkMemory, u32 workMemorySize); 

The simple address information obtained based on the ID specified in simpleAddressId is stored in pSimpleAddress.

Working memory is needed for operation of this function. A memory region at least as large as nn::cfg::CFG_SIMPLE_ADDRESS_WORKMEMORY_SIZE must be reserved and the memory location and size specified in pWorkMemory and workMemorySize respectively.

11.2.5.3. Converting Simple Address Information IDs Between 3DS and Wii U

Use the following function to convert simple address information IDs between 3DS and Wii U.

Code 11-11. Converting Simple Address IDs Between 3DS and Wii U
nn::cfg::SimpleAddressId nn::cfg::ConvertToWiiUSimpleAddressId(
    nn::cfg::SimpleAddressId ctrSimpleAddressId);
nn::cfg::SimpleAddressId nn::cfg::ConvertToCtrSimpleAddressId(
    nn::cfg::SimpleAddressId wiiUSimpleAddressId); 

11.2.6. Region Codes

Note:

The region codes here are those set in the 3DS system at the time of shipment. Region codes set in Game Cards are specified in a BSF file, and applications will not run if the system and card region codes do not match or if the card does not have a set region code. For more information about BSF files, see the reference manual for the CTR-SDK tool ctr_makebanner.

You can get the region code for the system’s target market.

Code 11-12. Getting the Region Code
nn::cfg::CfgRegionCode nn::cfg::GetResion(void); 

The following table shows the region codes defined in the system.

Table 11-2. Region Codes

Values

Target Market

3-Letter Code

CFG_REGION_JAPAN

Japan

JPN

CFG_REGION_AMERICA

Americas

USA

CFG_REGION_EUROPE

Europe and Australia

EUR

CFG_REGION_CHINA

China

CHN

CFG_REGION_KOREA

South Korea

KOR

CFG_REGION_TAIWAN

Taiwan

TWN

Use the following function to covert the obtained region code to a three-letter string.

Code 11-13. Converting From Region Code to 3-Letter String
const char* nn::cfg::GetRegionCodeA3(CfgRegionCode cfgRegionCode); 

The function returns NULL if there is no string corresponding to the language code specified in the cfgRegionCode parameter.

11.2.7. Sound Output Mode

You can get the sound output mode configured in System Settings.

Code 11-14. Getting the Sound Output Mode
nn::cfg::CfgSoundOutputMode nn::cfg::GetSoundOutputMode(void); 

The following table shows the sound output modes defined in the system.

Table 11-3. Sound Output Modes

Values

Sound Output Mode

CFG_SOUND_OUTPUT_MODE_MONO

Monaural

CFG_SOUND_OUTPUT_MODE_STEREO

Stereo

CFG_SOUND_OUTPUT_MODE_SURROUND

3D Surround Sound

11.2.8. RTC Modification Offset Value

You can get the offset value saved to the hardware as the cumulative total of user changes to the RTC time.

Code 11-15. Getting the RTC Modification Offset Value
nn::fnd::TimeSpan nn::cfg::GetUserTimeOffset(void); 

The function returns the modification offset in seconds. This is the cumulative total of the absolute values of all user changes made to the clock with the system settings. For more information about how to handle these values, see 8.5.3. Handling Time Modification Offset Values.

11.2.9. Parental Controls

An application must check whether restrictions are enabled in Parental Controls before photographs and images can be exchanged or friends added. Call nn::cfg::IsParentalControlEnabled to check whether the parental controls are enabled.

Code 11-16. Checking Whether Parental Controls Are Enabled
bool nn::cfg::IsParentalControlEnabled(void); 
Table 11-4. Parental Controls Settings and Restricted Functionality

Item

Restricted Application Functionality

Section

Age Restriction

N/A (restricted to the system side)

-

Use of Internet Browser

N/A (restricted to the system side)

-

Using Nintendo e-Shopping to Purchase Merchandise and Services

Purchasing Content Using ECDK

11.2.9.6

3D Image Display

N/A (restricted to the system side)

-

Use of Miiverse

Posting to Miiverse and Viewing Miiverse

11.2.9.7

Sending and Receiving Photos, Images, Voice Recordings, Videos, or Text

Sending and Receiving Rich UGC

11.2.9.2

Uploading Rich UGC (North America)

11.2.12

Internet Communication With Other Users

Data Exchange With Other Users

11.2.9.4

StreetPass Communication With Other Users

Using StreetPass

11.2.9.5

Friend Registration

Friend Registration Within the Application

11.2.9.3

Use of DS Download Play

N/A

-

Viewing Distributed Videos

Viewing videos obtained by communication

11.2.9.8

11.2.9.1. Temporarily Suspending Parental Controls by Entering a PIN

When Parental Controls are in force, applications can temporarily suspend Parental Controls by having the user input a PIN. Parental Controls are then suspended if the entered PIN matches the PIN in the Parental Controls settings. Note that neither the PIN entered by the user nor the PIN in the Parental Controls settings are ever displayed on the screen.

You can compare to the PIN in the Parental Controls settings by calling the nn::cfg::CheckParentalControlPinCode function.

Code 11-17. Comparing to the Parental Controls PIN
bool nn::cfg::CheckParentalControlPinCode(const char *input); 

This function returns true if the string passed to input matches the PIN (four single-byte digits).

The software keyboard applet includes a mode for temporarily suspending Parental Controls. When started in this mode, the software keyboard applet operates according to a specialized sequence. The application can then determine whether to suspend Parental Controls based on the return value from the applet.

11.2.9.2. Restrictions on the Transmission of Data That May Include Personal Information

Call the nn::cfg::IsRestrictPhotoExchange function to check whether photo exchanges (Sending and Receiving Photos, Images, Voice Recordings, Videos, or Text) are restricted. If restricted, and so long as Parental Controls are not temporarily suspended, the application cannot exchange photos or other images with any other system. This restriction includes not only the sending and receiving of photos, but also screen images, voice recordings, videos, and text; or any data that could include private information.

Code 11-18. Confirmation of Restrictions on the Transmission of Data That May Include Personal Information
bool nn::cfg::IsRestrictPhotoExchange(void); 

Be careful, as true is returned when the restriction is active.

11.2.9.3. Restrictions on Adding Friends

Call the nn::cfg::IsRestrictAddFriend function to check whether adding friends is restricted by the Parental Controls settings. If restricted, friend registration from within an application will end in an error. In principle, the application is not permitted to temporarily cancel this restriction.

Code 11-19. Checking Whether Adding Friends Is Restricted
bool nn::cfg::IsRestrictAddFriend(void); 

Be careful, as true is returned when the restriction is active.

11.2.9.4. Restrictions on Internet Communication With Other Users

The nn::cfg::IsRestrictP2pInternet function can be used to confirm whether exchanging data or online play with other players through Internet communication has been restricted by Parental Controls. If restriction on Internet communication has been enabled, Internet communication must not be performed for the purpose of downloading user-created content or engaging in online play with other players unless the restriction is temporarily lifted.

Code 11-20. Confirmation of Restrictions of Internet Communication With Other Users
bool nn::cfg::IsRestrictP2pInternet(void); 

Be careful, as true is returned when the restriction is active.

11.2.9.5. Restrictions on Communication via StreetPass

The nn::cfg::IsRestrictP2pCec function can be used to confirm whether exchanging data with other players through StreetPass has been restricted by Parental Controls. If restriction on communication through StreetPass has been enabled, StreetPass does not work at all, and an error will occur if an attempt is made to register StreetPass data. The application cannot temporarily cancel this restriction.

Code 11-21. Checking Restrictions on Communication via StreetPass
bool nn::cfg::IsRestrictP2pCec(void); 

Be careful, as true is returned when the restriction is active.

11.2.9.6. Restrictions on Nintendo 3DS Shopping Services

You can use the nn::cfg::IsRestrictShopUse function to determine whether Nintendo 3DS Shopping Services have been restricted by Parental Controls. When they have been restricted, applications cannot add to their balance, purchase content, or take other similar actions unless the restriction is temporarily revoked.

Code 11-22. Checking Restrictions on Nintendo 3DS Shopping Services
bool nn::cfg::IsRestrictShopUse(void); 

Be careful, as true is returned when the restriction is active.

11.2.9.7. Miiverse Restrictions

Nintendo provides a function to check whether viewing or posting to Miiverse is restricted in Parental Controls. Call nn::cfg::IsRestrictMiiverseBrowse to check whether viewing Miiverse is restricted. Call nn::cfg::IsRestrictMiiversePost to check whether posting to Miiverse is restricted.

The device Parental Controls configuration values correspond to the function's return values are described below.

Table11-2. Relationship Between Miiverse Restrictions Configuration and Return Values

Restriction Name in Device Configuration

IsRestrictMiiverseBrowse

IsRestrictMiiversePost

"Restrict Posting and Browsing"

true

true

"Posting only"

false

true

"Do Not Restrict"

false

false

The application cannot get Miiverse posts from other users, or post to Miiverse unless these restrictions are temporarily lifted.

11.2.9.8. Restriction of Video Content Acquired Through Communication

Call nn::cfg::IsRestrictWatchVideo to check whether Parental Controls is restricting viewing of video content acquired through communication. An application may not play back video acquired through communication when this restriction is active, unless the restriction is temporarily lifted.

Code 11-23. Check for Restriction of Video Content Acquired Through Communication
bool nn::cfg::IsRestrictWatchVideo(void); 

Be careful, as true is returned when the restriction is active.

11.2.10. Checking for EULA Acceptance

Users must first accept the terms of the End-User Licensing Agreement (EULA) before the application can use the Nintendo 3DS Network Service, which includes Nintendo Network and StreetPass. Call the nn::cfg::IsAgreedEula function to check whether the user has accepted the EULA terms. If they have not, the application must not use these networking features.

Code 11-24. Checking for EULA Acceptance
bool nn::cfg::IsAgreedEula(void); 

The function returns true if the user has accepted the terms of the EULA. The FS library must be initialized before calling this function.

For more information about which features require EULA acceptance, see the Guidelines.

11.2.11. System-Specific ID

You can get the system-specific ID used to identify the system.

Code 11-25. Getting the System-Specific ID
bit64 nn::cfg::GetTransferableId(bit32 uniqueId); 

For the uniqueId parameter, specify the unique 20-bit ID assigned to the application.

The system-specific ID is a 64-bit value that is guaranteed to be unique to a certain degree. This ID is also transferable in cases such as when a new replacement system has been bought. However, this ID cannot be recovered if the system was lost, stolen, or broken. The system–specific ID is changed when the user runs format system memory, and the original ID cannot thereafter be recovered.

Possible uses of this system ID include the following.

  • Ensuring that initial values of application parameters are different for each system.
  • Creating data accessible only from one specific system.
  • The identifier or its seed for use in local communication.

 

Note:

When save data is created, the system-specific ID is saved, and subsequently the use of that saved system-specific ID in the save data can support changes such as those resulting from repairs. In addition, upon saving, a 128-bit value that matches the current time is saved, which can prevent the same data from being saved to multiple cards.

If you are using the ID to create data accessible only from that system, note that this data will be inaccessible if the system is formatted with format system memory, lost, or stolen.

11.2.12. Restrictions Based on COPPACS

The COPPA Compliance System (COPPACS) is a system provided by Nintendo to enable applications created for North America (if the system region is North America, and the country setting is U.S. or Canada) to comply with the Children’s Online Privacy Protection Act (COPPA).

Note:

For a list of applications subject to COPPACS, see the UGC section of the guidelines. Plans are to provide details about COPPACS in the future in the System Application and Applet Specifications.

You can determine whether restrictions based on COPPACS are in effect.

Code 11-26. Getting Restrictions Based on COPPACS
bool nn::cfg::IsCoppacsSupported();
nn::cfg::CfgCoppacsRestriction nn::cfg::GetCoppacsRestriction(void); 

You can confirm the support method for COPPACS by calling the nn::cfg::GetCoppacsRestriction function.

When CFG_COPPACS_RESTRICTION_NONE is returned, no restrictions are in effect, so COPPACS support is unnecessary.

When CFG_COPPACS_RESTRICTION_NEED_PARENTAL_PIN_CODE or CFG_COPPACS_RESTRICTION_NEED_PARENTAL_AUTHENTICATION is returned, restrictions are in effect, so COPPACS support must be provided.

The former can be released by entering the parental control authentication number. Enter and check the authentication number within the application. If the correct authentication number is entered, a temporary suspension can be performed (see 11.2.9.1. Temporarily Suspending Parental Controls by Entering a PIN). The latter cannot be released from within the application. The COPPACS authentication procedure within the system settings must be used.

Note that you must temporarily exit the application when performing the authentication procedure for this setting. You can confirm the setting by restarting the application when returning to the application from System Settings. When continuing a process which was being performed before jumping to System Settings, always reconfirm the support method for COPPACS. In some cases, when reconfirming, you may be asked to perform the authentication procedure within System Settings.

To simply confirm which countries are subject to COPPACS with the current System Settings, you can use the nn::cfg::IsCoppacsSupported function. Note that if the system setting is for one of the countries on the list, the value true is returned even if COPPACS restrictions have not been enabled.

Note:

A description of how to jump to the COPPACS authentication procedure screen (PARENTAL_CONTROLS_COPPACS) is provided in 5.3.7. Jump to System Settings. For implementation examples, see the sample demo (coppacs in cfg).

11.3. Finalizing

Call the nn::cfg::Finalize function when done using the CFG library.

Code 11-27. Finalizing the CFG Library
void nn::cfg::Finalize(void); 

If this function is called before initialization, nothing will happen.

The number of times the library’s initialization function has been called is recorded. Until the finalize function is called the same number of times, the library remains in use.


CONFIDENTIAL