/*---------------------------------------------------------------------------* Project: Horizon File: applet_API.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: 26565 $ *---------------------------------------------------------------------------*/ #ifndef NN_APPLET_CTR_APPLET_API_H_ #define NN_APPLET_CTR_APPLET_API_H_ #include #include #include #include #include /*! @file @blief APPLET に関する API の宣言 */ namespace nn { namespace applet { namespace CTR { namespace detail { using namespace nn::applet::CTR; //---- 初期化・終了 Result Initialize( AppletAttr appletAttr = DEFAULT_APPLET_ATTRIBUTE ); void Lock(void); bool TryLock( nn::fnd::TimeSpan timeout=NO_WAIT); void Unlock(void); //---- for applet and application int CountRegisteredApplet(void); bool IsRegistered( AppletId appletId ); bool WaitForRegister( AppletId appletId, nn::fnd::TimeSpan span ); bool IsActive(void); void SetActive(void); void SetInactive(void); void SetAppletMode(void); nn::Result SaveVramSysArea(void); nn::Result RestoreVramSysArea(void); //================ // GPU権利 void AssignGpuRight( bool flag=true ); inline void ReleaseGpuRight(void) { AssignGpuRight(false); } bool IsGpuRightGiven(void); //================ // DSP権利 void AssignDspRight( bool flag = true ); inline void ReleaseDspRight( void ) { AssignDspRight(false); } //================ // sheredMemory のアタッチ void AttachSharedMemoryHandle( os::SharedMemoryBlock* sharedMemory, nn::Handle handle, size_t size, bool readOnly ); //================ // アプレットへのユーザメッセージ送り Result SendMessage( AppletId receiverId, const u8* pParam, size_t paramSize, nn::Handle handle=NN_APPLET_HANDLE_NONE, nn::fnd::TimeSpan timeout=WAIT_INFINITE ); Result TrySendMessage( AppletId receiverId, const u8* pParam, size_t paramSize, nn::Handle handle=NN_APPLET_HANDLE_NONE ); //================ // ホームボタン状態 AppletHomeButtonState GetAbsoluteHomeButtonState(void); void ClearAbsoluteHomeButtonState(void); // シャットダウン通知状態 AppletShutdownState GetShutdownState(void); void ClearShutdownState(void); // 電源ボタンクリック通知 AppletPowerButtonState GetPowerButtonState(void); void ClearPowerButtonState(void); //================ // ライブラリアプレットのプリロード Result PreloadLibraryApplet( AppletId id ); // ライブラリアプレット起動 Result PrepareToStartLibraryApplet( AppletId id ); Result StartLibraryApplet( AppletId id, const u8* pParam=NULL, size_t paramSize=0, Handle handle=NN_APPLET_HANDLE_NONE, nn::fnd::TimeSpan timeout=WAIT_INFINITE ); // 起動キャンセル Result CancelLibraryApplet(void); // アプリケーション終了 Result PrepareToCloseApplication(void); Result CloseApplication( const u8* pParam=NULL, size_t paramSize=0, Handle handle=NN_APPLET_HANDLE_NONE ); // ホームメニュー移行準備 Result PrepareToJumpToHomeMenu(void); Result JumpToHomeMenu( const u8* pParam=NULL, size_t paramSize=0, Handle handle=NN_APPLET_HANDLE_NONE ); // アプリケーションジャンプ Result JumpToOtherApplication( ProgramId programId, const u8 pParam[], const u8 pHmacBuf[] ); //================ // 引数受け取り bool ReceiveDeliverArg( u8 pParam[], u8 pHmacBuf[] ); // 動作準備状況の取得 AppletPreparationState GetAppletPreparationState(void); //================ //デバッグ用(そのうち消します) Result DebugFunc(u32 param=0); Result ArrangeAppletManagerForDebug(ProgramId programId); Result MapProgramIdForDebug(AppletId id, ProgramId programId); } } } } namespace nn { namespace applet { namespace CTR { using namespace nn::applet::CTR; //================================================================ // 初期化 //================================================================ /*! @name 初期化 @{ */ /*! @brief APPLET ライブラリの初期化を行います。 この関数を呼ぶことで他のAPPLET関数を呼ぶことが出来るようになります。 アプリケーションはこれを呼ぶことが必須です。 複数回呼ばないようにしてください。通常はプログラムの最初に記述すれば結構です。 appletAttr には描画処理があるかどうかなどを示しますが 通常は何も指定せずにデフォルト引数を用いてください。 (本SDKバージョンでの注意) 開発中にホームメニューを経由せずにアプリケーションを起動するときは、 Initialize() の後に ArrangeAppletManagerForDebug(1) を呼ぶようにしてください。 (呼ぶ位置は、applet::Initialize() の直後です。) これは、アプリケーションがホームメニューから起動されていない場合も あたかもそのアプリケーションがホームメニューから起動されたように アプレットマネージャの内部状態を変更するための関数です。 製品版では不要になりますし、開発用途でも次バージョンから廃止する予定です。 また、その際には入れたままにしても何も影響ないようにしますので、 現状は入れておいてください。常に入れておいて構いません。 @param[in] appletAttr アプレットライブラリを初期化する際のオプションです。 @return 初期化処理の結果を返します。 */ inline Result Initialize(AppletAttr appletAttr = NN_APPLET_DEFAULT_APPLET_ATTRIBUTE ) { return detail::Initialize( appletAttr ); } /*! @} */ //================================================================ // 排他制御 //================================================================ /*! @name 排他制御 @{ */ /*! :private @brief APPLET ライブラリにおける mutex をロックします。 とりあえず用意されていますが、使い方等が変更となるかもしれません。 */ inline void Lock(void) { detail::Lock(); } /*! :private @brief APPLET ライブラリにおける mutex のロックを試みます。 とりあえず用意されていますが、使い方等が変更となるかもしれません。 timeout は ロックできなかった場合に待つ時間の最大値です。 0 を指定すると即座に終了します。 @param[in] timeout タイムアウト時間を指定します。 @return ロックできれば true を、出来なければ false を返します。 */ inline bool TryLock(nn::fnd::TimeSpan timeout = NN_APPLET_NO_WAIT) { return detail::TryLock(timeout); } /*! :private @brief APPLET ライブラリにおける mutex をアンロックします。 とりあえず用意されていますが、使い方等が変更となるかもしれません。 */ inline void Unlock(void) { detail::Unlock(); } /*! @} */ //================================================================ // 情報取得 //================================================================ /*! @name 情報取得 @{ */ /*! @brief DeliverArg および HMAC 情報を取得します。 @param[out] pParam 受信用 DeliverArg バッファ @param[out] pHmacBuf 受信用 HMAC バッファ */ inline bool ReceiveDeliverArg( u8 pParam[], u8 pHmacBuf[] ) { return detail::ReceiveDeliverArg( pParam, pHmacBuf ); } /*! :private @brief 登録されている APPLET の数を数えます。 アプリケーション自体も 1 つと数えます。 @return 登録されている APPLET の数を返します。 */ inline int CountRegisteredApplet(void) { return detail::CountRegisteredApplet(); } /*! @brief 指定した ID のアプレットが登録されているか確認します。 @param[in] appletId アプレット ID @return 登録されていれば true を、されていなければ false 返します。 */ inline bool IsRegistered( AppletId appletId ) { return detail::IsRegistered( appletId ); } /*! @brief アプリケーションが現在動作中かを調べます。 @detail アプリケーションプログラムが動作しているときは active ですが、 ライブラリアプレットを呼び出したり、ホームメニューに遷移して、 動作が中断されているときは activeではありません。 スリープ問い合わせのコールバックなど、activeでなくても呼び出されるものもあります。 そのコールバック中で、現在アプリケーションが動作中かを判定することができます。 @return active ならば true を、そうでないならば false を返します。 */ inline bool IsActive(void) { return detail::IsActive(); } /*! :private @brief アプリケーションをアクティブにします。 */ inline void SetActive(void) { detail::SetActive(); } /*! :private @brief アプリケーションを非アクティブにします。 */ inline void SetInactive(void) { detail::SetInactive(); } /*! :private @brief アプリケーションのアプレット ID を取得します。 アプリケーションでは返る値が固定です。 @return アプレット ID を返します。 */ AppletId GetId(void); /*! :private @brief アプリケーションのアプレットアトリビュートを取得します。 取得できるのは Initialize() 時に指定したアトリビュートとなります。 @return アトリビュートを返します。 */ AppletAttr GetAttribute(void); /*! @} */ //================================================================ // 動作制御 //================================================================ /*! @name 動作制御 @{ */ /*! @brief 指定した ID のアプレットが登録されるのを、指定時間だけ待ちます。 NN_APPLET_WAIT_INFINITE を指定した場合は、登録完了まで待ちます。 すなわち返り値は必ず true です。 NN_APPLET_NO_WAIT を指定した場合は、処理がすぐに戻ります。 登録されていたかどうかで返り値は true か false になります。 @param[in] appletId アプレット ID @param[in] span 待ち時間の上限 @return 登録されていれば true を、されていなければ false を返します。 */ inline bool WaitForRegister( AppletId appletId, nn::fnd::TimeSpan span = NN_APPLET_WAIT_INFINITE ) { return detail::WaitForRegister( appletId, span ); } //================================================================ // 描画権 //================================================================ /*! @name 描画権 @{ */ /*! :private @brief アプリケーションが描画権限を与えられているかを調べます。 @return 描画権限を与えられていれば true を、そうでなければ false を返します。 */ inline bool IsGpuRightGiven(void) { return detail::IsGpuRightGiven(); } /*! @brief アプリケーションが描画することを宣言します。 この関数は、ライブラリアプレットやホームメニューなどから切り替わった後に、 自らが描画を行うことを宣言するものです。 通常、アプリケーションが呼ぶ必要はありません。 @param[in] flag true なら取得、false なら放棄 */ inline void AssignGpuRight( bool flag = true ) { detail::AssignGpuRight(flag); } /*! @brief アプリケーションが他のプログラムに描画を切り替えることを宣言します。 この関数は、ライブラリアプレットやホームメニューなどに切り替わる際に、 アプリケーションでの描画をやめることを宣言するものです。 通常、アプリケーションが呼ぶ必要はありません。 */ inline void ReleaseGpuRight(void) { detail::AssignGpuRight(false); } /*! @} */ //================================================================ // DSP使用権 //================================================================ /*! @name DSP使用権 @{ */ /*! :private @brief DSP の使用権を取得、放棄します。 必要に応じて、内部で DSP 処理を中断、再開します。 @param[in] flag true なら再開、false なら中断 */ inline void AssignDspRight( bool flag = true ) { detail::AssignDspRight(flag); } /*! :private @brief DSP の使用権を放棄します。 必要に応じて、内部で DSP での処理を一時中断します。 */ inline void ReleaseDspRight( void ) { detail::AssignDspRight(false); } /*! @} */ /*! :private @brief 共有メモリハンドルをアタッチします。 @param[out] sharedMemory 共有メモリブロックポインタ @param[in] handle ハンドル @param[in] size 共有メモリのサイズ @param[in] readOnly 読み取り専用フラグ */ inline void AttachSharedMemoryHandle( os::SharedMemoryBlock* sharedMemory, nn::Handle handle, size_t size, bool readOnly ) { detail::AttachSharedMemoryHandle( sharedMemory, handle, size, readOnly ); } //================================================================ // メッセージ //================================================================ /*! @name メッセージ @{ */ /*! :private @brief アプレットへのメッセージ送信を行います。 @param[in] receiverId 宛先のアプレット ID @param[in] pParam アプレットへ送るパラメータバッファ @param[in] paramSize アプレットへ送るパラメータバッファのサイズ @param[in] handle アプレットへ送るハンドル @param[in] timeout タイムアウト時間 @return 処理結果を返します。 */ inline Result SendMessage( AppletId receiverId, const u8* pParam, size_t paramSize, nn::Handle handle=NN_APPLET_HANDLE_NONE, nn::fnd::TimeSpan timeout=WAIT_INFINITE ) { return detail::SendMessage( receiverId, pParam, paramSize, handle, timeout ); } /*! :private @brief アプレットへのメッセージ送信を行います。 @param[in] receiverId 宛先のアプレット ID @param[in] pParam アプレットへ送るパラメータバッファ @param[in] paramSize アプレットへ送るパラメータバッファサイズ @param[in] handle アプレットへ送るハンドル @return 処理結果を返します。 */ inline Result TrySendMessage( AppletId receiverId, const u8* pParam, size_t paramSize, nn::Handle handle=NN_APPLET_HANDLE_NONE ) { return detail::TrySendMessage( receiverId, pParam, paramSize, handle ); } /*! @} */ /*! :private @brief 現在のホームボタンの状態を取得します。 @ref GetHomeButtonState 関数よりも正確な値が得られます。 @return 状態を返します。 */ inline AppletHomeButtonState GetAbsoluteHomeButtonState(void) { return detail::GetAbsoluteHomeButtonState(); } /*! :private @brief ホームボタンの状態をクリアします。 */ inline void ClearAbsoluteHomeButtonState(void) { return detail::ClearAbsoluteHomeButtonState(); } //================================================================ // シャットダウン //================================================================ /*! @name シャットダウン @{ */ /*! :private @brief シャットダウン状態を取得します。 @return 状態を返します。 */ inline AppletShutdownState GetShutdownState(void) { return detail::GetShutdownState(); } /*! :private @brief シャットダウン状態をクリアします。 */ inline void ClearShutdownState(void) { detail::ClearShutdownState(); } /*! @} */ //================================================================ // 電源ボタン //================================================================ /*! @name 電源ボタン @{ */ /*! :private @brief 電源ボタンの状態を取得します。 @return 状態を返します。 */ inline AppletPowerButtonState GetPowerButtonState(void) { return detail::GetPowerButtonState(); } /*! :private @brief 電源ボタンの状態をクリアします。 */ inline void ClearPowerButtonState(void) { detail::ClearPowerButtonState(); } /*! @} */ //================================================================ // ライブラリアプレット・プリロードと終了 //================================================================ /*! @name ライブラリアプレットのプリロードと終了 @{ */ /*! @brief 起動するライブラリアプレットのプリロードを行います。 @param[in] id ライブラリアプレットのアプレット ID @return 処理結果を返します。 */ inline Result PreloadLibraryApplet( AppletId id ) { return detail::PreloadLibraryApplet(id); } /*! @brief プリロードされているライブラリアプレットを終了します。 @return 処理結果を返します。 */ inline Result CancelLibraryApplet(void) { return detail::CancelLibraryApplet(); } /*! @} */ //================================================================ // ライブラリアプレット・起動 //================================================================ /*! @name ライブラリアプレット起動 @{ */ /*! @brief ライブラリアプレットを起動する準備を行います。 ライブラリアプレットを呼び出す準備を行う関数です。 この関数が呼ばれた後に StartLibraryApplet() を呼ぶことでライブラリアプレットを起動します。 @param[in] id ライブラリアプレットのアプレット ID @return 処理結果を返します。 */ inline Result PrepareToStartLibraryApplet( AppletId id ) { return detail::PrepareToStartLibraryApplet(id); } /*! @brief ライブラリアプレットを起動します。 ライブラリアプレットを呼び出す関数です。 この関数の前に PrepareToStartLibraryApplet() が呼ばれている必要があります。 この関数を呼んだ後に、WaitForStarting() で起動待ちを行ってください。 @param[in] id ライブラリアプレットのアプレット ID @param[in] pParam ライブラリアプレットに送るパラメータバッファ @param[in] paramSize ライブラリアプレットに送るパラメータバッファサイズ @param[in] handle ライブラリアプレットに送るハンドル @param[in] timeout タイムアウト時間 @return 処理結果を返します。 */ inline Result StartLibraryApplet( AppletId id, const u8* pParam=NULL, size_t paramSize=0, Handle handle=NN_APPLET_HANDLE_NONE, nn::fnd::TimeSpan timeout=WAIT_INFINITE ) { return detail::StartLibraryApplet(id, pParam, paramSize, handle, timeout); } /*! @} */ //================================================================ // アプリケーション終了 //================================================================ /*! @name アプリケーション終了 @{ */ /*! @brief アプリケーションを終了する準備を行います。 この関数の後に CloseApplication() を呼び出すことでアプリケーションが終了します。 @return 処理結果を返します。 */ inline Result PrepareToCloseApplication(void) { return detail::PrepareToCloseApplication(); } /*! @brief アプリケーションを終了します。 この関数の前に PrepareToCloseApplication() が呼ばれている必要があります。 終了した後は、制御がホームメニューに移ります。 この関数からは戻ってきません。 @param[in] pParam パラメータバッファ @param[in] paramSize パラメータバッファサイズ @param[in] handle ハンドル @return 処理結果を返します。 */ inline Result CloseApplication( const u8* pParam=NULL, size_t paramSize=0, Handle handle=NN_APPLET_HANDLE_NONE ) { return detail::CloseApplication( pParam, paramSize, handle ); } /*! @} */ //================================================================ // ホームメニュー //================================================================ /*! @name ホームメニュー @{ */ /*! @brief ホームメニューへ移行する準備を行います。 この関数の後に CloseApplication() を呼ぶことでホームメニューへ移行します。 @return 処理結果を返します。 */ inline Result PrepareToJumpToHomeMenu(void) { return detail::PrepareToJumpToHomeMenu(); } /*! @brief ホームメニューへ移行します。 この関数の前に PrepareToJumpToHomeMenu() が呼ばれている必要があります。 この関数を呼んだ後に、WaitForStarting() で起動待ちを行ってください。 @param[in] pParam ホームメニューへ送るパラメータバッファ @param[in] paramSize ホームメニューへ送るパラメータバッファのサイズ @param[in] handle ホームメニューへ送るハンドル @return 処理結果を返します。 */ inline Result JumpToHomeMenu( const u8* pParam=NULL, size_t paramSize=0, Handle handle=NN_APPLET_HANDLE_NONE ) { return detail::JumpToHomeMenu( pParam, paramSize, handle ); } /*! @} */ //================================================================ // アプリケーションジャンプ //================================================================ /*! @name アプリケーションジャンプ @{ */ /*! :private @brief 自身を終了し、他のアプリケーションを起動します。 @param[in] programId 起動するアプリケーションのプログラム ID @param[in] pParam 起動するアプリケーションに渡す DeliverArg バッファ @param[in] pHmacBuf 起動するアプリケーションに渡す HMAC バッファ @return 処理結果を返します。 */ inline Result JumpToOtherApplication( ProgramId programId, const u8 pParam[]=NULL, const u8 pHmacBuf[]=NULL ) { return detail::JumpToOtherApplication( programId, pParam, pHmacBuf ); } /*! @} */ //================================================================ // 非公開 //================================================================ /*! :private @brief アプレットマネージャの遷移の準備状態を取得します。 @return 状態を返します。 */ inline AppletPreparationState GetAppletPreparationState(void) { return detail::GetAppletPreparationState(); } /*! :private @brief アプリケーションがアプレットであることを宣言します。 */ inline void SetAppletMode(void) { detail::SetAppletMode(); } /*! :private @brief VRAM のシステム領域を退避させます。 @return 処理結果を返します。 */ inline nn::Result SaveVramSysArea(void) { return detail::SaveVramSysArea(); } /*! :private @brief VRAM のシステム領域を復元します。 @return 処理結果を返します。 */ inline nn::Result RestoreVramSysArea(void) { return detail::RestoreVramSysArea(); } /*! @} */ //================================================================ // デバッグ用途 //================================================================ /*! @name 開発用途 @{ */ inline Result DebugFunc(u32 param=0) { return detail::DebugFunc(param); } /*! :private @brief (開発用途) アプレットマネージャの状態を調整します。 通常アプリケーションは、ホームメニューから起動されるのですが 開発中はそうでないケースがあります。 そのときに、あたかもそのアプリケーションがホームメニューから起動されたように アプレットマネージャの内部状態を変更するためにこの関数が用意されています。 製品版では不要になりますし、開発用途でも将来的に廃止する予定です。 また、その際には入れたままにしても何も影響ないようにしますので、 現状は入れておいてください。 お手数ですが宜しくお願いいたします。 呼ぶ位置は、applet::Initialize() の直後です。 programId は、アプリケーションのプログラムIDを入れるための引数ですが、 現状、0以外の値ならば何であっても問題ありません。 @param[in] programId アプリケーションのプログラム ID (現在、0以外なら何でも構いません) */ inline Result ArrangeAppletManagerForDebug( ProgramId programId ) { return detail::ArrangeAppletManagerForDebug(programId); } /*! @} */ } } } /*! @defgroup nn_applet applet @brief APPLET を扱うモジュールです。 @{ */ #include /*! @brief APPLET ライブラリの初期化を行い、APPLET を登録します。 @detail 対応する C++ 関数 @ref nn::applet::CTR::Initialize() を参照してください。 */ NN_EXTERN_C inline nn::Result nnappletInitialize( AppletAttr appletAttr = NN_APPLET_DEFAULT_APPLET_ATTRIBUTE) { return nn::applet::CTR::Initialize(appletAttr); } /*! @brief APPLET ライブラリにおける mutex をロックします。 @detail 対応する C++ 関数 @ref nn::applet::CTR::Lock() を参照してください。 */ NN_EXTERN_C inline void nnappletLock(void) { nn::applet::CTR::Lock(); } /*! @brief APPLET ライブラリにおける mutex のロックを試みます。 @detail 対応する C++ 関数 @ref nn::applet::CTR::TryLock() を参照してください。 */ NN_EXTERN_C inline bool nnappletTryLock(nn::fnd::TimeSpan timeout=NN_APPLET_NO_WAIT) { return nn::applet::CTR::TryLock(timeout); } /*! @brief APPLET ライブラリにおける mutex をアンロックします。 @detail 対応する C++ 関数 @ref nn::applet::CTR::Unlock() を参照してください。 */ NN_EXTERN_C inline void nnappletUnlock(void) { nn::applet::CTR::Unlock(); } //---------------------------------------------------------------- /*! @brief 登録されている APPLET の数を数えます。 @detail 対応する C++ 関数 @ref nn::applet::CTR::CountRegisteredApplet() を参照してください。 */ NN_EXTERN_C inline int nnappletCountRegisteredApplet(void) { return nn::applet::CTR::CountRegisteredApplet(); } /*! @brief APPLET が登録されているかを調べます。 @detail 対応する C++ 関数 @ref nn::applet::CTR::IsRegistered() を参照してください。 */ NN_EXTERN_C inline bool nnappletIsRegistered( AppletId appletId ) { return nn::applet::CTR::IsRegistered( appletId ); } NN_EXTERN_C inline bool nnappletWaitForRegister( AppletId appletId, nn::fnd::TimeSpan span=NN_APPLET_WAIT_INFINITE ) { return nn::applet::CTR::WaitForRegister( appletId, span ); } /*! @brief APPLET が現在動作選択されて active かを調べます。 @detail 対応する C++ 関数 @ref nn::applet::CTR::IsActive() を参照してください。 */ NN_EXTERN_C inline bool nnappletIsActive(void) { return nn::applet::CTR::IsActive(); } NN_EXTERN_C inline void nnappletAssignGpuRight(bool flag=true) { nn::applet::CTR::AssignGpuRight(flag); } NN_EXTERN_C inline void nnappletReleaseGpuRight(void) { nn::applet::CTR::AssignGpuRight(false); } /*! @brief APPLET が現在描画権限を与えられているかを調べます。 @detail 対応する C++ 関数 @ref nn::applet::CTR::IsGpuRightGiven() を参照してください。 */ NN_EXTERN_C inline bool nnappletIsGpuRightGiven(void) { return nn::applet::CTR::IsGpuRightGiven(); } NN_EXTERN_C inline void nnappletAttachSharedMemoryHandle( nn::os::SharedMemoryBlock* sharedMemory, nn::Handle handle, size_t size, bool readOnly ) { nn::applet::CTR::AttachSharedMemoryHandle( sharedMemory, handle, size, readOnly ); } #if 0 NN_EXTERN_C inline void nnappletSetExitCallback( AppletExitCallback callback, uptr parameter ) { nn::applet::CTR::SetExitCallback( callback, parameter ); } #endif /*! @} */ #endif // ifndef NN_APPLET_CTR_APPLET_API_H_