/*---------------------------------------------------------------------------* Project: Horizon File: applet_Wrapper.h Copyright (C)2010 Nintendo Co., Ltd. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 31695 $ *---------------------------------------------------------------------------*/ #ifndef NN_APPLET_CTR_APPLET_WRAPPER_H_ #define NN_APPLET_CTR_APPLET_WRAPPER_H_ #include #include #include #include namespace nn { namespace applet { namespace CTR { namespace detail { AppletWakeupState WaitForStarting( AppletId* pSenderId=NULL, u8* pParam=NULL, size_t paramSize=0, s32* pReadLen=NULL, nn::Handle *pHandle=NULL, nn::fnd::TimeSpan span=NN_APPLET_WAIT_INFINITE ); bool ProcessHomeButton(void); } } } } namespace nn { namespace applet { namespace CTR { /*! @name ホームメニュー @{ */ /*! @brief ホームボタンの状態を取得します。 nn::applet::CTR::HOME_BUTTON_NONE, HOME_BUTTON_SINGLE_PRESSED, HOME_BUTTON_DOUBLE_PRESSED のいずれかを返します。 nn::applet::CTR::HOME_BUTTON_NONE 以外の状態のときには アプリケーションで必要な処理を行った後に、 ProcessHomeButton() を呼んでください。 なお、通常はホームボタン処理が必要かを調べる IsExpectedToProcessHomeMenu() を 使ってください。そちらは、ホームボタンによるホームメニュー遷移の必要性だけではなく、 他のアプレットからのシーケンスによるホームボタン同様のホームメニュー遷移要求も 考慮しています。 この関数で取得できる値は、一旦 applet::HOME_BUTTON_NONE 以外の値になると、 applet::GetHomeButtonState() でクリアする(applet::HOME_BUTTON_NONEにする) まで 同じ値を持ち続けます。 @return 状態を返します。 */ AppletHomeButtonState GetHomeButtonState(void); /*! @brief ホームボタンの状態をクリアします。 applet::GetHomeButtonState() で取得できる値をクリアします。 また、この関数はホームボタン処理の遷移と電源ボタンやスリープとの 排他の終了をシステムに知らせるものでもあります。 WaitForStarting() からアプリケーションに戻ったときに、 そのまま終了する場合は特に呼ぶ必要はありませんが アプリケーションを続行する場合には、この関数を呼んでおかなければ 電源ボタンやスリープといった他の遷移要素が有効になりませんので 注意してください。 */ void ClearHomeButtonState(void); // 内部関数(非公開) bool IsExpectedToJumpToHomeMenu(void); // 内部関数(非公開) void SetExpectationToJumpToHomeMenu( bool sw ); /*! @brief ホームボタンの処理を行う要求があるかを調べます。 返り値が true なら、ホームボタン押しによるメニュー遷移か、 他のアプレットからのシーケンスでホームボタン同様のホームメニュー遷移要求が あることを示します。 この場合は、速やかに ProcessHomeButton() を呼び出して ホームボタン処理を行って、必要なら WaitForStarting() で待ちうけを行ってください。 必要かどうかは ProcessHomeButton() の返り値によります。 @return 処理要求です。 */ bool IsExpectedToProcessHomeButton(void); /*! @} */ /*! @name ホームメニュー @{ */ /*! @brief ホームメニュー遷移処理を行います。 この関数は IsExpectedToProcesHomeButton() でホームメニュー遷移が必要であった場合の ホームメニュー遷移処理を行うためのものです。 関数名は ProcessHomeButton() ですが、ホームボタン以外にも他のアプレットからの 終了要求も考慮します。 返り値は、呼び出し後に WaitForStarting() で待ち受けを行う必要があるかどうかを示します。 true の場合は WaitForStarting() を呼んでください。 false の場合は呼ぶ必要はありません。(が、呼んでもウェイトせずに問題なく抜けるようになっています) なお、前バージョンまでの互換性のために全く同じ動作をする ProcessHomeButtonIfPrepared() が残されていますが、こちらの ProcessHomeButton()を 使うようにしてください。 @return ウェイトする必要があるかどうかを返します。 true の場合 WaitForStarting() で待ちうけが必要です。false の場合は待つ必要はありません。 */ inline bool ProcessHomeButton(void) { return detail::ProcessHomeButton(); } // ↓この関数は古い表記です。変わりにProcessHomeButton()を使ってください。 // (互換性のために本バージョンでは残してあります) inline bool ProcessHomeButtonIfPrepared(void) { return detail::ProcessHomeButton(); } /*! @} */ /*! @name スリープ @{ */ /*! @brief スリープ通知状態を取得します。 nn::applet::CTR::NOTIFY_NONE, NOTIFY_SLEEP_QUERY, NOTIFY_SLEEP_ACCEPT, NOTIFY_SLEEP_REJECT, NOTIFY_SLEEP_ACCEPTED, NOTIFY_AWAKE のいずれかを返します。 アプリケーションがスリープ問い合わせのコールバックに対し "保留"(nn::applet::CTR::REPLY_LATER) を返した後は nn::applet::CTR::NOTIFY_QUERY となります。 このときには、速やかに ReplySleepQuery() で nn::applet::CTR::REPLY_ACCEPT か、nn::applet::CTR::REPLY_REJECT のいずれかを ReplySleepQuery() で 返してください。 コールバックに対し、"あるいは ReplySleepQuery() で 承諾"(nn::applet::CTR::REPLY_ACCEPT) を返したした後は nn::applet::CTR::NOTIFY_ACCEPT となります。 コールバックに対し、"あるいは ReplySleepQuery() で 拒否"(nn::applet::CTR::REPLY_REJECT) を返したした後は nn::applet::CTR::NOTIFY_REJECT となります。 スリープに入る直前に、nn::applet::CTR::NOTIFY_SLEEP_ACCEPTED となります。 ただしアプリケーションでこの値を使用することはほぼ不可能です。 スリープから起床した後は nn::applet::CTR::NOTIFY_AWAKE となります。 @return 状態を返します。 */ AppletSleepNotificationState GetSleepNotificationState(void); inline bool IsExpectedToReplySleepQuery(void) { return (GetSleepNotificationState() == nn::applet::CTR::NOTIFY_SLEEP_QUERY)? true: false; } /*! @brief スリープ通知状態をクリアします。 GetSleepNotificationState() で取得できる状態が、 nn::applet::CTR::NOTIFY_NONE となります。 システムでは、この状態を用いて何かの動作を行ってはいませんので、 アプリケーションの都合がよければどのようなタイミングで状態を変更しても 問題はありません。 */ void ClearSleepNotificationState(void); /*! @brief スリープ問い合わせへの返答を行います。 この関数は、SetSleepQueryCallback() で設定されるスリープ問い合わせの コールバックで、アプリケーションが "保留"(nn::CTR::applet::REPLY_LATER) を 返した後に、改めて問い合わせの返答を行うものです。 "承諾"( nn::applet::CTR::REPLY_ACCEPT) または "拒否"(nn::applet::CTR::REPLY_REJECT) のいずれかを指定してください。 @param[in] reply 返答 */ void ReplySleepQuery( AppletQueryReply reply ); /*! @} */ /*! @name コールバック設定 @{ */ /*! @brief ホームボタン検出コールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetHomeButtonCallback( AppletHomeButtonCallback callback, uptr arg=0 ); /*! @brief メッセージ受け取りコールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetReceiveMessageCallback( AppletMessageCallback callback, uptr arg=0 ); /*! @brief 電源ボタン検出コールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetPowerButtonCallback( AppletPowerButtonCallback callback, uptr arg=0 ); /*! :private @brief 共有メモリ要求受け取りコールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetRequestMemoryCallback( AppletRequestMemoryCallback callback, uptr arg=0 ); /*! :private @brief 共有メモリ解放コールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetReleaseMemoryCallback( AppletReleaseMemoryCallback callback, uptr arg=0 ); /*! :private @brief DSP スリープコールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetDspSleepCallback( AppletDspSleepCallback callback, uptr arg=0 ); /*! :private @brief DSP スリープ復帰コールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetDspWakeUpCallback( AppletDspWakeUpCallback callback, uptr arg=0 ); /*! @brief スリープ問い合わせコールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetSleepQueryCallback( AppletSleepQueryCallback callback, uptr arg=0 ); /*! @brief スリープキャンセルコールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetSleepCanceledCallback( AppletSleepCanceledCallback callback, uptr arg=0 ); /*! @brief スリープ復帰コールバックを設定します。 なお、スリープから復帰したあとに nngxStartLcdDisplay() で LCD の復帰を行うのはアプリケーションで行う必要があります。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetAwakeCallback( AppletAwakeCallback callback, uptr arg=0 ); /*! @brief シャットダウン通知コールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetShutdownCallback( AppletShutdownCallback callback, uptr arg=0 ); /*! :private @brief アプレット終了時コールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetCloseAppletCallback( AppletCloseAppletCallback callback, uptr arg=0 ); /*! @brief アプリケーションからホームメニュー/システムアプレット遷移時のコールバックを設定します。 @param[in] callback コールバック @param[in] arg コールバックへの引数 */ void SetTransitionCallback( AppletTransitionCallback callback, uptr arg=0 ); /*! @} */ /*! @name 動作制御 @{ */ /*! @brief 自身の開始イベントが来るのを待ちます。 開始のイベントを受け取るまでこの関数から戻ります。 関数から戻る際には、AppletWakeupState 列挙型の値が返りますが、その値によって 以降の動作(通常再開するとか、アプリケーションを終了するとか)を決定する必要があります。 例えば、nn::applet::CTR::WAKEUP_BY_CANCEL を受け取った場合は、 速やかにアプリケーションを終了させる必要があります。 また電源ボタンのクリックが検出されている場合 (IsExpectedToProcessPowerButton() == true である場合) は 返り値によらずアプリケーションを終了する必要があります。 また、ホームボタン遷移と他の遷移のロックを解除するために その後アプリケーションを続行する場合は ClearHomeButtonState() を呼ぶ必要があります。 (ClearHomeButtonState() のリファレンスを参照してください) @param[out] pSenderId イベント送信元の アプレットID @param[out] pParam パラメータバッファ @param[in] paramSize パラメータバッファサイズ @param[out] pReadLen 読み込みサイズ @param[out] pHandle ハンドラ @param[in] timeout タイムアウト時間 @return 起床理由を返します。 */ inline AppletWakeupState WaitForStarting( AppletId* pSenderId=NULL, u8* pParam=NULL, size_t paramSize=0, s32* pReadLen=NULL, nn::Handle *pHandle=NULL, nn::fnd::TimeSpan timeout=NN_APPLET_WAIT_INFINITE ) { return detail::WaitForStarting( pSenderId, pParam, paramSize, pReadLen, pHandle, timeout ); } /*! @} */ bool IsAppletPreloaded( AppletId id ); void WaitForAppletPreloaded( AppletId id ); /*! @name ライブラリアプレットのプリロードと終了 @{ */ /*! :private @brief ライブラリアプレットのプリロードが完了したかを調べます。 @param[in] id ライブラリアプレットのアプレット ID @return 終了していれば true となります。 */ inline bool IsLibraryAppletPreloaded(void) { return IsAppletPreloaded( APPLIB_APPLET_ID ); } /*! :private @brief ライブラリアプレットのプリロードが完了するまで待ちます。 */ inline void WaitForLibraryAppletPreloaded(void) { WaitForAppletPreloaded( APPLIB_APPLET_ID ); } /*! @} */ /*! @brief スリープを可能にします。 この関数でスリープを可能にしておかなければ、 アプリケーションがアクティブであるときに、 スリープ問い合わせコールバック(applet::SetSleepQueryCallback() で設定します)に どのように返答しても、REPLY_REJECT(却下) 扱いとなります。 なお、applet::Enable() で applet::EnableSleep(false) を行っています。 @param[in] isSleepCheck ふたの状態をみてスリープするかどうかを表します。true ならば行います。 */ void EnableSleep( bool isSleepCheck=true ); /*! @brief スリープを禁止にします。 この関数でスリープを禁止にしておくと、アプリケーションがアクティブであるときに、 スリープ問い合わせコールバック(applet::SetSleepQueryCallback() で設定します)に どのように返答しても、REPLY_REJECT(却下) 扱いとなります。 @param[in] isReplyReject true の場合、スリープの問い合わせが来ていることを考慮して applet::ReplySleepQuery( applet::REPLY_REJECT ) を呼びます。 */ void DisableSleep( bool isReplyReject=true ); bool IsEnableSleep(); } } } #include NN_EXTERN_C inline AppletHomeButtonState nnappletGetHomeButtonState(void) { return nn::applet::CTR::GetHomeButtonState(); } NN_EXTERN_C inline void nnappletClearHomeButtonState(void) { nn::applet::CTR::ClearHomeButtonState(); } NN_EXTERN_C inline AppletWakeupState nnappletWaitForStarting( AppletId* pSenderId=NULL, u8* pParam=NULL, size_t paramSize=0, s32* pReadLen=NULL, nn::Handle *pHandle=NULL ) { return nn::applet::CTR::WaitForStarting( pSenderId, pParam, paramSize, pReadLen, pHandle ); } NN_EXTERN_C inline bool nnappletProcessHomeButton(void) { return nn::applet::CTR::ProcessHomeButton(); } #endif // ifndef NN_APPLET_CTR_APPLET_WRAPPER_H_