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.
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.
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.
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.
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).
nn::Result nn::cfg::ConvertCountryCodeToIso3166a2( char* iso3166a2, nn::cfg::CfgCountryCode countryCode); nn::Result nn::cfg::ConvertIso3166a2ToCountryCode( nn::cfg::CfgCountryCode* pCountryCode, const char* iso3166a2);
The nn::cfg::GetCountryCodeA2()
function will be removed from CTR-SDK.
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.
nn::cfg::CfgLanguageCode nn::cfg::GetLanguage(void);
The following table shows the language codes defined in the system.
Values |
Language |
Language Name (ISO 639-1 alpha-2) |
---|---|---|
|
Japanese |
ja |
|
English |
en |
|
French |
fr |
|
German |
de |
|
Italian |
it |
|
Spanish |
es |
|
Chinese (Simplified) |
zh |
|
Korean |
ko |
|
Dutch |
nl |
|
Portuguese |
pt |
|
Russian |
ru |
|
Chinese (Traditional) |
zh |
Use the following function to covert the obtained language code to a language name in ISO 639-1 alpha-2 format.
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.
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.
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.
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
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.
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
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.
nn::cfg::CfgRegionCode nn::cfg::GetResion(void);
The following table shows the region codes defined in the system.
Values |
Target Market |
3-Letter Code |
---|---|---|
|
Japan |
JPN |
|
Americas |
USA |
|
Europe and Australia |
EUR |
|
China |
CHN |
|
South Korea |
KOR |
|
Taiwan |
TWN |
Use the following function to covert the obtained region code to a three-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.
nn::cfg::CfgSoundOutputMode nn::cfg::GetSoundOutputMode(void);
The following table shows the sound output modes defined in the system.
Values |
Sound Output Mode |
---|---|
|
Monaural |
|
Stereo |
|
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.
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.
bool nn::cfg::IsParentalControlEnabled(void);
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 |
|
3D Image Display |
N/A (restricted to the system side) |
- |
Use of Miiverse |
Posting to Miiverse and Viewing Miiverse |
|
Sending and Receiving Photos, Images, Voice Recordings, Videos, or Text |
Sending and Receiving Rich UGC |
|
Uploading Rich UGC (North America) |
||
Internet Communication With Other Users |
Data Exchange With Other Users |
|
StreetPass Communication With Other Users |
Using StreetPass |
|
Friend Registration |
Friend Registration Within the Application |
|
Use of DS Download Play |
N/A |
- |
Viewing Distributed Videos |
Viewing videos obtained by communication |
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.
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.
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.
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.
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.
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.
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.
Restriction Name in Device Configuration |
IsRestrictMiiverseBrowse |
IsRestrictMiiversePost |
---|---|---|
"Restrict Posting and Browsing" |
|
|
"Posting only" |
|
|
"Do Not Restrict" |
|
|
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.
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.
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.
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.
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).
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.
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.
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.
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.