この章では、本体設定で行ったユーザーに関する情報やサウンドの設定などを、アプリケーションから取得する方法について説明します。
11.1. 初期化
本体設定で扱われている情報や 3DS 本体の情報へのアクセスには CFG ライブラリを使用します。
一部の関数を除いて、CFG ライブラリの関数を使用するには、まず nn::cfg::Initialize()
で初期化を行わなければなりません。初期化を行ったあとは、終了処理を行うまで CFG ライブラリの関数を呼び出すことができます。
void nn::cfg::Initialize(void);
11.2. 情報の取得
ライブラリの初期化後は、用意されている関数を呼び出すことで様々な情報にアクセスすることができるようになります。
11.2.1. ユーザー名
本体設定で設定された、ユーザーの名前を取得することができます。
void nn::cfg::GetUserName(nn::cfg::UserName* pUserName); struct nn::cfg::UserName { wchar_t userName[CFG_USER_NAME_LENGTH]; bool isNgUserName; NN_PADDING1; };
pUserName
には、ユーザー名を格納する nn::cfg::UserName
構造体へのポインタを指定します。
nn::cfg::UserName
構造体の userName
メンバにはユーザー名がワイド文字列で格納され、isNgUserName
メンバにはユーザー名に NG ワードが含まれている場合に true
が格納されます。
NG ワードのチェックは、日本リージョンであれば日本語、北米リージョンであれば北米英語と本体設定言語、欧州リージョンであればイギリス英語と本体設定言語で行われます。
11.2.2. 誕生日
本体設定で設定された、ユーザーの誕生日を取得することができます。
void nn::cfg::GetBirthday(nn::cfg::Birthday* pBirthday); struct nn::cfg::Birthday { s8 month; s8 day; };
pBirthday
には、誕生日を格納する nn::cfg:Birthday
構造体へのポインタを指定します。
11.2.3. 国コード
本体設定で設定された、ユーザーの住んでいる国および地域を国コードで取得することができます。
nn::cfg::CfgCountryCode nn::cfg::GetCountry(void);
定義されている国コードについては、ヘッダファイル(nn/cfg/CTR/cfg_CountryCode.h
)を参照してください。
国コードと国名コード(ISO 3166-1 alpha-2)は、以下の関数で相互に変換することができます。
nn::Result nn::cfg::ConvertCountryCodeToIso3166a2( char* iso3166a2, nn::cfg::CfgCountryCode countryCode); nn::Result nn::cfg::ConvertIso3166a2ToCountryCode( nn::cfg::CfgCountryCode* pCountryCode, const char* iso3166a2);
nn::cfg::GetCountryCodeA2()
は CTR-SDK から削除されます。
国コードと国名コードの相互変換を行う関数を使用するアプリケーションは、必ず返り値に nn::cfg::ResultNotFound
が返された場合のハンドリングを行ってください。
11.2.4. 言語コード
本体設定で設定された、表示に使用する言語を言語コードで取得することができます。
nn::cfg::CfgLanguageCode nn::cfg::GetLanguage(void);
定義されている言語コードには、以下のものが存在します。
値 |
言語 |
言語名(ISO 639-1 alpha-2) |
---|---|---|
|
日本語 |
ja |
|
英語 |
en |
|
フランス語 |
fr |
|
ドイツ語 |
de |
|
イタリア語 |
it |
|
スペイン語 |
es |
|
中国語(簡体字) |
zh |
|
韓国語 |
ko |
|
オランダ語 |
nl |
|
ポルトガル語 |
pt |
|
ロシア語 |
ru |
|
中国語(繁体字) |
zh |
取得した言語コードは、以下の関数で言語名(ISO 639-1 alpha-2)に変換することができます。
const char* nn::cfg::GetLanguageCodeA2(CfgLanguageCode cfgLanguageCode);
cfgLanguageCode
で指定した言語コードに対応する文字列がなかった場合は NULL
を返します。
この関数は初期化を行っていない状態でも呼び出すことができます。
11.2.5. 簡易アドレス情報
本体設定で設定された、簡易アドレス情報(国名、地域名、緯度、経度)を取得することができます。
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; };
pSimpleAddress
には、簡易アドレス情報を格納する nn::cfg::SimpleAddress
構造体へのポインタを指定します。
nn::cfg::SimpleAddress
構造体の countryName
メンバと regionName
メンバには国名と地域名がワイド文字列で格納され、latitude
メンバと longitude
メンバには緯度と経度が格納されます。
緯度(latitude
メンバ)と経度(longitude
メンバ)は 360°を 65536 で割った値(約 0.005°)を単位に表されます。北緯 0°~90°が 0x0000~0x4000、南緯 0.005°~90°が 0xFFFF~0xC000、東経 0°~179.995°が 0x0000~0x7FFF、西経 0.005°~180°が 0xFFFF~0x8000 にそれぞれ対応しています。
11.2.5.1. 簡易アドレス情報の ID
簡易アドレス情報の 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; };
pSimpleAddressId
には、nn::cfg::SimpleAddressId
構造体へのポインタを指定します。
nn::cfg::SimpleAddressId
構造体には、国コードを取得する GetCountryCode()
メンバと地域コードを取得する GetRegionCode()
メンバが用意されています。それぞれのメンバ関数で取得できる値については、「11.2.3. 国コード」を参照してください。
11.2.5.2. ID による簡易アドレス情報の取得
簡易アドレス情報の ID から、簡易アドレス情報を取得することができます。
nn::Result nn::cfg::GetSimpleAddress(nn::cfg::SimpleAddress* pSimpleAddress, nn::cfg::SimpleAddressId simpleAddressId, uptr pWorkMemory, u32 workMemorySize);
simpleAdressId
に指定した ID をもとに取得した簡易アドレス情報を pSimpleAddress
に格納します。
この関数の動作にはワークメモリが必要です。nn::cfg::CFG_SIMPLE_ADDRESS_WORKMEMORY_SIZE
以上のサイズで確保したワークメモリとそのサイズを、pWorkMemory
と workMemorySize
のそれぞれに指定してください。
11.2.5.3. 簡易アドレス情報の ID の 3DS と Wii U 間での相互変換
以下の関数で、3DS の簡易アドレス情報の ID と Wii U の簡易アドレス情報の ID を相互に変換することができます。
nn::cfg::SimpleAddressId nn::cfg::ConvertToWiiUSimpleAddressId( nn::cfg::SimpleAddressId ctrSimpleAddressId); nn::cfg::SimpleAddressId nn::cfg::ConvertToCtrSimpleAddressId( nn::cfg::SimpleAddressId wiiUSimpleAddressId);
11.2.6. リージョンコード
ここで扱うリージョンコードは、出荷時に 3DS 本体に設定されているものです。カードに設定するリージョンコードは bsf ファイルで設定し、本体とカードのリージョンコードが異なる場合やカードにリージョンコードが設定されていない場合にはソフトは起動しません。bsf ファイルについては、CTR-SDK のツール「ctr_makebanner」のリファレンスなどを参照してください。
本体の仕向地をリージョンコードで取得することができます。
nn::cfg::CfgRegionCode nn::cfg::GetResion(void);
定義されているリージョンコードには、以下のものが存在します。
値 |
仕向地 |
対応する文字列 |
---|---|---|
|
日本 |
JPN |
|
米州 |
USA |
|
欧州および豪州 |
EUR |
|
中国 |
CHN |
|
韓国 |
KOR |
|
台湾 |
TWN |
取得したリージョンコードは、以下の関数で対応するアルファベット 3 文字の文字列に変換することができます。
const char* nn::cfg::GetRegionCodeA3(CfgRegionCode cfgRegionCode);
cfgRegionCode
に指定したリージョンコードに対応する文字列がなかった場合は NULL
を返します。
11.2.7. サウンド出力モード
本体設定で設定された、サウンドの出力モードを取得することができます。
nn::cfg::CfgSoundOutputMode nn::cfg::GetSoundOutputMode(void);
定義されているサウンド出力モードには、以下のものが存在します。
値 |
サウンド出力モード |
---|---|
|
モノラル |
|
ステレオ |
|
(3D)サラウンド |
11.2.8. RTC 改変オフセット値
ハードウェアが保持している、ユーザーによる RTC 時刻の改変オフセット値を取得することができます。
nn::fnd::TimeSpan nn::cfg::GetUserTimeOffset(void);
改変オフセット値は秒単位で返されます。この値は本体設定の時刻設定で時刻が変更されたときに、何秒進め(戻し)たかの絶対値を累積したものです。この値の取り扱いについては、「8.5.3. 時刻改変のオフセット値の取り扱い」を参照してください。
11.2.9. ペアレンタルコントロール
写真の送受信やフレンドの追加などをアプリケーションで行う前に、本体設定の「保護者による使用制限」(以降、「ペアレンタルコントロール」と表記)で制限されていないかどうかを確認しなければなりません。ペアレンタルコントロールの設定が有効になっているかどうかは、nn::cfg::IsParentalControlEnabled()
で確認することができます。
bool nn::cfg::IsParentalControlEnabled(void);
項目名 |
制限対象となるアプリケーションの機能 |
参照先 |
---|---|---|
年齢制限 |
対象外(システム側で制限します) |
- |
インターネットブラウザーの使用 |
対象外(システム側で制限します) |
- |
ニンテンドーeショップ等での商品やサービスの購入 |
ECDK を利用したコンテンツ購入など |
|
3D映像の表示 |
対象外(システム側で制限します) |
- |
Miiverseの使用 |
Miiverse への投稿、Miiverse の閲覧 |
|
写真や画像・音声・動画・長文テキストの送受信 |
リッチ UGC の送受信 |
|
(北米)リッチ UGC のアップロード |
||
他のユーザーとのインターネット通信 |
ほかのユーザーとのデータ交換 |
|
他のユーザーとのすれちがい通信 |
すれちがい通信の使用 |
|
フレンドの登録 |
アプリケーション内でのフレンド登録 |
|
DSダウンロードプレイの使用 |
対象外 |
- |
配信動画の視聴 |
通信を介して取得した動画の視聴 |
11.2.9.1. 暗証番号の入力による制限の一時的な解除
ペアレンタルコントロールを適用するタイミングで保護者が一時的に制限を解除することができるように、アプリケーションは暗証番号の入力を受け付け、入力された暗証番号と設定されている暗証番号とが合致した場合に、一時的に制限を解除することができます。このとき、入力中の暗証番号や設定されている暗証番号が画面には一切表示されないように注意してください。
設定されているペアレンタルコントロールの暗証番号は、nn::cfg::CheckParentalControlPinCode()
で照合することができます。
bool nn::cfg::CheckParentalControlPinCode(const char *input);
input
に渡した文字列と暗証番号(半角数字 4 桁)が合致した場合に true
を返します。
ソフトウェアキーボードアプレットに「保護者による使用制限一時解除モード」を用意しています。このモードで起動したソフトウェアキーボードアプレットは専用のシーケンスで動作し、アプリケーションはアプレットからの返り値で制限を解除してよいかどうかを判断することができます。
11.2.9.2. 個人情報を含む可能性のあるデータの送受信に対する制限
ペアレンタルコントロールで写真交換(写真、画像、音声、動画、長文テキストなどの交換)が制限されているかどうかを、nn::cfg::IsRestrictPhotoExchange()
で確認することができます。写真交換が制限されている場合、制限が一時的に解除されない限り、アプリケーションは撮影した写真などの画像をほかの本体と送受信してはいけません。なお、この制限は写真だけでなく、画像、音声、動画、長文テキストなど、個人情報を含む可能性のあるデータの送受信が対象となっています。
bool nn::cfg::IsRestrictPhotoExchange(void);
制限されているときに true
が返されることに注意してください。
11.2.9.3. フレンド追加の制限
ペアレンタルコントロールでフレンドの追加が制限されているかどうかを、nn::cfg::IsRestrictAddFriend()
で確認することができます。フレンドの追加が制限されている場合、アプリケーションからのフレンド登録はエラーとなります。原則的に、アプリケーションがこの制限を一時的に解除することは許可されていません。
bool nn::cfg::IsRestrictAddFriend(void);
制限されているときに true
が返されることに注意してください。
11.2.9.4. ほかのユーザーとのインターネット通信の制限
ペアレンタルコントロールで、インターネット通信を経由したほかのユーザーとの対戦やデータのやり取りが制限されているかどうかを、nn::cfg::IsRestrictP2pInternet()
で確認することができます。この制限が有効になっている場合、制限が一時的に解除されない限り、アプリケーションは対戦やユーザー作成のコンテンツをダウンロードするようなインターネット通信を行ってはいけません。
bool nn::cfg::IsRestrictP2pInternet(void);
制限されているときに true
が返されることに注意してください。
11.2.9.5. すれちがい通信の制限
ペアレンタルコントロールで、すれちがい通信を経由したほかのユーザーとのデータのやり取りが制限されているかどうかを、nn::cfg::IsRestrictP2pCec()
で確認することができます。この制限が有効になっている場合、すれちがい通信は一切行われず、すれちがいデータの登録時にエラーとなります。アプリケーションがこの制限を一時的に解除することはできません。
bool nn::cfg::IsRestrictP2pCec(void);
制限されているときに true
が返されることに注意してください。
11.2.9.6. ニンテンドーeショップ等の利用の制限
ペアレンタルコントロールで、ニンテンドーeショップなどでのクレジットカードの使用や、商品やサービスの購入が制限されているかを、nn::cfg::IsRestrictShopUse()
で確認することができます。この制限が有効になっている場合、制限が一時的に解除されない限り、アプリケーションは残高の追加やコンテンツの購入などを行ってはいけません。
bool nn::cfg::IsRestrictShopUse(void);
制限されているときに true
が返されることに注意してください。
11.2.9.7. Miiverseの使用の制限
ペアレンタルコントロールで、Miiverse の閲覧や Miiverse への投稿が制限されているかを確認する関数が用意されています。Miiverse の閲覧が制限されているかどうかは nn::cfg::IsRestrictMiiverseBrowse()
で、Miiverse への投稿が制限されているかどうかは nn::cfg::IsRestrictMiiversePost()
で確認することができます。
ペアレンタルコントロールの本体設定での項目名と、各関数が返す値の対応は以下の通りです。
本体設定での項目名 |
IsRestrictMiiverseBrowse() |
IsRestrictMiiversePost() |
---|---|---|
「投稿・閲覧を制限する」 |
|
|
「投稿のみ制限する」 |
|
|
「制限しない」 |
|
|
これらの制限が一時的に解除されない限り、アプリケーションはほかのユーザーからの Miiverse への投稿を取得することや Miiverse への投稿を行ってはいけません。
11.2.9.8. 通信を介して取得した映像コンテンツの視聴の制限
11.2.10. EULA への同意の確認
ニンテンドーネットワークやすれちがい通信などを含む「ニンテンドー 3DS ネットワークサービス」をアプリケーションで利用するには、事前にユーザーによる EULA(利用規約)への同意が必要です。ユーザーが利用規約に同意しているかどうかを nn::cfg::IsAgreedEula()
で確認し、同意していない場合はこれらの機能を使用してはいけません。
bool nn::cfg::IsAgreedEula(void);
ユーザーが利用規約に同意しているときは true
が返されます。この関数を呼び出すには、事前に FS ライブラリの初期化が行われていなければなりません。
利用規約への同意の確認が必要な機能については、ガイドラインを参照してください。
11.2.11. 本体固有 ID
本体の識別などに利用する本体固有 ID を取得することができます。
bit64 nn::cfg::GetTransferableId(bit32 uniqueId);
uniqueId
には、アプリケーションに割り当てられたユニーク ID(20 ビット)を指定します。
本体固有 ID は、ユニーク性がある程度保証された 64 ビット値です。また、本体の移動が可能で、買い替えなどで本体が変わったときに移行することができます。ただし、本体を紛失した場合や盗難、破壊された場合は、二度とその ID を復帰させることができません。本体の初期化を行ったときにも本体固有 ID が変更され、ID の復帰はできません。
本体固有 ID の利用目的として、以下のようなものを想定しています。
- アプリケーション内のパラメータの初期値を、本体ごとで異なる値にする
- 特定の本体からのみアクセス可能なデータを生成する
- ローカル通信などの際に識別 ID、またはそのシードとする
セーブデータの作成時に取得した本体固有 ID を保存し、以後はセーブデータに保存された本体固有 ID を使用することで修理などによる変更に対応できる場合があります。また、保存の際に現在時刻と合わせた 128 ビット値として保存することで、複数のカードに同じデータが保存されることを回避することができます。
特定の本体でのみアクセス可能にした場合は、本体の初期化、本体の紛失や盗難により二度とアクセスできなくなってしまうことに注意してください。
11.2.12. COPPACS による制限
COPPACS(COPPA Compliance System)とは、北米向け(本体リージョンが北米、かつ国設定がアメリカまたはカナダの場合)に作成されたアプリケーションが COPPA(Children's Online Privacy Protection Act)に対応するために任天堂が提供するシステムです。
どのようなアプリケーションが COPPACS による制限の対象となるかについては、ガイドラインの「UGC」を参照してください。COPPACS の詳細は、「システムアプリ・アプレット仕様書」に記載される予定です。
COPPACS による制限がかけられているかどうかを取得することができます。
bool nn::cfg::IsCoppacsSupported(); nn::cfg::CfgCoppacsRestriction nn::cfg::GetCoppacsRestriction(void);
nn::cfg::GetCoppacsRestriction()
を呼び出すことで、COPPACS への対応方法を確認することができます。
CFG_COPPACS_RESTRICTION_NONE
が返された場合は制限がかけられていませんので、COPPACS への対応は必要ありません。
CFG_COPPACS_RESTRICTION_NEED_PARENTAL_PIN_CODE
または CFG_COPPACS_RESTRICTION_NEED_PARENTAL_AUTHENTICATION
が返された場合は制限がかけられていますので、COPPACS への対応が必要です。
前者はペアレンタルコントロールの暗証番号の入力で解除可能ですので、アプリケーション内で暗証番号の入力とチェック(「11.2.9.1. 暗証番号の入力による制限の一時的な解除」参照)を行い、正しい暗証番号が入力された場合に制限を一時的に解除することができます。後者はアプリケーション内で解除することができず、本体設定で COPPACS 認証の手続きを行う必要があります。
本体設定での認証手続きを行う場合、一旦アプリケーションを終了させなければならないことに注意してください。なお、本体設定からアプリケーションに戻ったことはアプリケーションの再起動時に確認することができます。ジャンプ前に行っていた処理を継続する場合は、必ず COPPACS への対応方法を再度確認してください。再確認時でも、本体設定での認証手続きが必要であると判断される可能性があります。
単に現在の本体設定が COPPACS の対象国であるかどうかの確認は、nn::cfg::IsCoppacsSupported()
で行うことができます。本体設定が対象国であれば、COPPACS の制限が掛けられてなくても true
が返されることに注意してください。
COPPACS 認証の手続きを行う画面(PARENTAL_CONTROLS_COPPACS
)へジャンプする方法は、「5.3.7. 本体設定へのジャンプ」で説明しています。実装例については、サンプルデモ(cfg の coppacs)を参照してください。