この章では、3DS で提供されているアプレットを利用するための、ライブラリについて説明します。
各アプレットで提供されているライブラリにより、アプリケーションからそのアプレットを起動したり、機能を利用することができます。 アプレットの起動に必要なメモリは基本的にシステム側から確保されますが、アプリケーションから作業メモリを渡さなければならないアプレットも存在します。 また、アプレットの動作中は、呼び出したスレッドの動作を停止した上でアプリケーションと同じ CPU を使用しますので、実質的にアプリケーションは止まった状態になります。
12.1. ライブラリアプレット
3DS では、アプリケーションでよく使われる機能を、以下のライブラリアプレットとして提供しています。
- ソフトウェアキーボードアプレット
- 写真選択アプレット
- Mii 選択アプレット
- 音声選択アプレット
- エラー・EULA アプレット
- 拡張スライドパッド補正アプレット
- EC アプレット
- ログインアプレット
Mii 選択アプレットは CTR 似顔絵ライブラリパッケージで提供しています。
12.1.1. 各ライブラリアプレットに共通する情報
ライブラリアプレットを起動するために行わなければならない処理や、ライブラリアプレットから復帰したときの処理は、基本的に HOME メニューの起動と復帰で行っている処理と同じです。同様に、ライブラリアプレットから復帰するまで、キー入力の取得や描画などのデバイスの使用に制限がかかり、ライブラリアプレットを呼び出したスレッドのみが停止することにも注意が必要です。なるべく、不要なスレッドを動作中のままにしないようにしてください。ライブラリアプレットの起動中でも動作し続けるスレッドを作成する場合は、ライブラリアプレットが下表の優先度設定でスレッドを作成していることに注意し、それらのスレッドの処理に影響がないようにスレッドの優先度を設計してください。
ライブラリアプレット |
優先度 |
備考 |
---|---|---|
(すべてに共通) |
15 |
スリープなどの通知に使用しています。 |
ソフトウェアキーボードアプレット |
17~20 |
|
写真選択アプレット |
16, 18, 20, 21, 25 |
|
Mii 選択アプレット |
17 |
|
音声選択アプレット |
16, 18 |
|
エラー・EULA アプレット |
17, 20 |
|
拡張スライドパッド補正アプレット |
17~19 |
|
EC アプレット |
17, 22 |
通信などに使用しています。 |
ログインアプレット | 17, 22 | 通信などに使用しています。 |
HOME メニューの起動で呼び出している nn::applet::WaitForStarting()
から復帰するときのように、アプリケーション復帰後の nn::applet::IsExpectedToCloseApplication()
でアプリケーションの終了に対応する必要があります。ただし、ライブラリアプレットの表示中に電源ボタンが押されたときは、描画の権限がない状態、かつ同時に nn::applet::IsExpectedToProcessPowerButton()
が true
を返す状態になります。そのため、そのまま終了要求への対処を行うと、終了処理を行っている間の画面更新が止まってしまいますので、先に電源ボタンへの対処を行うように実装してください。
12.1.1.1. ライブラリアプレットからの復帰
ライブラリアプレットの起動中に HOME ボタンや電源ボタン、ソフトウェアリセットとなる組み合わせのボタン(L + R + START)が押されたときは、すぐにアプリケーションに復帰し、以下のような挙動となります。
ボタン |
挙動 |
---|---|
HOME ボタン |
リターンコードに HOME ボタンが押されたことが判別できる値を返し、復帰後の |
電源ボタン |
リターンコードに電源ボタンが押されたことが判別できる値を返し、復帰後の |
ソフトウェアリセット |
リターンコードにソフトウェアリセットされたことが判別できる値を返します。 |
12.1.1.2. プリロード
プリロードに対応しているライブラリアプレットは、事前にロードなどの処理を行うことができます。これにより、ライブラリアプレットを起動する関数を呼び出してから画面が表示されるまでの、描画が止まってしまう時間を短縮することができます。
プリロードのための関数名は各ライブラリアプレットで異なりますが、基本的に、プリロードを開始する Preload
~()
、プリロードの完了を待つ WaitForPreload
~()
、プリロードを取り消す CancelPreload
~()
に統一されています。
プリロードしたライブラリアプレットを起動するときは、必ずその完了を待ってから起動してください。また、完了を待つ関数は、プリロードを開始していない状態で呼び出すと制御を戻さなくなりますので注意してください。ただし、これは 1 つのスレッドで行った場合であり、完了を待っているスレッドと異なるスレッドでプリロードを開始させた場合は呼び出す順番が逆になっていても制御が戻ります。なお、nn::applet::ProcessHomeButton()
により HOME メニューを表示するとプリロードがキャンセルされます。そのため、Preload
~()
と WaitForPreload
~()
の間で HOME メニューへ遷移すると WaitForPreload
~()
が制御を戻さなくなりますので注意してください。
同時に複数のライブラリアプレットをプリロードしておくことはできません。プリロードしていたライブラリアプレット以外のライブラリアプレットを起動する場合は、先にプリロードを取り消さなければなりません。ライブラリアプレットを起動した時点でプリロードは解除されますので、ライブラリアプレットから復帰したあとに、プリロードを取り消す必要はありません。
12.1.2. ソフトウェアキーボードアプレット
名前やパスワードなど、アプリケーションがユーザーからの文字入力を必要とする際に呼び出すライブラリアプレットです。ソフトウェアキーボードは下画面に表示され、パスワード入力用の補助機能や、入力文字数と入力可能文字の制限機能、NG ワードフィルタ機能などを備えています。上画面には、ソフトウェアキーボードを起動したときにアプリケーションが表示していた画面がそのまま、または暗くして表示されます。
このライブラリアプレットを利用するには、ヘッダファイル(nn/swkbd.h
)のインクルードと、ライブラリファイル(libnn_swkbd
)の追加が必要です。
ライブラリアプレットの起動時に渡すパラメータは nn::swkbd::Parameter
構造体で定義されています。詳細な動作設定は、パラメータの config
メンバ(nn::swkbd::Config
構造体)に対して行いますが、設定の前に初期化を行わなければなりません。
void nn::swkbd::InitializeConfig(nn::swkbd::Config* pConfig);
pConfig
に渡された Config
構造体がデフォルト設定で初期化されます。Config
構造体のメンバに対して行うことのできる動作設定については、「アプレット仕様書」を参照してください。
このライブラリアプレットはアプリケーションで作業メモリを確保する必要があります。必要な作業メモリのサイズは動作設定によって異なり、nn::swkbd::GetSharedMemorySize()
で取得することができます。
s32 nn::swkbd::GetSharedMemorySize( const nn::swkbd::Config* pConfig, const void* pInitialStatusData = NULL, const void* pInitialLearningData = NULL);
pConfig
には、動作設定を行った Config
構造体へのポインタを渡します。
pInitialStatusData
には、前回起動したソフトウェアキーボードの動作設定で最終状態を保存していた場合、そのデータの先頭アドレスを渡すことで前回起動時の最終状態を復元することができます。復元の必要がない場合や、最終状態を保存していない場合は NULL
を指定してください。
pInitialLearningData
には、前回起動したソフトウェアキーボードの動作設定で予測変換の学習データを保存していた場合、そのデータの先頭アドレスを渡すことで前回起動時の予測変換の学習状態を復元することができます。復元の必要がない場合や、学習状態を保存していない場合は NULL
を指定してください。
作業メモリは、先頭アドレスが nn::swkbd::MEMORY_ALIGNMENT
( 4096 Byte ) のアライメント、サイズが nn::swkbd::MEMORY_UNITSIZE
( 4096 ) の倍数で確保しなければなりません。また、作業メモリにはデバイスメモリから確保したメモリ領域を指定しないでください。
パラメータ設定と作業メモリの確保が完了したら、nn::swkbd::StartKeyboardApplet()
でソフトウェアキーボードを起動することができます。
bool nn::swkbd::StartKeyboardApplet( nn::applet::AppletWakeupState* pWakeupState, nn::swkbd::Parameter* pParameter, void* pSharedMemoryAddr, size_t sharedMemorySize, const wchar_t* pInitialInputText = NULL, const nn::swkbd::UserWord* pUserWordArray = NULL, const void* pInitialStatusData = NULL, const void* pInitialLearningData = NULL nn::applet::AppTextCheckCallback callback = NULL);
pParameter
には、動作設定を行った Config
構造体をメンバに持つ Parameter
構造体へのポインタを指定します。入力された文字列などの情報は、この引数で指定された構造体に格納されます。
pSharedMemoryAddr
と pSharedMemorySize
には、作業メモリの先頭アドレスとサイズを指定します。
pInitialInputText
に、NULL
ではなく UTF-16LE の文字列を渡すと、指定された文字列が入力欄に設定された状態でソフトウェアキーボードが起動します。
pUserWordArray
には、ユーザー辞書に登録する単語の配列を指定します。
pInitialStatusData
と pInitialLearningData
には、作業メモリサイズの取得時と同じ値を指定してください。
callback
には、入力された文字列をアプリケーションでチェックする場合に使用するコールバック関数を指定します。動作設定でアプリケーションによる入力チェックを行わない場合、この引数は無視されます。
返り値が false
ならば起動に失敗しています。返り値が true
ならば起動に成功しています。
ソフトウェアキーボードのスレッドは優先度 17~20 で動作していますので、ソフトウェアキーボードの起動中でも動作し続けるスレッドの優先度の設定には注意が必要です。
12.1.3. 写真選択アプレット
ニンテンドー 3DS カメラのアルバムに登録されている写真の中から、アプリケーションで使用するデータを 1 つ選択するためのライブラリアプレットです。起動時に撮影時間や種類などの抽出条件を指定することができ、一覧表示されるデータを絞り込むことができます。なお、アプレットで選択可能な写真は SD カードに保存されているものに限られています。
このライブラリアプレットを利用するには、ヘッダファイル(nn/phtsel.h
)のインクルードと、ライブラリファイル(libnn_phtsel
)の追加が必要です。
ライブラリアプレットの起動時に渡すパラメータは nn::phtsel::Parameter
構造体で定義されています。基本動作の設定は、パラメータの m_config
メンバ(nn::phtsel::Config
構造体)に対して行い、抽出条件などの詳細な設定は m_input
メンバ(nn::phtsel::PhtselInput
構造体)で行います。m_output
メンバ(nn::phtsel::PhtselOutput
構造体)には実行結果が格納されます。設定項目などの詳細については、サンプルデモを参照してください。
アプレットの背景にアプリケーションのキャプチャ画像を表示する場合は、アプリケーションで作業メモリを確保する必要があります。必要な作業メモリのサイズは、nn::phtsel::GetWorkBufferSize()
で取得することができます。
size_t nn::phtsel::GetWorkBufferSize();
作業メモリは、先頭アドレスが 4096 バイトのアライメント、サイズが 4096 の倍数で確保しなければなりません。また、作業メモリにはデバイスメモリから確保したメモリ領域を指定しないでください。
パラメータの設定と作業メモリの確保が完了したら、nn::phtsel::StartPhtsel()
で写真選択のライブラリアプレットを起動することができます。nn::phtsel::StartPhtselNoCapture()
はアプレットの背景にアプリケーションのキャプチャ画像を表示しない場合に呼び出します。
nn::applet::AppletWakeupState nn::phtsel::StartPhtsel( nn::phtsel::Parameter* pParameter, void* pWorkBuffer); nn::applet::AppletWakeupState nn::phtsel::StartPhtselNoCapture( nn::phtsel::Parameter* pParameter);
pParameter
には、設定を行った Parameter
構造体へのポインタを指定します。pWorkBuffer
には、作業メモリの先頭アドレスを指定します。
アプリケーションに復帰したときには、pParameter
の m_output
メンバに実行結果が格納されています。
12.1.4. Mii 選択アプレット
アプリケーションで Mii を利用する際に、登録されている Mii から選択する際に呼び出すライブラリアプレットです。登録されている Mii とゲスト Mii(デフォルトの 6 体)から 1 体だけを選択することができます。ゲスト Mii を一覧に表示するかどうかや、操作画面を上画面または下画面のどちらに表示するかを選択することができます。
Mii 選択をアプリケーションで利用するには、CTR 似顔絵ライブラリ(ミドルウェア)が必要です。
使用方法は CTR 似顔絵ライブラリのドキュメントを参照してください。
12.1.5. 音声選択アプレット
アプリケーションの SE などに使用する音声を、ニンテンドー 3DS サウンドで録音した音声データから選択する際に呼び出すライブラリアプレットです。音声データは 1 つだけ選択することができます。音声の録音やデータの並べ替え、データの削除などはできません。なお、アプレットで選択可能な音声データは SD カードに保存されているものに限られています。
このライブラリアプレットを利用するには、ヘッダファイル(nn/voicesel.h
)のインクルードと、ライブラリファイル(libnn_voicesel
)の追加が必要です。
ライブラリアプレットの起動時に渡すパラメータは nn::voicesel::Parameter
構造体で定義されています。基本動作の設定は、パラメータの config
メンバ(nn::voicesel::Config
構造体)に対して行い、抽出条件などの詳細な設定は input
メンバ(nn::voicesel::Input
構造体)で行います。output
メンバ(nn::voicesel::Output
構造体)には実行結果が格納されます。設定項目などの詳細については、サンプルデモを参照してください。
パラメータの設定が完了したら、nn::voicesel::StartVoiceSel()
で音声選択のライブラリアプレットを起動することができます。
nn::applet::AppletWakeupState nn::voicesel::StartVoiceSel( nn::voicesel::Parameter* pParameter);
pParameter
には、設定を行った Parameter
構造体へのポインタを指定します。
アプリケーションに復帰したときには、pParameter
の output
メンバに実行結果が格納されています。
12.1.6. エラー・EULA アプレット
すれちがい通信などの無線による通信機能を使用する際には、EULA(ニンテンドー3DS ネットワークサービスに関する利用規約)の確認と同意をユーザーから得ている必要があります。これらの通信機能を使用するアプリケーションは、ユーザーが最新の EULA に同意しているかどうかを確認し、同意を得ていない場合は、このライブラリアプレットで EULA の表示を行って同意を得ることができます。通信機能の使用に EULA への同意は必須ですが、アプリケーションの EULA 表示は任意です。EULA を表示しない場合は、通信時にエラーを表示して本体設定への誘導を行うなどの対応をしてください。
このライブラリアプレットは EULA の表示だけでなく、エラーメッセージの表示を行うことができます。インフラストラクチャ通信関連のライブラリ(AC や FRIENDS など)ならば、エラーコードを渡すことで対応するエラーメッセージを表示します。また、アプリケーション独自のエラーメッセージを表示させることもできます。
このライブラリアプレットを利用するには、ヘッダファイル(nn/erreula.h
)のインクルードと、ライブラリファイル(libnn_erreula
)の追加が必要です。
ライブラリアプレットの起動時に渡すパラメータは nn::erreula::Parameter
構造体で定義されています。エラーコードやエラーメッセージ、動作の設定は、パラメータの config
メンバ(nn::erreula::Config
構造体)に対して行います。必ず、nn::erreula::InitializeConfig()
で初期化を行ってから、設定を行ってください。設定項目などの詳細については、「アプレット仕様書」やサンプルデモを参照してください。
パラメータの設定が完了したら、nn::erreula::StartErrEulaApplet()
でライブラリアプレットを起動することができます。
void nn::erreula::StartErrEulaApplet( nn::applet::AppletWakeupState* pWakeupState, nn::erreula::Parameter* pParameter);
pParameter
には、設定を行った Parameter
構造体へのポインタを指定します。
設定により EULA 表示が行われた場合、EULA(ネットワークサービスの利用規約)の同意シーケンスを表示し、アプリケーションには EULA への同意・非同意の結果が返されます。
アプリケーションが関わるすべてのインフラ通信機能、およびすれちがい通信機能の関数は、アプリケーションが同意を必要とするバージョンの EULA にユーザーが同意していないと、EULA 非同意エラーを返します。NEX のログイン、ダウンロードタスクの登録、すれちがいボックスの作成などはすべて対象となります。同意を必要とする EULA バージョンは、自動的に ROM に埋め込まれます。必ず EULA 同意が必要かどうかを nn::cfg::IsAgreedEula()
で確認し、EULA 未同意であれば本アプレットを呼び出すようにしてください。なお、EULA 未同意の状態で呼び出されたときのみ、正しく「EULA 同意」または「EULA 非同意」が返されます。
12.1.7. 拡張スライドパッド補正アプレット
このライブラリアプレットは、拡張スライドパッドに搭載されているスライドパッド(R)の操作感覚を補正するためのものです。拡張スライドパッドに対応するアプリケーションは、ユーザーがスライドパッド(R)の操作感覚を補正することができるように、このアプレットを起動するシーンを必ず用意しなければなりません。
SNAKE に搭載されている Cスティックは、常時接続されている拡張スライドパッドに搭載されているスライドパッド(R)として機能しています。SNAKE で動作しているアプリケーションが拡張スライドパッド補正アプレットを呼び出すと、Cスティックの補正方法を示すメッセージが表示されます。
このライブラリアプレットを利用するには、ヘッダファイル(nn/extrapad.h)のインクルードが必要です。また、CTR-SDK 11.3.x 以前を利用されている場合は、あわせてライブラリファイル(libnn_extrapad)の追加も必要となります。
ライブラリアプレットの起動時に渡すパラメータは nn::extrapad::Parameter
構造体で定義されています。動作の設定は、パラメータの config
メンバ(nn::extrapad::Config
構造体)に対して行います。必ず、nn::extrapad::InitializeConfig()
で初期化を行ってから、HOME ボタンやソフトウェアリセットへの対応を行うかを設定してください。
パラメータの設定が完了したら、nn::extrapad::StartExtraPadApplet()
でライブラリアプレットを起動することができます。
void nn::extrapad::StartExtraPadApplet( nn::applet::AppletWakeupState* pWakeupState, nn::extrapad::Parameter* pParameter);
pParameter
には、設定を行った Parameter
構造体へのポインタを指定します。
12.1.8. EC アプレット
追加コンテンツやサービスアイテムの購入・管理を行うためのライブラリアプレットです。
EC 機能の詳細については、CTR-SDK の関数リファレンスを参照してください。
12.1.9. ログインアプレット
アカウントサーバーとの通信を行い、アカウント認証処理と各種サービストークンの取得処理などをアプリケーションの代わりに行うためのライブラリアプレットです。
ログインアプレットの詳細については、「3DS プログラミングマニュアル - 無線通信編」を参照してください。
12.2. システムアプレット
システムアプレットは、基本的に HOME メニューから起動されるアプレットですが、アプリケーションから起動や利用するためのライブラリを提供しています。 アプリケーションが、システムアプレットを起動するために行わなければならない処理や、システムアプレットから復帰したときの処理は、基本的に HOME メニューの起動と復帰で行っている処理と同じです。
12.2.1. インターネットブラウザーアプレット
WEBBRS ライブラリを用いると、アプリケーションから URL を指定して、内蔵のインターネットブラウザーを起動することができます。起動方法はライブラリアプレットと類似していますが、起動したインターネットブラウザーを閉じるとアプリケーションが中断された状態で HOME メニューに戻る点が異なります。
本体更新の状況によって、インターネットブラウザーがインストールされていない本体が存在します。そのため、本体にインターネットブラウザーがインストールされているかどうかを確認してから起動する必要があります。
WEBBRS ライブラリの詳細については、CTR-SDK の関数リファレンスを参照してください。
12.2.2. Miiverse アプリ、投稿アプリ
OLV ライブラリを用いると、アプリケーションで Miiverse を活用するための機能が利用できます。アプリケーションから Miiverse アプリや投稿アプリを起動したり、投稿データなどを受信することができます。これらは名称にアプリとついていますがシステムアプレットに含まれます。
OLV ライブラリの詳細については、CTR-SDK の関数リファレンスを参照してください。
12.2.2.1. Miiverse 投稿ページからのアプリケーション起動
Miiverse の投稿ページからアプリケーションを起動することができます。
投稿ページから起動できるようにするためには、アプリケーションに以下の設定が必要です。
- bsf ファイルに
EnableMiiverseJumpArgs:True
を指定 - 投稿時に
nn::olv::UploadPostDataByPostApp()
で、フラグFLAG_APP_STARTABLE
を指定
Miiverse アプリ上での操作
上記のフラグを設定された投稿を Miiverse アプリで閲覧すると、その投稿に起動ボタンが表示され、投稿をしたユーザーも、投稿をしていないユーザーでも対応するアプリケーションを持っていれば、画面の起動ボタンから起動できます。アプリケーションを持っていないユーザーは閲覧はできますが起動はできません。