11. 本体設定

この章では、本体設定で行ったユーザーに関する情報やサウンドの設定などを、アプリケーションから取得する方法について説明します。

11.1. 初期化

本体設定で扱われている情報や 3DS 本体の情報へのアクセスには CFG ライブラリを使用します。

一部の関数を除いて、CFG ライブラリの関数を使用するには、まず nn::cfg::Initialize() で初期化を行わなければなりません。初期化を行ったあとは、終了処理を行うまで CFG ライブラリの関数を呼び出すことができます。

コード 11-1. CFG ライブラリの初期化
void nn::cfg::Initialize(void);

11.2. 情報の取得

ライブラリの初期化後は、用意されている関数を呼び出すことで様々な情報にアクセスすることができるようになります。

11.2.1. ユーザー名

本体設定で設定された、ユーザーの名前を取得することができます。

コード 11-2. ユーザー名の取得
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. 誕生日

本体設定で設定された、ユーザーの誕生日を取得することができます。

コード 11-3. 誕生日の取得
void nn::cfg::GetBirthday(nn::cfg::Birthday* pBirthday);

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

pBirthday には、誕生日を格納する nn::cfg:Birthday 構造体へのポインタを指定します。

11.2.3. 国コード

本体設定で設定された、ユーザーの住んでいる国および地域を国コードで取得することができます。

コード 11-4. 国コードの取得
nn::cfg::CfgCountryCode nn::cfg::GetCountry(void);

定義されている国コードについては、ヘッダファイル(nn/cfg/CTR/cfg_CountryCode.h)を参照してください。

国コードと国名コード(ISO 3166-1 alpha-2)は、以下の関数で相互に変換することができます。

コード 11-5. 国コードと国名コードの相互変換
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. 言語コード

本体設定で設定された、表示に使用する言語を言語コードで取得することができます。

コード 11-6. 言語コードの取得
nn::cfg::CfgLanguageCode nn::cfg::GetLanguage(void);

定義されている言語コードには、以下のものが存在します。

表 11-1. 言語コード

言語

言語名(ISO 639-1 alpha-2)

CFG_LANGUAGE_JAPANESE

日本語

ja

CFG_LANGUAGE_ENGLISH

英語

en

CFG_LANGUAGE_FRENCH

フランス語

fr

CFG_LANGUAGE_GERMAN

ドイツ語

de

CFG_LANGUAGE_ITALIAN

イタリア語

it

CFG_LANGUAGE_SPANISH

スペイン語

es

CFG_LANGUAGE_SIMP_CHINESE

中国語(簡体字)

zh

CFG_LANGUAGE_KOREAN

韓国語

ko

CFG_LANGUAGE_DUTCH

オランダ語

nl

CFG_LANGUAGE_PORTUGUESE

ポルトガル語

pt

CFG_LANGUAGE_RUSSIAN

ロシア語

ru

CFG_LANGUAGE_TRAD_CHINESE

中国語(繁体字)

zh

取得した言語コードは、以下の関数で言語名(ISO 639-1 alpha-2)に変換することができます。

コード 11-7. 言語コードから言語名への変換
const char* nn::cfg::GetLanguageCodeA2(CfgLanguageCode cfgLanguageCode);

cfgLanguageCode で指定した言語コードに対応する文字列がなかった場合は NULL を返します。

補足:

この関数は初期化を行っていない状態でも呼び出すことができます。

11.2.5. 簡易アドレス情報

本体設定で設定された、簡易アドレス情報(国名、地域名、緯度、経度)を取得することができます。

コード 11-8. 簡易アドレス情報の取得
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 のみを取得する関数が用意されています。

コード 11-9. 簡易アドレス情報の 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 から、簡易アドレス情報を取得することができます。

コード 11-10. 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 以上のサイズで確保したワークメモリとそのサイズを、pWorkMemoryworkMemorySize のそれぞれに指定してください。

11.2.5.3. 簡易アドレス情報の ID の 3DS と Wii U 間での相互変換

以下の関数で、3DS の簡易アドレス情報の ID と Wii U の簡易アドレス情報の ID を相互に変換することができます。

コード 11-11. 簡易アドレス情報の ID の 3DS と 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. リージョンコード

補足:

ここで扱うリージョンコードは、出荷時に 3DS 本体に設定されているものです。カードに設定するリージョンコードは bsf ファイルで設定し、本体とカードのリージョンコードが異なる場合やカードにリージョンコードが設定されていない場合にはソフトは起動しません。bsf ファイルについては、CTR-SDK のツール「ctr_makebanner」のリファレンスなどを参照してください。

本体の仕向地をリージョンコードで取得することができます。

コード 11-12. リージョンコードの取得
nn::cfg::CfgRegionCode nn::cfg::GetResion(void);

定義されているリージョンコードには、以下のものが存在します。

表 11-2. リージョンコード

仕向地

対応する文字列

CFG_REGION_JAPAN

日本

JPN

CFG_REGION_AMERICA

米州

USA

CFG_REGION_EUROPE

欧州および豪州

EUR

CFG_REGION_CHINA

中国

CHN

CFG_REGION_KOREA

韓国

KOR

CFG_REGION_TAIWAN

台湾

TWN

取得したリージョンコードは、以下の関数で対応するアルファベット 3 文字の文字列に変換することができます。

コード 11-13. リージョンコードから対応する文字列への変換
const char* nn::cfg::GetRegionCodeA3(CfgRegionCode cfgRegionCode);

cfgRegionCode に指定したリージョンコードに対応する文字列がなかった場合は NULL を返します。

11.2.7. サウンド出力モード

本体設定で設定された、サウンドの出力モードを取得することができます。

コード 11-14. サウンド出力モードの取得
nn::cfg::CfgSoundOutputMode nn::cfg::GetSoundOutputMode(void);

定義されているサウンド出力モードには、以下のものが存在します。

表 11-3. サウンド出力モード

サウンド出力モード

CFG_SOUND_OUTPUT_MODE_MONO

モノラル

CFG_SOUND_OUTPUT_MODE_STEREO

ステレオ

CFG_SOUND_OUTPUT_MODE_SURROUND

(3D)サラウンド

11.2.8. RTC 改変オフセット値

ハードウェアが保持している、ユーザーによる RTC 時刻の改変オフセット値を取得することができます。

コード 11-15. RTC 改変オフセット値の取得
nn::fnd::TimeSpan nn::cfg::GetUserTimeOffset(void);

改変オフセット値は秒単位で返されます。この値は本体設定の時刻設定で時刻が変更されたときに、何秒進め(戻し)たかの絶対値を累積したものです。この値の取り扱いについては、「8.5.3. 時刻改変のオフセット値の取り扱い」を参照してください。

11.2.9. ペアレンタルコントロール

写真の送受信やフレンドの追加などをアプリケーションで行う前に、本体設定の「保護者による使用制限」(以降、「ペアレンタルコントロール」と表記)で制限されていないかどうかを確認しなければなりません。ペアレンタルコントロールの設定が有効になっているかどうかは、nn::cfg::IsParentalControlEnabled() で確認することができます。

コード 11-16. ペアレンタルコントロール設定が有効になっているかどうかの確認
bool nn::cfg::IsParentalControlEnabled(void);
表 11-4. ペアレンタルコントロールの項目と制限対象となるアプリケーションの機能

項目名

制限対象となるアプリケーションの機能

参照先

年齢制限

対象外(システム側で制限します)

-

インターネットブラウザーの使用

対象外(システム側で制限します)

-

ニンテンドーeショップ等での商品やサービスの購入

ECDK を利用したコンテンツ購入など

11.2.9.6

3D映像の表示

対象外(システム側で制限します)

-

Miiverseの使用

Miiverse への投稿、Miiverse の閲覧

11.2.9.7

写真や画像・音声・動画・長文テキストの送受信

リッチ UGC の送受信

11.2.9.2

(北米)リッチ UGC のアップロード

11.2.12

他のユーザーとのインターネット通信

ほかのユーザーとのデータ交換

11.2.9.4

他のユーザーとのすれちがい通信

すれちがい通信の使用

11.2.9.5

フレンドの登録

アプリケーション内でのフレンド登録

11.2.9.3

DSダウンロードプレイの使用

対象外

-

配信動画の視聴

通信を介して取得した動画の視聴

11.2.9.8

11.2.9.1. 暗証番号の入力による制限の一時的な解除

ペアレンタルコントロールを適用するタイミングで保護者が一時的に制限を解除することができるように、アプリケーションは暗証番号の入力を受け付け、入力された暗証番号と設定されている暗証番号とが合致した場合に、一時的に制限を解除することができます。このとき、入力中の暗証番号や設定されている暗証番号が画面には一切表示されないように注意してください。

設定されているペアレンタルコントロールの暗証番号は、nn::cfg::CheckParentalControlPinCode() で照合することができます。

コード 11-17. ペアレンタルコントロールの暗証番号の照合
bool nn::cfg::CheckParentalControlPinCode(const char *input);

input に渡した文字列と暗証番号(半角数字 4 桁)が合致した場合に true を返します。

ソフトウェアキーボードアプレットに「保護者による使用制限一時解除モード」を用意しています。このモードで起動したソフトウェアキーボードアプレットは専用のシーケンスで動作し、アプリケーションはアプレットからの返り値で制限を解除してよいかどうかを判断することができます。

11.2.9.2. 個人情報を含む可能性のあるデータの送受信に対する制限

ペアレンタルコントロールで写真交換(写真、画像、音声、動画、長文テキストなどの交換)が制限されているかどうかを、nn::cfg::IsRestrictPhotoExchange() で確認することができます。写真交換が制限されている場合、制限が一時的に解除されない限り、アプリケーションは撮影した写真などの画像をほかの本体と送受信してはいけません。なお、この制限は写真だけでなく、画像、音声、動画、長文テキストなど、個人情報を含む可能性のあるデータの送受信が対象となっています。

コード 11-18. 個人情報を含む可能性のあるデータの送受信に対する制限の確認
bool nn::cfg::IsRestrictPhotoExchange(void);

制限されているときに true が返されることに注意してください。

11.2.9.3. フレンド追加の制限

ペアレンタルコントロールでフレンドの追加が制限されているかどうかを、nn::cfg::IsRestrictAddFriend() で確認することができます。フレンドの追加が制限されている場合、アプリケーションからのフレンド登録はエラーとなります。原則的に、アプリケーションがこの制限を一時的に解除することは許可されていません。

コード 11-19. フレンド追加の制限の確認
bool nn::cfg::IsRestrictAddFriend(void);

制限されているときに true が返されることに注意してください。

11.2.9.4. ほかのユーザーとのインターネット通信の制限

ペアレンタルコントロールで、インターネット通信を経由したほかのユーザーとの対戦やデータのやり取りが制限されているかどうかを、nn::cfg::IsRestrictP2pInternet() で確認することができます。この制限が有効になっている場合、制限が一時的に解除されない限り、アプリケーションは対戦やユーザー作成のコンテンツをダウンロードするようなインターネット通信を行ってはいけません。

コード 11-20. ほかのユーザーとのインターネット通信の制限の確認
bool nn::cfg::IsRestrictP2pInternet(void);

制限されているときに true が返されることに注意してください。

11.2.9.5. すれちがい通信の制限

ペアレンタルコントロールで、すれちがい通信を経由したほかのユーザーとのデータのやり取りが制限されているかどうかを、nn::cfg::IsRestrictP2pCec() で確認することができます。この制限が有効になっている場合、すれちがい通信は一切行われず、すれちがいデータの登録時にエラーとなります。アプリケーションがこの制限を一時的に解除することはできません。

コード 11-21. すれちがい通信の制限の確認
bool nn::cfg::IsRestrictP2pCec(void);

制限されているときに true が返されることに注意してください。

11.2.9.6. ニンテンドーeショップ等の利用の制限

ペアレンタルコントロールで、ニンテンドーeショップなどでのクレジットカードの使用や、商品やサービスの購入が制限されているかを、nn::cfg::IsRestrictShopUse() で確認することができます。この制限が有効になっている場合、制限が一時的に解除されない限り、アプリケーションは残高の追加やコンテンツの購入などを行ってはいけません。

コード 11-22. ニンテンドーeショップ等の利用制限の確認
bool nn::cfg::IsRestrictShopUse(void);

制限されているときに true が返されることに注意してください。

11.2.9.7. Miiverseの使用の制限

ペアレンタルコントロールで、Miiverse の閲覧や Miiverse への投稿が制限されているかを確認する関数が用意されています。Miiverse の閲覧が制限されているかどうかは nn::cfg::IsRestrictMiiverseBrowse() で、Miiverse への投稿が制限されているかどうかは nn::cfg::IsRestrictMiiversePost() で確認することができます。

ペアレンタルコントロールの本体設定での項目名と、各関数が返す値の対応は以下の通りです。

表 11-5. Miiverse の使用の制限に対する本体設定での項目名と返り値の対応

本体設定での項目名

IsRestrictMiiverseBrowse()

IsRestrictMiiversePost()

「投稿・閲覧を制限する」

true

true

「投稿のみ制限する」

false

true

「制限しない」

false

false

これらの制限が一時的に解除されない限り、アプリケーションはほかのユーザーからの Miiverse への投稿を取得することや Miiverse への投稿を行ってはいけません。

11.2.9.8. 通信を介して取得した映像コンテンツの視聴の制限

ペアレンタルコントロールで、通信を介して取得した映像コンテンツの視聴が制限されているかを、nn::cfg::IsRestrictWatchVideo() で確認することができます。この制限が有効になっている場合、制限が一時的に解除されない限り、アプリケーションは通信を介して取得した動画の再生などを行ってはいけません。

コード 11-23. 通信を介して取得した映像コンテンツの視聴制限の確認
bool nn::cfg::IsRestrictWatchVideo(void);

制限されているときに true が返されることに注意してください。

11.2.10. EULA への同意の確認

ニンテンドーネットワークやすれちがい通信などを含む「ニンテンドー 3DS ネットワークサービス」をアプリケーションで利用するには、事前にユーザーによる EULA(利用規約)への同意が必要です。ユーザーが利用規約に同意しているかどうかを nn::cfg::IsAgreedEula() で確認し、同意していない場合はこれらの機能を使用してはいけません。

コード 11-24. EULA への同意の確認
bool nn::cfg::IsAgreedEula(void);

ユーザーが利用規約に同意しているときは true が返されます。この関数を呼び出すには、事前に FS ライブラリの初期化が行われていなければなりません。

利用規約への同意の確認が必要な機能については、ガイドラインを参照してください。

11.2.11. 本体固有 ID

本体の識別などに利用する本体固有 ID を取得することができます。

コード 11-25. 本体固有 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 による制限がかけられているかどうかを取得することができます。

コード 11-26. 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)を参照してください。

11.3. 終了処理

CFG ライブラリの使用を終了するときは、nn::cfg::Finalize() を呼び出して終了処理を行ってください。

コード 11-27. CFG ライブラリの終了
void nn::cfg::Finalize(void);

初期化が行われていない状態で呼び出された場合は何も行いません。

ライブラリの初期化関数を呼び出した回数は記録されていますので、同じ回数の終了処理が呼び出されるまでライブラリの使用を終了したとは見なされません。