/** * @file apt.h * @brief APT (Applet) service. */ #pragma once /** * @brief NS Application IDs. * * Retrieved from http://3dbrew.org/wiki/NS_and_APT_Services#AppIDs */ typedef enum { APPID_NONE = 0, APPID_HOMEMENU = 0x101, ///< Home Menu APPID_CAMERA = 0x110, ///< Camera applet APPID_FRIENDS_LIST = 0x112, ///< Friends List applet APPID_GAME_NOTES = 0x113, ///< Game Notes applet APPID_WEB = 0x114, ///< Internet Browser APPID_INSTRUCTION_MANUAL = 0x115, ///< Instruction Manual applet APPID_NOTIFICATIONS = 0x116, ///< Notifications applet APPID_MIIVERSE = 0x117, ///< Miiverse applet (olv) APPID_MIIVERSE_POSTING = 0x118, ///< Miiverse posting applet (solv3) APPID_AMIIBO_SETTINGS = 0x119, ///< Amiibo settings applet (cabinet) APPID_APPLICATION = 0x300, ///< Application APPID_ESHOP = 0x301, ///< eShop (tiger) APPID_SOFTWARE_KEYBOARD = 0x401, ///< Software Keyboard APPID_APPLETED = 0x402, ///< appletEd APPID_PNOTE_AP = 0x404, ///< PNOTE_AP APPID_SNOTE_AP = 0x405, ///< SNOTE_AP APPID_ERROR = 0x406, ///< error APPID_MINT = 0x407, ///< mint APPID_EXTRAPAD = 0x408, ///< extrapad APPID_MEMOLIB = 0x409, ///< memolib } NS_APPID; /// APT applet position. typedef enum { APTPOS_NONE = -1, ///< No position specified. APTPOS_APP = 0, ///< Application. APTPOS_APPLIB = 1, ///< Application library (?). APTPOS_SYS = 2, ///< System applet. APTPOS_SYSLIB = 3, ///< System library (?). APTPOS_RESIDENT = 4, ///< Resident applet. } APT_AppletPos; typedef u8 APT_AppletAttr; struct PtmWakeEvents; /// Create an APT_AppletAttr bitfield from its components. static inline APT_AppletAttr aptMakeAppletAttr(APT_AppletPos pos, bool manualGpuRights, bool manualDspRights) { return (pos&7) | (manualGpuRights ? BIT(3) : 0) | (manualDspRights ? BIT(4) : 0); } /// APT query reply. typedef enum { APTREPLY_REJECT = 0, APTREPLY_ACCEPT = 1, APTREPLY_LATER = 2, } APT_QueryReply; /// APT signals. typedef enum { APTSIGNAL_NONE = 0, ///< No signal received. APTSIGNAL_HOMEBUTTON = 1, ///< HOME button pressed. APTSIGNAL_HOMEBUTTON2 = 2, ///< HOME button pressed (again?). APTSIGNAL_SLEEP_QUERY = 3, ///< Prepare to enter sleep mode. APTSIGNAL_SLEEP_CANCEL = 4, ///< Triggered when ptm:s GetShellStatus() returns 5. APTSIGNAL_SLEEP_ENTER = 5, ///< Enter sleep mode. APTSIGNAL_SLEEP_WAKEUP = 6, ///< Wake from sleep mode. APTSIGNAL_SHUTDOWN = 7, ///< Shutdown. APTSIGNAL_POWERBUTTON = 8, ///< POWER button pressed. APTSIGNAL_POWERBUTTON2 = 9, ///< POWER button cleared (?). APTSIGNAL_TRY_SLEEP = 10, ///< System sleeping (?). APTSIGNAL_ORDERTOCLOSE = 11, ///< Order to close (such as when an error happens?). } APT_Signal; /// APT commands. typedef enum { APTCMD_NONE = 0, ///< No command received. APTCMD_WAKEUP = 1, ///< Applet should wake up. APTCMD_REQUEST = 2, ///< Source applet sent us a parameter. APTCMD_RESPONSE = 3, ///< Target applet replied to our parameter. APTCMD_EXIT = 4, ///< Exit (??) APTCMD_MESSAGE = 5, ///< Message (??) APTCMD_HOMEBUTTON_ONCE = 6, ///< HOME button pressed once. APTCMD_HOMEBUTTON_TWICE = 7, ///< HOME button pressed twice (double-pressed). APTCMD_DSP_SLEEP = 8, ///< DSP should sleep (manual DSP rights related?). APTCMD_DSP_WAKEUP = 9, ///< DSP should wake up (manual DSP rights related?). APTCMD_WAKEUP_EXIT = 10, ///< Applet wakes up due to a different applet exiting. APTCMD_WAKEUP_PAUSE = 11, ///< Applet wakes up after being paused through HOME menu. APTCMD_WAKEUP_CANCEL = 12, ///< Applet wakes up due to being cancelled. APTCMD_WAKEUP_CANCELALL = 13, ///< Applet wakes up due to all applets being cancelled. APTCMD_WAKEUP_POWERBUTTON = 14, ///< Applet wakes up due to POWER button being pressed (?). APTCMD_WAKEUP_JUMPTOHOME = 15, ///< Applet wakes up and is instructed to jump to HOME menu (?). APTCMD_SYSAPPLET_REQUEST = 16, ///< Request for sysapplet (?). APTCMD_WAKEUP_LAUNCHAPP = 17, ///< Applet wakes up and is instructed to launch another applet (?). } APT_Command; /// APT capture buffer information. typedef struct { u32 size; u32 is3D; struct { u32 leftOffset; u32 rightOffset; u32 format; } top, bottom; } aptCaptureBufInfo; /// APT hook types. typedef enum { APTHOOK_ONSUSPEND = 0, ///< App suspended. APTHOOK_ONRESTORE, ///< App restored. APTHOOK_ONSLEEP, ///< App sleeping. APTHOOK_ONWAKEUP, ///< App waking up. APTHOOK_ONEXIT, ///< App exiting. APTHOOK_COUNT, ///< Number of APT hook types. } APT_HookType; /// APT hook function. typedef void (*aptHookFn)(APT_HookType hook, void* param); /// APT hook cookie. typedef struct tag_aptHookCookie { struct tag_aptHookCookie* next; ///< Next cookie. aptHookFn callback; ///< Hook callback. void* param; ///< Callback parameter. } aptHookCookie; /// APT message callback. typedef void (*aptMessageCb)(void* user, NS_APPID sender, void* msg, size_t msgsize); /// Initializes APT. Result aptInit(void); /// Exits APT. void aptExit(void); /** * @brief Sends an APT command through IPC, taking care of locking, opening and closing an APT session. * @param aptcmdbuf Pointer to command buffer (should have capacity for at least 16 words). */ Result aptSendCommand(u32* aptcmdbuf); /// Returns true if the application is currently in the foreground. bool aptIsActive(void); /// Returns true if the system has told the application to close. bool aptShouldClose(void); /// Returns true if the system can enter sleep mode while the application is active. bool aptIsSleepAllowed(void); /// Configures whether the system can enter sleep mode while the application is active. void aptSetSleepAllowed(bool allowed); /// Handles incoming sleep mode requests. void aptHandleSleep(void); /// Returns true if the user can press the HOME button to jump back to the HOME menu while the application is active. bool aptIsHomeAllowed(void); /// Configures whether the user can press the HOME button to jump back to the HOME menu while the application is active. void aptSetHomeAllowed(bool allowed); /// Returns true if the system requires the application to jump back to the HOME menu. bool aptShouldJumpToHome(void); /// Returns true if there is an incoming HOME button press rejected by the policy set by \ref aptSetHomeAllowed (use this to show a "no HOME allowed" icon). bool aptCheckHomePressRejected(void); /// \deprecated Alias for \ref aptCheckHomePressRejected. static inline CTR_DEPRECATED bool aptIsHomePressed(void) { return aptCheckHomePressRejected(); } /// Jumps back to the HOME menu. void aptJumpToHomeMenu(void); /// Handles incoming jump-to-HOME requests. static inline void aptHandleJumpToHome(void) { if (aptShouldJumpToHome()) aptJumpToHomeMenu(); } /** * @brief Main function which handles sleep mode and HOME/power buttons - call this at the beginning of every frame. * @return true if the application should keep running, false otherwise (see \ref aptShouldClose). */ bool aptMainLoop(void); /** * @brief Sets up an APT status hook. * @param cookie Hook cookie to use. * @param callback Function to call when APT's status changes. * @param param User-defined parameter to pass to the callback. */ void aptHook(aptHookCookie* cookie, aptHookFn callback, void* param); /** * @brief Removes an APT status hook. * @param cookie Hook cookie to remove. */ void aptUnhook(aptHookCookie* cookie); /** * @brief Sets the function to be called when an APT message from another applet is received. * @param callback Callback function. * @param user User-defined data to be passed to the callback. */ void aptSetMessageCallback(aptMessageCb callback, void* user); /** * @brief Launches a library applet. * @param appId ID of the applet to launch. * @param buf Input/output buffer that contains launch parameters on entry and result data on exit. * @param bufsize Size of the buffer. * @param handle Handle to pass to the library applet. */ void aptLaunchLibraryApplet(NS_APPID appId, void* buf, size_t bufsize, Handle handle); /// Clears the chainloader state. void aptClearChainloader(void); /** * @brief Configures the chainloader to launch a specific application. * @param programID ID of the program to chainload to. * @param mediatype Media type of the program to chainload to. */ void aptSetChainloader(u64 programID, u8 mediatype); /// Configures the chainloader to launch the previous application. void aptSetChainloaderToCaller(void); /// Configures the chainloader to relaunch the current application (i.e. soft-reset) void aptSetChainloaderToSelf(void); /** * @brief Sets the "deliver arg" and HMAC for the chainloader, which will * be passed to the target 3DS/DS(i) application. The meaning of each * parameter varies on a per-application basis. * @param deliverArg Deliver arg to pass to the target application. * @param deliverArgSize Size of the deliver arg, maximum 0x300 bytes. * @param hmac HMAC buffer, 32 bytes. Use NULL to pass an all-zero dummy HMAC. */ void aptSetChainloaderArgs(const void *deliverArg, size_t deliverArgSize, const void *hmac); /** * @brief Gets an APT lock handle. * @param flags Flags to use. * @param lockHandle Pointer to output the lock handle to. */ Result APT_GetLockHandle(u16 flags, Handle* lockHandle); /** * @brief Initializes an application's registration with APT. * @param appId ID of the application. * @param attr Attributes of the application. * @param signalEvent Pointer to output the signal event handle to. * @param resumeEvent Pointer to output the resume event handle to. */ Result APT_Initialize(NS_APPID appId, APT_AppletAttr attr, Handle* signalEvent, Handle* resumeEvent); /** * @brief Terminates an application's registration with APT. * @param appID ID of the application. */ Result APT_Finalize(NS_APPID appId); /// Asynchronously resets the hardware. Result APT_HardwareResetAsync(void); /** * @brief Enables APT. * @param attr Attributes of the application. */ Result APT_Enable(APT_AppletAttr attr); /** * @brief Gets applet management info. * @param inpos Requested applet position. * @param outpos Pointer to output the position of the current applet to. * @param req_appid Pointer to output the AppID of the applet at the requested position to. * @param menu_appid Pointer to output the HOME menu AppID to. * @param active_appid Pointer to output the AppID of the currently active applet to. */ Result APT_GetAppletManInfo(APT_AppletPos inpos, APT_AppletPos* outpos, NS_APPID* req_appid, NS_APPID* menu_appid, NS_APPID* active_appid); /** * @brief Gets the menu's app ID. * @return The menu's app ID. */ static inline NS_APPID aptGetMenuAppID(void) { NS_APPID menu_appid = APPID_NONE; APT_GetAppletManInfo(APTPOS_NONE, NULL, NULL, &menu_appid, NULL); return menu_appid; } /** * @brief Gets an applet's information. * @param appID AppID of the applet. * @param pProgramID Pointer to output the program ID to. * @param pMediaType Pointer to output the media type to. * @param pRegistered Pointer to output the registration status to. * @param pLoadState Pointer to output the load state to. * @param pAttributes Pointer to output the applet atrributes to. */ Result APT_GetAppletInfo(NS_APPID appID, u64* pProgramID, u8* pMediaType, bool* pRegistered, bool* pLoadState, APT_AppletAttr* pAttributes); /** * @brief Gets an applet's program information. * @param id ID of the applet. * @param flags Flags to use when retreiving the information. * @param titleversion Pointer to output the applet's title version to. * * Flags: * - 0x01: Use AM_ListTitles with NAND media type. * - 0x02: Use AM_ListTitles with SDMC media type. * - 0x04: Use AM_ListTitles with GAMECARD media type. * - 0x10: Input ID is an app ID. Must be set if 0x20 is not. * - 0x20: Input ID is a program ID. Must be set if 0x10 is not. * - 0x100: Sets program ID high to 0x00040000, else it is 0x00040010. Only used when 0x20 is set. */ Result APT_GetAppletProgramInfo(u32 id, u32 flags, u16 *titleversion); /** * @brief Gets the current application's program ID. * @param pProgramID Pointer to output the program ID to. */ Result APT_GetProgramID(u64* pProgramID); /// Prepares to jump to the home menu. Result APT_PrepareToJumpToHomeMenu(void); /** * @brief Jumps to the home menu. * @param param Parameters to jump with. * @param Size of the parameter buffer. * @param handle Handle to pass. */ Result APT_JumpToHomeMenu(const void* param, size_t paramSize, Handle handle); /** * @brief Prepares to jump to an application. * @param exiting Specifies whether the applet is exiting. */ Result APT_PrepareToJumpToApplication(bool exiting); /** * @brief Jumps to an application. * @param param Parameters to jump with. * @param Size of the parameter buffer. * @param handle Handle to pass. */ Result APT_JumpToApplication(const void* param, size_t paramSize, Handle handle); /** * @brief Gets whether an application is registered. * @param appID ID of the application. * @param out Pointer to output the registration state to. */ Result APT_IsRegistered(NS_APPID appID, bool* out); /** * @brief Inquires as to whether a signal has been received. * @param appID ID of the application. * @param signalType Pointer to output the signal type to. */ Result APT_InquireNotification(u32 appID, APT_Signal* signalType); /** * @brief Requests to enter sleep mode, and later sets wake events if allowed to. * @param wakeEvents The wake events. Limited to "shell" (bit 1) for the PDN wake events part * and "shell opened", "shell closed" and "HOME button pressed" for the MCU interrupts part. */ Result APT_SleepSystem(const struct PtmWakeEvents *wakeEvents); /** * @brief Notifies an application to wait. * @param appID ID of the application. */ Result APT_NotifyToWait(NS_APPID appID); /** * @brief Calls an applet utility function. * @param id Utility function to call. * @param out Pointer to write output data to. * @param outSize Size of the output buffer. * @param in Pointer to the input data. * @param inSize Size of the input buffer. */ Result APT_AppletUtility(int id, void* out, size_t outSize, const void* in, size_t inSize); /// Sleeps if shell is closed (?). Result APT_SleepIfShellClosed(void); /** * @brief Locks a transition (?). * @param transition Transition ID. * @param flag Flag (?) */ Result APT_LockTransition(u32 transition, bool flag); /** * @brief Tries to lock a transition (?). * @param transition Transition ID. * @param succeeded Pointer to output whether the lock was successfully applied. */ Result APT_TryLockTransition(u32 transition, bool* succeeded); /** * @brief Unlocks a transition (?). * @param transition Transition ID. */ Result APT_UnlockTransition(u32 transition); /** * @brief Glances at a receieved parameter without removing it from the queue. * @param appID AppID of the application. * @param buffer Buffer to receive to. * @param bufferSize Size of the buffer. * @param sender Pointer to output the sender's AppID to. * @param command Pointer to output the command ID to. * @param actualSize Pointer to output the actual received data size to. * @param parameter Pointer to output the parameter handle to. */ Result APT_GlanceParameter(NS_APPID appID, void* buffer, size_t bufferSize, NS_APPID* sender, APT_Command* command, size_t* actualSize, Handle* parameter); /** * @brief Receives a parameter. * @param appID AppID of the application. * @param buffer Buffer to receive to. * @param bufferSize Size of the buffer. * @param sender Pointer to output the sender's AppID to. * @param command Pointer to output the command ID to. * @param actualSize Pointer to output the actual received data size to. * @param parameter Pointer to output the parameter handle to. */ Result APT_ReceiveParameter(NS_APPID appID, void* buffer, size_t bufferSize, NS_APPID* sender, APT_Command* command, size_t* actualSize, Handle* parameter); /** * @brief Sends a parameter. * @param source AppID of the source application. * @param dest AppID of the destination application. * @param command Command to send. * @param buffer Buffer to send. * @param bufferSize Size of the buffer. * @param parameter Parameter handle to pass. */ Result APT_SendParameter(NS_APPID source, NS_APPID dest, APT_Command command, const void* buffer, u32 bufferSize, Handle parameter); /** * @brief Cancels a parameter which matches the specified source and dest AppIDs. * @param source AppID of the source application (use APPID_NONE to disable the check). * @param dest AppID of the destination application (use APPID_NONE to disable the check). * @param success Pointer to output true if a parameter was cancelled, or false otherwise. */ Result APT_CancelParameter(NS_APPID source, NS_APPID dest, bool* success); /** * @brief Sends capture buffer information. * @param captureBuf Capture buffer information to send. */ Result APT_SendCaptureBufferInfo(const aptCaptureBufInfo* captureBuf); /** * @brief Replies to a sleep query. * @param appID ID of the application. * @param reply Query reply value. */ Result APT_ReplySleepQuery(NS_APPID appID, APT_QueryReply reply); /** * @brief Replies that a sleep notification has been completed. * @param appID ID of the application. */ Result APT_ReplySleepNotificationComplete(NS_APPID appID); /** * @brief Prepares to close the application. * @param cancelPreload Whether applet preloads should be cancelled. */ Result APT_PrepareToCloseApplication(bool cancelPreload); /** * @brief Closes the application. * @param param Parameters to close with. * @param paramSize Size of param. * @param handle Handle to pass. */ Result APT_CloseApplication(const void* param, size_t paramSize, Handle handle); /** * @brief Sets the application's CPU time limit. * @param percent CPU time limit percentage to set. */ Result APT_SetAppCpuTimeLimit(u32 percent); /** * @brief Gets the application's CPU time limit. * @param percent Pointer to output the CPU time limit percentage to. */ Result APT_GetAppCpuTimeLimit(u32 *percent); /** * @brief Checks whether the system is a New 3DS. * @param out Pointer to write the New 3DS flag to. */ Result APT_CheckNew3DS(bool* out); /** * @brief Prepares for an applicaton jump. * @param flags Flags to use. * @param programID ID of the program to jump to. * @param mediatype Media type of the program to jump to. */ Result APT_PrepareToDoApplicationJump(u8 flags, u64 programID, u8 mediatype); /** * @brief Performs an application jump. * @param param Parameter buffer. * @param paramSize Size of parameter buffer. * @param hmac HMAC buffer (should be 0x20 bytes long). */ Result APT_DoApplicationJump(const void* param, size_t paramSize, const void* hmac); /** * @brief Prepares to start a library applet. * @param appID AppID of the applet to start. */ Result APT_PrepareToStartLibraryApplet(NS_APPID appID); /** * @brief Starts a library applet. * @param appID AppID of the applet to launch. * @param param Buffer containing applet parameters. * @param paramsize Size of the buffer. * @param handle Handle to pass to the applet. */ Result APT_StartLibraryApplet(NS_APPID appID, const void* param, size_t paramSize, Handle handle); /** * @brief Prepares to start a system applet. * @param appID AppID of the applet to start. */ Result APT_PrepareToStartSystemApplet(NS_APPID appID); /** * @brief Starts a system applet. * @param appID AppID of the applet to launch. * @param param Buffer containing applet parameters. * @param paramSize Size of the parameter buffer. * @param handle Handle to pass to the applet. */ Result APT_StartSystemApplet(NS_APPID appID, const void* param, size_t paramSize, Handle handle); /** * @brief Retrieves the shared system font. * @brief fontHandle Pointer to write the handle of the system font memory block to. * @brief mapAddr Pointer to write the mapping address of the system font memory block to. */ Result APT_GetSharedFont(Handle* fontHandle, u32* mapAddr); /** * @brief Receives the deliver (launch) argument * @param param Parameter buffer. * @param paramSize Size of parameter buffer. * @param hmac HMAC buffer (should be 0x20 bytes long). * @param sender Pointer to output the sender's AppID to. * @param received Pointer to output whether an argument was received to. */ Result APT_ReceiveDeliverArg(void* param, size_t paramSize, void* hmac, u64* sender, bool* received);