5. 通信補助ライブラリ

無線通信を利用する際にアプリケーションを補助するために、以下のライブラリが用意されています。

  • 受信拒否リスト
  • NG ワードリスト
  • おしらせ
  • アカウント

この章では、それぞれのライブラリを使用したアプリケーションの開発に必要な情報とプログラミング手順について説明します。

5.1. 受信拒否リスト

受信拒否リストとは、不適切なユーザー作成コンテンツ(以下 UGC と呼びます)がユーザー同士の直接通信(以下 P2P 通信)によって、広範囲に蔓延してしまうことを抑えるために用意された機能です。

5.1.1. 概要

UGC が特定のサーバー上で管理されている場合は、登録されている UGC の全数チェックを行ったりすることで、管理者が不適切な UGC を削除することができます。しかし、P2P 通信はサーバーを介さずに本体同士が直接通信するため、不適切な UGC に対応することができません。

受信拒否リストはそのような P2P 通信でも、できるだけ不適切な UGC の蔓延を抑えることを目的としています。

受信拒否リストでは、本体に用意されたリスト(ローカル受信拒否リスト)に不適切な UGC の作者を登録することができます。そこに登録されている作者の UGC を表示できなくすることで、不適切な UGC を制限します。

ユーザーはローカル受信拒否リストに対して、HOMEメニューから以下の操作を行うことができます。

  • 登録した UGC 作者情報の一括消去(解除)

受信拒否リストは UGC 作者の ID の登録と参照をするためだけのものですので、受信拒否リストに登録されたユーザーが作成した UGC を受け取っても、それが自動的に削除されるわけではありません。そのため、受信拒否リストへの対応が必要な UGC を受け取った場合は、その UGC 作者 ID が受信拒否リストに登録されていないかをアプリケーション自身で確認して、UGC の削除などを行う必要があります。また、受信拒否リストへの UGC 作者 ID の登録もアプリケーションで行う必要があります。

補足:

ローカル受信拒否リストは共有拡張セーブデータ領域に保存されます。

5.1.2. 初期化と終了

アプリケーションで受信拒否リストの機能を利用するには、UBL ライブラリを使用します。UBL ライブラリの初期化と終了は、nn::ubl::Initialize()nn::ubl::Finalize() で行います。

コード 5-1. UBL ライブラリの初期化と終了
void nn::ubl::Initialize(void);
void nn::ubl::Finalize(void);

5.1.3. ローカル受信拒否リスト

ローカル受信拒否リストは、受信した UGC の作者を対象とする自分専用のリストで、本体につき 1 つだけ保存されます。ユーザーには、「受信拒否設定」という名称で提供されます。

ローカル受信拒否リストには、ユーザーが不適切なものであると判断した UGC の UGC 作者情報を登録します。ローカル受信拒否リストへの登録は、nn::ubl::Entry() を呼び出して行います。

コード 5-2. ローカル受信拒否リストへの登録
nn::Result nn::ubl::Entry(u64 id, nn::fnd::DateTime *dt);

id には、ローカル受信拒否リストに登録する UGC 作者 ID を指定します。自分自身を登録しようとした場合はエラーが返されます。

UGC 作者 ID は UGC を作成した作者の ID で、受信拒否リストのためにのみ使用される ID です。本体ごとにユニークな 8 Byte の IDで、本体を特定することはできませんが、異なるアプリケーションで作成した UGC でも同じ ID となります。受信した UGC を編集することのできるアプリケーションの場合、編集された UGC からは、その UGC を最初に作成したユーザーの ID(新規作者 ID)ではなく、編集したユーザーの ID(編集者 ID)が登録されます。

補足:

アプリケーション側で必要な対応についてはガイドラインの「受信拒否リスト」を参照してください。

dt には、登録日時(現在日時)を指定します。UGC 作者情報には、UGC 作者 ID をローカル受信拒否リストに登録した日時が記録され、ローカル受信拒否リストが一杯になったときに削除する情報の判断に使用されます。

登録可能な UGC 作者情報は最大 1000 件です。登録時に、登録件数が最大数に達している場合は、古いものから自動的に上書きされます。

5.1.4. 受信拒否リスト該当チェック

受信拒否リストが対象とする UGC(ガイドラインの「受信拒否リスト」参照)を受信または表示するときには、その UGC の UGC 作者 ID がローカル受信拒否リストに登録されていないかをチェックしてください。

UGC 作者 ID のチェックは nn::ubl::IsExist() で行うことができます。

コード 5-3. 受信拒否リストのチェック
bool nn::ubl::IsExist(u64 authorId, u32 titleId, u64 dataId);

authorId には、チェックする UGC 作者 ID を指定します。受信した UGC を編集可能ならば、チェックは新規作者 ID と編集者 ID の両方に対して行ってください。

titleId dataId は将来の拡張機能で使用する引数です。現在は未対応の機能ですので、指定しても無視されます。

受信拒否リストに該当した UGC は、アプリケーションで削除または表示されないようにしてください。

5.1.5. UGC 閲覧モード

UGC 閲覧モードは、アプリケーション内で表示される可能性がある UGC の内容を閲覧できるモード(閲覧画面)です。UGC を作成することのできるアプリケーションには、必ず UGC 閲覧モードを用意してください。

UGC 閲覧モードでは、アプリケーションで表示される、まだローカル受信拒否リストに登録されていない作者の UGC を表示し、その中からユーザーが不適切だと判断した UGC をローカル受信拒否リストに登録できるように実装してください。

5.1.6. ローカル受信拒否リスト登録の流れ

下図は、すれちがい通信によるデータ受信を例にして、ローカル受信拒否リストの登録の流れを示したものです。

図 5-1. ローカル受信拒否リストの登録の流れ

UGC データの作者 ユーザー A データ a ユーザー B データ a ユーザー C データ a ユーザー D データ a ユーザー F データ a’ ユーザー C のローカル受信拒否リスト (1) データを受信 ユーザー A の作者情報 (2) ユーザー A をローカル受信拒否リストに登録 (3) 別のユーザーを経由して受信 (5) 編集されたデータを受信した場合も削除 (4) 受信したデータの作者がユーザー A であることを検知したので、データを削除 ユーザー E データ e すれちがい通信によるデータの移動 データ a’ 編集

  1. ユーザー A が作成した UGC を含むデータ(「データ a」)を、ユーザー B からユーザー C が受信したとします。
  2. ユーザー C がアプリケーション内で「データ a」を見て不適切だと感じたため、UGC 閲覧モードから「データ a」を選択します。アプリケーションは以下のようなメッセージを表示して、ローカル受信拒否リストに登録するかどうかをユーザーに確認します。「はい」が選択されたときは、ローカル受信拒否リストにユーザー A を登録します。
    「受信拒否設定に登録しますか? はい いいえ」
  3. その後、同じ「データ a」をユーザー D から受信したとします。
  4. すれちがい通信の場合、「データ a」を受信したあとでユーザー C が対応するアプリケーションを起動したときに、「データ a」の作者ユーザー A がローカル受信拒否リストに登録されていることを検知して、「データ a」が削除されます。(ガイドラインの「受信拒否リスト」参照)
  5. そのあと、ユーザー A が "編集" した「データ a'」をユーザー F から受信したとしても、「データ a'」の編集者 ID がローカル受信拒否リストに登録されているため、「データ a'」は削除されます。

5.2. NG ワードリスト

インターネット経由の通信だけでなく、すれちがい通信のようなローカル通信においても、文字列情報を含むユーザー作成コンテンツ(以下 UGC と呼びます)を送受信する際には、必ず NG ワードリストによる NG ワードのチェックを行ってください。

NG ワードのチェックは、リージョンや言語設定が異なる本体と通信できる場合でも、送信側もしくは受信側のどちらか一方だけで構いません。また、送信側と受信側の両方でチェックしても構いません。

CTR-SDK では、NG ワードのチェックを行う NGC ライブラリを用意しています。NGC ライブラリは Wii の DWC ライブラリなどとは異なり、サーバーを仲介せずに問題のある語句かどうかをチェックすることができます。

5.2.1. 初期化と終了

NG ワードのチェックは nn::ngc::ProfanityFilter クラスで行います。事前に FS ライブラリを初期化しておく必要があります。

コード 5-4. nn::ngc::ProfanityFilter クラスの初期化
class nn::ngc::ProfanityFilter
{
    ProfanityFilter();
    ProfanityFilter(const nn::WithInitialize&);
    ProfanityFilter(uptr pWorkMemory);

    nn::Result Initialize();
    nn::Result Initialize(uptr pWorkMemory);
}

NG ワードのチェックで使用する作業メモリは、ライブラリでメモリブロックから確保させるか、アプリケーションで確保しなければなりません。作業メモリとして必要なサイズは nn::ngc::ProfanityFilter::WORKMEMORY_SIZE ( 65,536 Byte )です。

nn::WithInitialize() を引数にインスタンスを生成した場合と、引数なしのコンストラクタで生成したインスタンスで引数なしの Initialize() を呼び出した場合は、作業メモリがメモリブロックから確保されます。事前にメモリブロック(nn::os::MemoryBlock クラス)が利用できるようにしなければならないことに注意が必要です。

pWorkMemory に作業メモリの先頭アドレスを指定してインスタンスを生成した場合と、引数なしのコンストラクタで生成したインスタンスで引数ありの Initialize() を呼び出した場合は、作業メモリをアプリケーションで確保しなければなりません。作業メモリは nn::ngc::ProfanityFilter::WORKMEMORY_ALIGNMENT ( 4 Byte ) アライメント、nn::ngc::ProfanityFilter::WORKMEMORY_SIZE ( 65,536 Byte ) 以上の連続したメモリ領域で確保してください。

チェックを完了し、インスタンスが不要になったときは Finalize() を呼び出して終了処理を行ってください。

コード 5-5. nn::ngc::ProfanityFilter クラスの終了
class nn::ngc::ProfanityFilter
{
    nn::Result Finalize();
}

終了処理後は作業メモリを解放することができます。メモリブロックから確保していた場合は、終了処理の中で解放されています。

5.2.2. NG ワードのチェック

NG ワードのチェックは ProfanityFilter クラスのメンバ関数 CheckProfanityWords() で行います。

コード 5-6. NG ワードのチェック
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);
}

各オーバーロードは上から、全リージョン・全言語でのチェック、パターンリスト(リージョンと言語の組み合わせ)を指定してチェック、本体のリージョンから適切なパターンリストを自動で判定してチェックするためのものです。

ppWords nWordCount には、チェックする文字列の配列と文字列の個数を指定します。文字列は文字コード UTF16-LE の NULL 終端で指定します。複数の文字列を同時に確認することができ、一度に複数の文字列をチェックすることで個別にチェックするよりも短い時間でチェックすることができます。

pCheckResults には判定結果が格納されますので、nWordCount 以上の要素を持つ bit32 型の配列を指定してください。判定結果はビットフラグで返され、フラグが立っている(1 になっている)ビットが、どのパターンリストで NG ワードであると判定されたかを示します。nn::ngc::ProfanityPatternList に定義されている値で 1 を左ビットシフトしたものが、そのパターンリストに対応するビットです。すべてのパターンリストで問題がなければ 0 が格納されます。

nPatternCode には、チェックに使用するパターンリストを nn::ngc::ProfanityPatternList に定義されている値で指定します。nn::ngc::ProfanityPatternList には、以下のパターンリストが定義されています。

表 5-1. パターンリスト

定義

リージョン

言語

PATTERNLIST_JAPAN_JAPANESE

日本

日本語

PATTERNLIST_AMERICA_ENGLISH

米州

北米英語

PATTERNLIST_AMERICA_FRENCH

米州

フランス語(カナダ)

PATTERNLIST_AMERICA_SPANISH

米州

スペイン語(ラテンアメリカ)

PATTERNLIST_EUROPE_ENGLISH

欧州

イギリス英語

PATTERNLIST_EUROPE_FRENCH

欧州

フランス語

PATTERNLIST_EUROPE_GERMAN

欧州

ドイツ語

PATTERNLIST_EUROPE_ITALIAN

欧州

イタリア語

PATTERNLIST_EUROPE_SPANISH

欧州

スペイン語

PATTERNLIST_EUROPE_DUTCH

欧州

オランダ語

PATTERNLIST_KOREA_KOREAN

韓国

韓国語

PATTERNLIST_CHINA_SIMP_CHINESE

中国

中国語(簡体字)

PATTERNLIST_EUROPE_PORTUGUESE

欧州

ポルトガル語

PATTERNLIST_EUROPE_RUSSIAN

欧州

ロシア語

PATTERNLIST_AMERICA_PORTUGUESE

北米

ポルトガル語(ブラジル)

PATTERNLIST_TAIWAN_TRAD_CHINESE

台湾

中国語(繁体字)

PATTERNLIST_TAIWAN_ENGLISH

台湾

英語(台湾)

引数 bCommunicateWithOtherRegions を持つオーバーロードは、チェックすべきパターンリストを本体のリージョンから判断します。そのため、このオーバーロードを呼び出す場合は CFG ライブラリの初期化が必要です。この引数に false を指定した場合は本体のリージョンと一致するパターンリストでのみチェックを行います。現在、この引数は参照されず、false を指定した場合のチェックを行います。

NG ワードのチェックは処理をブロックし、完了までに時間がかかる場合がありますので、別のスレッドを作成してチェックすることを推奨します。

5.2.3. 数字のチェック

nn::ngc::ProfanityFilter クラスによるチェックでは、メールアドレスの表記に使われる可能性のあるアットマーク記号が含まれていることは判定できますが、電話番号などの表示に利用される可能性のある数字が多く含まれているかどうかについては判定できません。

文字列に含まれている数字の数をチェックするには、nn::ngc::CountNumbers() を呼び出します。この関数の呼び出しには、nn::ngc::ProfanityFilter クラスの初期化は必要ありません。

コード 5-7. 文字列に含まれる数字の数のチェック
int nn::ngc::CountNumbers(const wchar_t *pString);

pString には、チェックする文字列を指定します。文字列は文字コード UTF16-LE の NULL 終端で指定します。

返り値は文字列に含まれている数字の数です。エラーが発生したときには負の値が返されます。

5.2.4. 文章のチェック

nn::ngc::ProfanityFilter クラスの MaskProfanityWordsInText() では、文章のように長い文字列に対する NG ワードのチェックを行い、問題となる文字列をアスタリスク(「*」)に置き換えることができます。表示名などのように短い文字列に対する NG ワードのチェックは、CheckProfanityWords() を利用してください。

コード 5-8. 文章内の NG ワードのチェック
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);
}

各オーバーロードは上から、全リージョン・全言語でのチェック、パターンリスト(リージョンと言語の組み合わせ)を指定してチェック、本体のリージョンから適切なパターンリストを自動で判定してチェックするためのものです。

pText にチェック対象となる文章へのポインタを渡します。pProfanityWordCountNULL ではない int 型変数へのポインタを渡すと、問題となる文字列が文章中に現れた回数を返します。

nPatternCode によるパターンリストの指定や、bCommunicateWithOtherRegions の指定については、CheckProfanityWords() の説明を参照してください。

NG ワードのチェックは処理をブロックし、完了までに時間がかかる場合がありますので、別のスレッドを作成してチェックすることを推奨します。

SetMaskMode()bOverWrite には、MaskProfanityWordsInText() で問題となる文字列をアスタリスクに置き換える際に、そのままの文字数で置き換える(true:デフォルト)か、文字数に関係なく 1 文字で置き換える(false)かを指定します。そのままの文字数で置き換えた場合、元の文字とアスタリスクの文字幅の違いにより、プロポーショナルフォントで表示したときに枠外などにはみ出てしまう可能性があることに注意してください。

5.3. おしらせ

HOMEメニュー機能の「おしらせリスト」には、Wii の伝言板のように任天堂からのおしらせやアプリケーションからのおしらせなどが表示されます。このおしらせをアプリケーションから投稿することができます。

5.3.1. 初期化と終了

アプリケーションからおしらせを投稿するためには、NEWS ライブラリを利用します。おしらせを投稿する前に、nn::news::Initialize() で NEWS ライブラリの初期化を行ってください。おしらせを投稿する必要がなくなったときは、nn::news::Finalize() を呼び出してください。

コード 5-9. NEWS ライブラリの初期化と終了
nn::Result nn::news::Initialize();
nn::Result nn::news::Finalize();

5.3.2. おしらせの投稿

おしらせの投稿は nn::news::PostNews() の呼び出しで行われます。

コード 5-10. おしらせの投稿
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);

おしらせのタイトル(subject)と本文(message)の指定は必須です。どちらも、文字コード UTF16-LE の NULL 終端文字列で指定し、改行には 0x000A(LF)の制御文字を使用します。

picture pictureSize には、おしらせに画像を添付するときに、画像データとそのサイズを指定します。

serialId dataVersion には、おしらせのシリアル ID とデータバージョンを指定しますが、現時点では 0 を指定してください。

jumpParam には、おしらせリストからアプリケーションにジャンプする際のパラメータを指定します。アプリケーションでは、おしらせリストから起動されたことを nn::news::IsFromNewsList() で検知することができ、jumpParam で指定されたパラメータを取得することができます。

それぞれの引数で指定されたタイトル、本文、添付画像は関数内でコピーされますので、投稿が完了した時点で解放することができます。

タイトル、本文、添付画像の仕様は以下のとおりです。投稿間隔の制限などについてはガイドラインを参照してください。

表 5-2. おしらせの仕様

項目

仕様

タイトル

文字コード UTF16-LE。終端文字を含めて、nn::news::SUBJECT_LEN 文字以下。

最大幅の内蔵フォント(日米欧リージョンは "%"、そのほかのリージョンはひらがな、漢字、ハングルなど)17 文字分の幅まで表示されます。最大表示幅を越えた場合は、文字サイズが最大 80% まで縮小されます。それでも最大表示幅を越えた場合は、越えた分の文字が非表示になります。

本文

文字コード UTF16-LE。終端文字を含めて、nn::news::MESSAGE_LEN 文字以下。

最大幅の内蔵フォント 18 文字分の幅までが 1 行に表示されます。

添付画像

MPO 形式で 3D 写真可。nn::news::PICTURE_SIZE バイト以下。

仕様で定められた文字列長を超えたタイトル、本文を指定したときや、不正な形式の画像やデータサイズの制限を超える添付画像を指定したときは、以下のエラーが返されます。

表 5-3. おしらせの投稿で返されるエラー

返り値

エラーの原因

ResultInvalidSubjectSize

タイトルに指定した文字列が長すぎます。

ResultInvalidMessageSize

本文に指定した文字列が長すぎます。

ResultInvalidPictureSize

添付画像の制限サイズを超えています。

ResultInvalidPicture

対応していない形式の画像データです。

5.3.3. URL 付おしらせの投稿

URL 付おしらせは、通常のおしらせに URL を付与したものです。おしらせに URL が付与されると、おしらせリストで表示したときに、指定された URL のページをインターネットブラウザで開くためのボタンが表示されます。

コード 5-11. 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);

url workBuf 以外の引数への指定方法は nn:news::PostNews() と同じです。

url には、付与する URL を文字コード UTF-8 で指定します。付与できる URL の最大長は、NULL 終端を含んで nn::news::MESSAGE_URL_URL_SIZE Byte です。なお、URL は本文が格納される領域を利用するため、URL を付与したときの本文の最大文字数は以下の式で求めた値となります。

nn::news::MESSAGE_LEN -(NULL 終端を含む URL の文字数)/ 2

workBuf には、GetWorkBufferSizeForNewsUrl() で返されるサイズで確保されたワークバッファを指定します。本文や URL の文字数が最大長をオーバーしている、不正なポインタを指定しているなど、渡された引数が不正である場合は 0 が返されます。

5.4. アカウント

アカウントライブラリ(ACT ライブラリ)は、アプリケーションから 3DS のアカウントシステムの機能を利用するためのライブラリです。アカウントシステムの全体像については、CTR-SDK に同梱されている「CTR アカウントシステム デベロッパーズガイド」を参照してください。

アプリケーションは ACT ライブラリを利用することにより、本体内にキャッシュされているニンテンドーネットワークアカウントの情報の取得や、登録された情報に基づく認証を行うことができます。

5.4.1. 初期化と終了

ACT ライブラリの初期化は nn::act::Initialize() で行います。

ネットワーク時計やログインアプレットのように、インターネット通信を行う ACT ライブラリの関数を利用する場合は、それらの関数を呼び出す前に AC ライブラリでインターネット接続を完了させておいてください。また、インターネット通信を行う関数には、ACT ライブラリの初期化時に通信用バッファの指定が必要になるものもあります。

補足:

現在公開されている ACT ライブラリの関数には、通信用バッファの指定が必要なものはありません。

通信用バッファとして渡すバッファは デバイスメモリ以外から確保 しなければなりません 。また、バッファの先頭アドレスのアライメントは nn::act::BUFFER_ALIGNMENT ( 4096 Byte ) 、バッファのサイズは nn::act::BUFFER_UNITSIZE ( 4096 ) の倍数でなければなりません。

nn::act::Initialize() は多重呼び出しが可能です。ただし、通信用バッファには ACT ライブラリが初期化されていない状態でのときに指定されたバッファが使用され、初期化済みの状態で指定されたバッファは使用されません。

nn::act::Initialize() が呼び出された回数は記録されます。そのため、nn::act::Finalize()nn::act::Initialize() と同じ回数呼び出すまで ACT ライブラリは初期化済みと判断されます。

5.4.2. ニンテンドーネットワークアカウントの情報

ACT ライブラリを使用することで、ニンテンドーネットワークアカウントの情報をアプリケーションで利用することができます。

ニンテンドーネットワークアカウントの情報を取得する関数のほとんどがローカルにキャッシュされたデータを返すため、関数の実行で通信が行われることはありません。

ニンテンドーネットワークアカウントの情報と取得関数の対応は下表のとおりです。詳細については関数リファレンスを参照してください。

表 5-4. ニンテンドーネットワークアカウントの情報と取得関数の対応

情報

関数

備考

ネットワークアカウント

IsNetworkAccount()

本体アカウントがネットワークアカウントかどうかを判定します。

アカウント ID

GetAccountId()

 

プリンシパル ID

GetPrincipalId()

ACT ライブラリで取得するプリンシパル ID はニンテンドーネットワークアカウントの登録時にアカウントサーバーで発行された ID です。

同じプリンシパル ID という名前でも、FRIENDS ライブラリで取得するプリンシパル ID はフレンドサーバーで発行された ID であり、ACT ライブラリで取得する ID とは異なります。2 つの ID を混在して管理したり、FRIENDS ライブラリの関数に ACT ライブラリで取得したプリンシパル ID を渡したりしないように注意してください。

パスワード

取得することができません。

メールアドレス

企画上取得する必要がある場合は、弊社窓口までご相談ください。

生年月日

企画上取得する必要がある場合は、弊社窓口までご相談ください。

年齢

IsOverAge()

指定年齢以上かの判定のみが可能です。 詳しくは「5.4.2.1. 年齢判定」を参照してください。

居住国

GetCountry()

ISO 3166-1 alpha-2 形式で返します。

居住地域

GetSimpleAddressId()
GetWiiUSimpleAddressId()

 

タイムゾーン

GetTimeZoneId()

居住地域のタイムゾーンを tz database 形式で返します。

時差

GetUtcOffset()

居住地域の時刻と UTC との時差をマイクロ秒単位で返します。

夏時間を考慮した時差を返しますが、キャッシュのタイミングによっては正確な時差とはならないことがあります。

性別

企画上取得する必要がある場合は、弊社窓口までご相談ください。

5.4.2.1. 年齢判定

nn::act::IsOverAge() は、ニンテンドーネットワークアカウントのユーザーの年齢が引数 age で指定された年齢以上であるかどうかを判定します。

年齢判定には、ニンテンドーネットワークアカウントの生年月日とネットワーク時計が使用されます。本体アカウントがネットワークアカウントではない場合や、ネットワーク時計が有効でない場合、この関数は必ず false を返します。ネットワーク時計を有効にする方法については「5.4.3. ネットワーク時計」を参照してください。

5.4.3. ネットワーク時計

ネットワーク時計を利用する関数を呼び出す場合は、事前にネットワーク時計の有効化と補正が行われていないと正しい時刻をもとにした処理が行われません。ネットワーク時計が利用可能になっているかを nn::act::IsNetworkTimeValidated() で確認し、利用可能でない場合は nn::act::InquireNetworkTime() を呼び出してください。

nn::act::InquireNetworkTime() はアカウントサーバーとの通信を行い、処理完了までアプリケーションの実行をブロックすることに注意してください。

なお、アカウントサーバーとの通信が行われる関数の実行が正常に完了したあとは、ネットワーク時計が利用可能な状態になっています。

5.4.4. ログインアプレット

ログインアプレットは、アカウントサーバーとの通信を行い、アカウント認証処理と各種サービストークンの取得処理などをアプリケーションの代わりに行います。なお、一連の処理が完了するまでアプリケーションに処理は戻りません。

ログインアプレット内でアカウント認証が行われますので、本体アカウントがネットワークアカウントでなければエラーが返されます。事前に nn::act::IsNetworkAccount() でネットワークアカウントであるかどうかを確認し、ネットワークアカウントでなければログインアプレットを利用しないようにすることを推奨します。

注意:

ログインアプレットではペアレンタルコントロールの設定をチェックしません。ペアレンタルコントロールで制限される機能を提供しているアプリケーションは、ペアレンタルコントロールの設定をアプリケーションで適切に反映してください。たとえば、アカウント認証後に利用するすべてのサービスがペアレンタルコントロールで制限されているならば、ログインアプレットの呼び出し自体を行わないなどです。

補足:

ほかのライブラリアプレットと同様に、ログインアプレットもプリロードに対応しています。また、アプリケーションに復帰した直後に HOMEボタンや電源ボタン、ソフトウェアリセットが要因となって復帰したかどうかのチェックと対応が必要です。

5.4.4.1. 独自サービス向けサービストークン

独自サーバーを利用したサービス向けに、接続するユーザーが任天堂のアカウント認証を受けたユーザーであることを証明するサービストークンを nn::act::applet::AcquireIndependentServiceToken() で取得することができます。

コード 5-12. 独自サービス向けサービストークンを取得する関数
nn::Result nn::act::applet::AcquireIndependentServiceToken(
    char*           pServiceToken,
    const char*     pClientId,
    u32             reusableRangeInSeconds = 0
);

引数 reusableRangeInSeconds に 0 以外の値を渡した場合、以前にアカウントサーバーと通信を行ってサービストークンを取得してから指定された秒数が経過していなければ、通信を行わずにキャッシュされたサービストークンを返します。期限切れや独自サーバー側の拒否など、サービストークンが無効になったときには、この引数に 0 を指定し、確実にサービストークンの再取得を行ってください。

ログインアプレット内で通信を行いますが、ACT ライブラリの初期化時に通信用バッファを指定する必要はありません。

コード 5-13. 独自サービス向けサービストークンを取得する際のエラーハンドリングの例
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() )
{
    // serviceTokenにサービストークンが格納されています
}
else if ( nn::act::ResultCanceled::Includes( result ) )
{
    // ユーザーによって明示的にキャンセルされたので終了シーケンスに進む
}
else if ( nn::act::ResultApplicationUpdateRequired::Includes( result ) )
{
    // アプリケーションの更新が必要なのでニンテンドーeショップのパッチページにジャンプする(任意)
}
else
{
    // キャンセル以外のエラーが発生したため、エラーコードを表示する
    u32 networkErrorCode = nn::act::GetErrorCode( result );

    // 設定構造体初期化
    nn::applet::AppletWakeupState wstate;
    nn::erreula::Parameter ere_param;    // エラーEULAの設定構造体
    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. Miiverse 向けサービストークン

Miiverse 向けのサービストークンを nn::act::applet::AcquireOlvServiceToken() で取得することができます。Miiverse 向けサービストークンは OLV ライブラリを利用する際に必要となります。

ログインアプレット内で通信を行いますが、ACT ライブラリの初期化時に通信用バッファを指定する必要はありません。

ハンドリングする必要のあるエラーは「5.4.4.1. 独自サービス向けサービストークン」と同じです。

5.4.5. UUID の生成

自動生成されたオブジェクトに割り振るなど、一意に特定可能な識別子として利用されている UUID(Universally Unique Identifier)を nn::act::GenerateUuid() で生成することができます。

生成される UUID は RFC 4122 - Version 1 の仕様に準拠していますが、今後、ユニーク性が損なわれない範囲でフォーマットが変更される可能性があります。そのため、nn::act::GenerateUuid() で返される UUID は返された値のまま使用してください。また、UUID の一部分だけを使用したり、時刻などの情報を取り出して使用したりしないでください。