The following libraries have been provided to assist applications using wireless communication.
- Blocked-User List
- Profanity List
- Notifications
- Accounts
This chapter describes the programming procedures and information required to develop an application that uses these libraries.
5.1. Blocked-User List
The blocked-user list is a feature provided to prevent the wide spread of inappropriate user-generated content (UGC) over peer-to-peer (P2P) communication.
5.1.1. Overview
If UGC is being managed by a particular server, the administrator checks all instances of UGC that have been registered and deletes inappropriate UGC. However, because content is directly transmitted without going through a server when using P2P communication, there is no way to handle inappropriate UGC.
The blocked-user list is intended to prevent the spread of inappropriate UGC as much as possible, even when P2P communication is used.
Authors of inappropriate UGC are registered in a list on the system (the local blocked-user list) by the blocked-user list feature. Inappropriate UGC is restricted by preventing UGC from authors registered in the list from being displayed.
Users can perform the following operations on the local blocked-user list on the HOME Menu.
- Delete all registered UGC author information (lift the blocked-user list restrictions)
The blocked-user list is only used to register and access the IDs of UGC authors. Even if the system receives UGC that was created by an author on the blocked-user list, the content will not be deleted automatically. If you receive UGC that must comply with the blocked-user list, you must check whether the author ID is on the blocked-user list from within your application, and take appropriate measures (such as deleting the content). The application is also responsible for adding UGC author IDs to the blocked-user list.
The local blocked-user list is saved to the shared expanded save data region.
5.1.2. Initialization and Finalization
Use the UBL library to use the blocked-user list feature in an application. Initialize and finalize the UBL library using the nn::ubl::Initialize
and nn::ubl::Finalize()
functions.
void nn::ubl::Initialize(void); void nn::ubl::Finalize(void);
5.1.3. Local Blocked-User List
Each system saves a single local blocked-user list that lists authors of received UGC. Users know this list as the Blocked-User Settings.
The UGC author information of UGC that the user deems to be inappropriate is registered on the local blocked-user list. Call nn::ubl::Entry
to register entries on the local blocked-user list.
nn::Result nn::ubl::Entry(u64 id, nn::fnd::DateTime *dt);
Specify the UGC author ID to register on the local blocked-user list in id
. The function returns an error if the local author (the user of the local system) tries to register himself or herself.
The UGC author ID represents the ID of the author who created the UGC. This ID is used only for the blocked-user list. Each system has a unique 8-byte ID. Although it cannot be used to identify a particular system, the same ID is used even when UGC is created with a different application. If the application allows received UGC to be edited, the ID of the user doing the editing (the editor ID) is registered for edited UGC data rather than the ID of the user who first created that UGC (the original author ID).
For information about what the application must support, see the Blocked-User List section of the guidelines.
Specify the registration date and time in dt
. The date and time that the UGC author ID was registered on the blocked-user list as UGC author information is used to determine which information to delete if the local blocked-user list becomes full.
Up to 1000 instances of UGC author information can be registered. If the number of registered entries reaches the maximum value at time of registration, entries are automatically overwritten beginning from the earliest.
5.1.4. Blocked-User List Check
When receiving or displaying UGC targeted by the blocked-user list (see Blocked-User List in the guidelines), make sure to check whether the UGC author ID of that UGC is registered on the local blocked-user list.
You can use nn::ubl::IsExist
to check the UGC author ID.
bool nn::ubl::IsExist(u64 authorId, u32 titleId, u64 dataId);
Specify the UGC author ID to check in authorId
. If the received UGC can be edited, make sure to check both the original author ID and editor ID.
The arguments titleId
and dataId
will be used with an extended feature in the future. Currently, their use is unsupported and they are ignored if specified.
Make sure that UGC on the blocked-user list is either deleted by the application or not displayed by the application.
5.1.5. UGC Browse Mode
UGC browse mode is a mode (browsing window) that allows you to browse UGC content that may be displayed within an application. Applications that allow the creation of UGC must include a UGC browse mode.
In UGC browse mode, users can display the UGC of authors not yet registered on the local blocked-user list within the associated application. Implement this feature so that users can register browsed UGC that they determine to be inappropriate on their local blocked-user list.
5.1.6. Local Blocked-User List Registration Flow
The following figure represents an example of receiving data via StreetPass. It shows the execution flow when registering an author on the local blocked-user list.
- Assume that data including UGC created by User A (Data a) is received by User C from User B.
- User C looks at Data a inside an application and, deeming it inappropriate, selects Data a from UGC browse mode. The application then displays a message and checks whether the user is registered in the local blocked-user list. User A is registered in the local blocked-user list when Yes is selected.
"Place content author on blocked-user list? Yes. No." - Next, assume that the same Data a is received from User D.
- When using StreetPass, the system detects that User A, the creator of Data a, is registered in the local blocked-user list and deletes Data a the next time User C opens the corresponding application after Data a has been received. (See the Blocked-User List section in the guidelines.)
- After this, even if User A edits Data a to create Data a’, and this Data a’ is then received from User F, Data a’ will be deleted because the author ID of Data a’ is registered in the local blocked-user list.
5.2. Profanity List
Whenever UGC that contains text is received, check against the profanity list to determine whether the text contains any profanity. Run this check not only for content received via the Internet, but also when content is received via local communications such as StreetPass.
Run this check not only for content received via the Internet, but also when content is received via local communications such as StreetPass. When systems with different language settings are communicating, the profanity check may be run on only the sender or only the receiver or it may be run on both sides.
Nintendo provides the NGC library for the CTR-SDK to check for profanity. Unlike the DWC library prepared for the Wii system, this NGC library can check for profanity without the need for going through a server.
5.2.1. Initialization and Finalization
Use the nn::ngc::ProfanityFilter
class to check for profanity. You must initialize the FS library before using this class.
class nn::ngc::ProfanityFilter { ProfanityFilter(); ProfanityFilter(const nn::WithInitialize&); ProfanityFilter(uptr pWorkMemory); nn::Result Initialize(); nn::Result Initialize(uptr pWorkMemory); }
The working memory used for the profanity check must be allocated either by the library from a memory block, or by the application. The size required for working memory is nn::ngc::ProfanityFilter::
WORKMEMORY_SIZE
(65,536 bytes).
If an instance is generated in an argument by the nn::WithInitialize()
function, or if an instance is generated by a constructor without an argument, and the Initialize()
function is called without an argument, the working memory is allocated from a memory block. In either case, note that the use of memory blocks (the nn::os::MemoryBlock
class) must be enabled beforehand.
If an instance is generated by specifying the starting address of the working memory in pWorkMemory
, or if an instance is generated by a constructor without an argument and the Initialize()
function is called with an argument, the working memory must be allocated by the application. For this working memory, allocate a contiguous region that is least nn::ngc::ProfanityFilter::
WORKMEMORY_SIZE
(65,536 bytes) in size and has nn::ngc::ProfanityFilter::WORKMEMORY_ALIGNMENT
(4 bytes) alignment.
After the check is completed and the instance is no longer needed, call the Finalize()
function to finalize the process.
class nn::ngc::ProfanityFilter { nn::Result Finalize(); }
After finalization you can release the working memory. If the working memory was allocated from a memory block, it is released during the finalization process.
5.2.2. Checking for Profanity
The profanity check for illegal strings is conducted by the ProfanityFilter
class CheckProfanityWords
member function.
class nn::ngc::ProfanityFilter { nn::Result CheckProfanityWords( bit32* pCheckResults, const wchar_t** ppWords, size_t nWordCount); nn::Result CheckProfanityWords( bit32* pCheckResults, nn::ngc::ProfanityFilterPatternList nPatternCode, const wchar_t** ppWords, size_t nWordCount); nn::Result CheckProfanityWords( bit32* pCheckResults, bool bCommunicateWithOtherRegions, const wchar_t** ppWords, size_t nWordCount); }
Each overload is checked from the top in all regions, and all languages and pattern lists are specified and checked (for region and language combinations). Pattern lists are automatically determined and checked based on the appropriate regions of the system.
The arguments ppWords
and nWordCount
specify the string array to check and the number of strings in that array. Specify a string terminated with a UTF16-LE NULL
terminator. Multiple strings can be checked at the same time, and this is faster than checking them one at a time.
The results of the profanity determinations are stored in pCheckResults
. Specify a bit32
-type array of nWordCount
or more elements. Each determination is returned as a bit flag. If a bit flag is up (the bit is 1), the string has been judged to be profane based on one of the pattern lists. The bit in the pattern list corresponds to the value that is left-shifted by 1 bit in nn::ngc::ProfanityPatternList
. If no problems are found in any of the pattern lists, 0
is stored in pCheckResults
.
The pattern lists that are used for profanity checks are specified in nPatternCode
using the values defined in nn::ngc::ProfanityPatternList
. The following pattern lists are defined in nn::ngc::ProfanityPatternList
.
Definition |
Region |
Language |
---|---|---|
|
Japan |
Japanese |
|
Americas |
American English |
|
Americas |
French (Canadian) |
|
Americas |
Spanish (Latin America) |
|
Europe |
British English |
|
Europe |
French |
|
Europe |
German |
|
Europe |
Italian |
|
Europe |
Spanish |
|
Europe |
Dutch |
|
South Korea |
Korean |
|
China |
Chinese (Simplified) |
|
Europe |
Portuguese |
|
Europe |
Russian |
|
Americas |
Portuguese (Brazil) |
|
Taiwan |
Chinese (Traditional) |
|
Taiwan |
English (Taiwan) |
In the overload with the bCommunicateWithOtherRegions
parameter, the system region determines which pattern lists must be used for the profanity check. For this reason, you must initialize the CFG library if this overload is being called. If false
is specified for this parameter, the profanity check is conducted using only the pattern lists that match the system region. This parameter is not currently referenced, and the profanity check is conducted as if false
were specified.
The profanity check can sometimes block processing and take time to complete, so we recommend creating a separate thread for these checks.
5.2.3. Checking Numbers
The checking performed by the nn::ngc::ProfanityFilter
class determines whether a string includes the @ symbol, which may be used in the notation for an email address, but the checking cannot determine whether the string contains many numerals, such as might be the case for a telephone number.
To check for numerals contained in strings, call the nn::ngc::CountNumbers()
function. You do not need to initialize the nn::ngc::ProfanityFilter
class to call this function
int nn::ngc::CountNumbers(const wchar_t *pString);
The pString
parameter specifies the string to check. Specify a string terminated with a UTF16-LE NULL
terminator.
As the return value, the function returns the number of numerals in the string. If an error occurs, the function returns a negative value.
5.2.4. Text Check
The nn::ngc::ProfanityFilter
class MaskProfanityWordsInText()
function checks long strings (such as sentences) for profanity, and when a string thought to be problematic is found, it can be replaced with asterisks. For a profanity check on shorter strings, such as display names, use the CheckProfanityWords()
function.
class nn::ngc::ProfanityFilter { nn::Result MaskProfanityWordsInText( int* pProfanityWordCount, wchar_t* pText); nn::Result MaskProfanityWordsInText( int* pProfanityWordCount, nn::ngc::ProfanityFilterPatternList nPatternCode, wchar_t* pText); nn::Result MaskProfanityWordsInText( int* pProfanityWordCount, bool bCommunicateWithOtherRegions, wchar_t* pText); void SetMaskMode(bool bOverWrite); }
Each overload is checked from the top in all regions, and all languages and pattern lists are specified and checked (for region and language combinations). Pattern lists are automatically determined and checked based on the appropriate regions of the system.
The pointer to the text targeted for a check is passed to pText
. When a pointer to an int
-type variable that is not NULL
is passed to pProfanityWordCount
, the number of times the problem string appears in the text is returned.
For more information about specifying pattern lists using nPatternCode
and specifying bCommunicateWithOtherRegions
see the CheckProfanityWords()
function.
The profanity check can sometimes block processing and take time to complete, so we recommend creating a separate thread for these checks.
When problem strings are replaced with asterisks by the MaskProfanityWordsInText()
function at bOverWrite
with the SetMaskMode()
function, it also specifies whether to replace the string with the same number of characters (true
: default) or with only one character (false
). Note that when the string is replaced by the same number of characters, the new string displayed in a proportional font may extend beyond the original frame due to differences in character width between the original characters and the asterisks.
5.3. Notifications
Notifications is a feature of the HOME Menu that works like the Wii Message Board to show notifications from Nintendo and from applications. Notifications can be posted from the application.
5.3.1. Initialization and Finalization
To post notifications from the application you must use the NEWS library. Before posting notifications, use the nn::news::Initialize()
function to initialize the NEWS library. After you no longer need to post notifications, call the nn::news::Finalize()
function.
nn::Result nn::news::Initialize(); nn::Result nn::news::Finalize();
5.3.2. Posting Notifications
To post a notification, call the nn::news::PostNews()
function.
nn::Result nn::news::PostNews( const wchar_t* subject, const wchar_t* message, const u8* picture = NULL, size_t pictureSize = 0, u32 serialId = 0, u32 dataVersion = 0, u64 jumpParam = 0);
You must specify both the title (subject
) and the body (message
) for this post. Both strings must be terminated with a UTF16-LE NULL
terminator. Use the 0x000A
(LF) control character for line breaks.
When an image is attached to the notification, the picture
and pictureSize
parameters specify the image data and the image size.
The serialId
and dataVersion
parameters specify the notification's serial ID and data version number. At present, specify 0
.
The jumpParam
argument specifies the parameters when jumping from the notification list to the application. The application can call nn::news::IsFromNewsList
to detect when the notification list is activated, and can get the parameters specified at the jumpParam
argument.
The title, body, and image attachment specified by these parameters are copied to inside the function, so they can be released after posting has completed.
The following table provides specifications for the title, body, and image attachment. For more information, such as the restriction on the interval between postings, see the CTR Guidelines.
Item |
Specification |
---|---|
Title |
The character encoding is UTF16-LE. The total number of characters including the string terminator must be no greater than The length of characters that are displayed is equal to the length of 17 characters of the system fonts at maximum width (in Japan, European, U.S. regions: "%"; in other regions: Japanese hiragana characters, Chinese kanji characters, Hangul characters, and so on). If the maximum display length is exceeded, the character size is reduced by up to 80%. If it still exceeds the maximum display length, the excess portion is hidden. |
Body |
The character encoding is UTF16-LE. The total number of characters including the string terminator must be no greater than A number of characters equal in length to 18 characters of the internal font at maximum width is displayed in a single line. |
Attached images |
MPO format. 3D pictures are also possible. The size in bytes must be no greater than |
The following errors are returned if the characters specified for title or body exceed the specifications, or if the specified image for attachment is in an invalid format or exceeds the data size limit.
Return Value |
Cause of Error |
---|---|
|
The specified title has too many characters. |
|
The specified body has too many characters. |
|
The image attachment exceeds the limit size. |
|
The image data is in an unsupported format. |
5.3.3. Posting Notifications With URLs
A notification with a URL is a normal notification with a URL provided. When a URL is provided along with a notification and displayed in the notification list, a button is also displayed that allows you to open your Internet browser to the page with the specified URL.
nn::Result nn::news::PostNewsUrl( const wchar_t* subject, const wchar_t* message, const u8* url, u8* workBuf, const u8* picture = NULL, size_t pictureSize = 0, u32 serialId = 0, u32 dataVersion = 0, u64 jumpParam = 0); size_t nn::news::GetWorkBufferSizeForNewsUrl( const wchar_t* message, const u8* url);
You can specify parameters other than url
and workBuf
in the same way as for the nn:news::PostNews()
function.
For the url
parameter, specify the URL to be provided in UTF-8 encoding. The maximum URL length that can be provided including the NULL
terminator is nn::news::MESSAGE_URL_URL_SIZE
bytes. Because the URL name uses the same region where the main text is stored, use the following formula to calculate the number of characters allowed when a URL is provided.
nn::news::MESSAGE_LEN
- (Number of characters in the URL, including the NULL
terminator) / 2
The size of the allocated work buffer returned by the GetWorkBufferSizeForNewsUrl()
function is specified in workBuf
. If the main text and URL total a number of characters exceeding the allowable length, or if an illegal argument such as an illegal pointer is passed, 0
is returned.
5.4. Accounts
The account library (the ACT library) enables applications to use the 3DS platform’s account system features. For an overall picture of the account system, see the CTR Account System Developer’s Guide included in the CTR-SDK.
By using the ACT library, applications can access the Nintendo Network account information that is cached in the CTR system and perform authentication processes based on the registered information.
5.4.1. Initialization and Finalization
Use the nn::act::Initialize()
function to initialize the ACT library.
If you are using ACT library functions that involve Internet communications, such as for the network clock or the login applet, complete a connection to the Internet with the ACT library before you call those functions. When you initialize the ACT library, you must specify a buffer for communications for these functions that perform Internet communications.
For the ACT library functions that are currently public functions, you do not need to specify a buffer for communications.
The buffer you pass for communications must be allocated from outside of device memory. The starting address of the buffer must be aligned to nn::act::BUFFER_ALIGNMENT
(4,096 bytes), and the size of the buffer must be a multiple of nn::act::BUFFER_UNITSIZE
(4,096 bytes).
The nn::act::Initialize()
function can be called multiple times. However, for the communications buffer, the specified buffer is used when the ACT library has not been initialized, and it is not used when it has been initialized.
The number of calls to the nn::act::Initialize()
function is counted and recorded. Until you call the nn::act::Finalize()
function as many times as the nn::act::Initialize()
function, the ACT library is considered to be initialized.
5.4.2. Nintendo Network Account Information
The application can use the ACT library to use Nintendo Network account information.
Because most of the functions that get Nintendo Network account information return locally cached information, these functions do not perform communications when they execute.
The table shows the correspondence between library functions and the Nintendo Network information they get. For more information, see the API reference.
Information |
Function |
Comments |
---|---|---|
Network account |
|
Determines whether the system account is a network account. |
Account ID |
|
|
Principal ID |
|
The principal ID obtained by the ACT library is the ID that was issued by the account server when the Nintendo Network account was registered. Although the name is the same, the principal ID obtained by the FRIENDS library is the ID issued by the friend server and differs from the one obtained by the ACT library. Be careful not to confuse these two IDs, and make mistakes like passing the principal ID obtained by the ACT library to the functions of the FRIENDS library. |
Password |
― |
Cannot be obtained. |
Email address |
― |
Contact Nintendo if your plans require getting this information. |
Date of birth |
― |
Contact Nintendo if your plans require getting this information. |
Age |
|
Can only get information as to whether a user meets a specified age. For more information, see 5.4.2.1. Age Determination. |
Country of residence |
|
Returned in the ISO 3166-1 alpha-2 format. |
Region of residence |
|
|
Time zone |
|
Returns the time zone of the region of residence in the tz database format. |
Time offset |
|
Returns the difference between UTC time and the time in the region of residence, in seconds. This process takes daylight savings time into account, but depending on when the information was cached, the time difference might not be accurate. |
Gender |
― |
Contact Nintendo if your plans require getting this information. |
5.4.2.1. Age Determination
The nn::act::IsOverAge()
function determines whether the Nintendo Network account user is at least the age specified in the age
parameter.
Age is determined using the birth date registered in the Nintendo Network account and the network clock. If the CTR system account is not a Nintendo Network account, or if the network clock is not enabled, this function always returns false
. For more information about the network clock, see 5.4.3. Network Clock.
5.4.3. Network Clock
If the network clock is not enabled and the time is not corrected before you call functions that use the network clock, the processes of those functions will be based on the wrong time. Use the nn::act:: IsNetworkTimeValidated()
function to check whether the network clock is available, and if it is not, call the nn::act::InquireNetworkTime()
function.
Note that the nn::act::InquireNetworkTime()
function communicates with the account server and blocks execution of the application until its process is completed.
The network clock becomes available for use after this function communicating with the account server has ended execution normally.
5.4.4. Login Applet
The login applet communicates with the account server, working on behalf of the application to authenticate the account and get various service tokens and the like. Control does not return to the application until its series of processes have completed.
The login applet authenticates the account, and returns an error if the system account is not a Nintendo Network account. We recommend that you check the account by calling the nn::act::IsNetworkAccount()
function beforehand and that you not use the login applet if it is not a Nintendo Network account.
The login applet does not check the Parental Controls settings. If your application has features that can be restricted by the Parental Controls, make sure that the application appropriately reflects the setting. For example, if the Parental Controls have been set to restrict all services that are available after account authentication, do not even bother calling the login applet.
Like other library applets, the login applet supports preloading. You also must support and check to determine whether control returned to the applet due to the pressing of the HOME Button or the POWER Button or a software reset immediately after control was returned to the application.
5.4.4.1. Service Tokens for Independent Services
For services that use independent servers, you can use the nn::act::applet::AcquireIndependentServiceToken()
function to get a service token that verifies that the connected user has received Nintendo account authentication.
nn::Result nn::act::applet::AcquireIndependentServiceToken( char* pServiceToken, const char* pClientId, u32 reusableRangeInSeconds = 0 );
If a nonzero value is set in the reusableRangeInSeconds
parameter, the cached service token is returned without communicating with the account server, providing that a certain amount of time (specified as a number of seconds) has not passed since the last time a service token was obtained from the account server. If the service token is invalid, for example because time has expired or due to a denial by the independent server, specify 0
for this parameter to ensure that you can get another service token.
The login applet performs communications internally. You do not need to specify a buffer for communications when you initialize the ACT library.
char serviceToken[NN_ACT_INDEPENDENT_SERVICE_TOKEN_SIZE]; nn::Result result = nn::act::applet::AcquireIndependentServiceToken( serviceToken, CLIENT_ID_INDEPENDENT, SERVICE_TOKEN_REUSABLE_RANGE ); if ( result.IsSuccess() ) { // Stores the service token in serviceToken. } else if ( nn::act::ResultCanceled::Includes( result ) ) { // Explicitly canceled by user, so go to the finalization sequence. } else if ( nn::act::ResultApplicationUpdateRequired::Includes( result ) ) { // An application update is required, so jump to the Nintendo eShop patch page (optional). } else { // Some error other than a cancellation has occurred, so show the error code. u32 networkErrorCode = nn::act::GetErrorCode( result ); // Initialize the configuration structure. nn::applet::AppletWakeupState wstate; nn::erreula::Parameter ere_param; // Error EULA configuration structure ere_param.config.errorType = nn::erreula::ERROR_TYPE_ERROR_CODE; ere_param.config.errorCode = networkErrorCode; ere_param.config.upperScreenFlag = nn::erreula::UPPER_SCREEN_NORMAL; ere_param.config.homeButton = true; ere_param.config.softwareReset = false; ere_param.config.appJump = false; nn::erreula::StartErrEulaApplet( &wstate, &ere_param ); }
5.4.4.2. Service Tokens for Miiverse
Use the nn::act::applet::AcquireOlvServiceToken()
function to get Miiverse service tokens. Service tokens for Miiverse are needed when using the OLV library.
The login applet performs communications internally. You do not need to specify a buffer for communications when you initialize the ACT library.
The errors that require handling are the same as those for 5.4.4.1. Service Tokens for Independent Services.
5.4.5. Creating UUIDs
Use the nn::act::GenerateUuid()
function to create UUIDs (Universally Unique Identifiers) that can be allocated to automatically generated objects and the like.
The created UUIDs comply with RFC 4122 - Version 1 specifications. The format might be changed in the future, but only in ways that will not compromise uniqueness of the UUIDs. For this reason, use the values returned by the nn::act::GenerateUuid()
function as the UUIDs without making any changes to them. Do not make use of only portions of these UUIDs, and do not extract time information or other information from these UUIDs for other uses.