1 /*---------------------------------------------------------------------------* 2 Project: Cafe 3 File: sysapp.h 4 5 Copyright (C) 2012 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 *---------------------------------------------------------------------------*/ 14 15 #ifndef __SYSAPP_H__ 16 #define __SYSAPP_H__ 17 18 #include <types.h> 19 #include <cafe/os.h> 20 21 #include <nn/ffl/FFLStandard.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /// @addtogroup pub Public 28 /// @{ 29 //=============================================================================== 30 /** 31 * A common, standard argument passed when making application jumps. 32 */ 33 typedef struct SysStandardArgsIn 34 { 35 /** Make an application jump, and upon returning from that jump, specify the data that can be obtained with <tt>SYSGetArguments</tt>. 36 * Use this data to determine the sequence of the jump and return. 37 */ 38 const char * cp_Anchor; 39 /** Specify the size of the data block specified above. (Maximum: 4096 bytes) 40 */ 41 u32 anchorSize; 42 } SysStandardArgsIn; 43 /*---------------------------------------------------------------------------*/ 44 /** 45 * A standard argument that can be obtained when making application jumps. 46 */ 47 typedef struct SysStandardArgs 48 { 49 const char * cp_Anchor; // Pointer to data used to determine which application control returned after returning from an application jump. 50 u32 anchorSize; // 51 52 char * p_Result; // Pointer to data that is passed from the application that was jumped to after returning from an application jump. 53 u32 resultSize; // 54 } SysStandardArgs; 55 //=============================================================================== 56 /* 57 * browser 58 */ 59 /*---------------------------------------------------------------------------*/ 60 /** 61 ** An argument passed when starting the browser. 62 */ 63 typedef struct SysBrowserArgsIn 64 { 65 SysStandardArgsIn stdIn; ///< A common, standard argument. 66 67 /** Specifies a pointer to the URL string. 68 * The URL must be a NULL-terminated string that starts with either http:// or https://. 69 * The maximum length, including the scheme at the beginning, is 1023 characters (not including the NULL terminator). 70 * If you are including characters that cannot be used in the URI, percent-encode them beforehand. 71 */ 72 const char * cp_URL; 73 74 /** Specifies the size of the URL string. Specify a size that includes a string terminator. 75 */ 76 u32 urlSize; 77 78 } SysBrowserArgsIn; 79 /*---------------------------------------------------------------------------*/ 80 /** 81 * Switch to the browser. 82 * 83 * @param[in] cp_Args Specifies a pointer to the argument structure to pass to the browser. If 0 is specified, it simply jumps to the browser. 84 * 85 * @retval 0 Indicates success. 86 * @retval -40000 Indicates that <span class="argument">anchorSize</span> is too big. Specify 0. 87 * @retval -50000 Indicates that <span class="argument">urlSize</span> is too big. Specify 1024 or less. 88 */ 89 s32 SYSSwitchToBrowser( const SysBrowserArgsIn *cp_Args ); 90 /*---------------------------------------------------------------------------*/ 91 /** 92 * An argument passed when starting the browser. A callback URL can be specified. 93 */ 94 typedef struct SysBrowserArgsInForCallbackURL 95 { 96 SysStandardArgsIn stdIn; ///< A common, standard argument. 97 98 /** Specifies a pointer to the URL string. 99 * The URL must be a NULL-terminated string that starts with either http:// or https://. 100 * The maximum length, including the scheme at the beginning, is 1023 characters (not including the NULL terminator). 101 * If you are including characters that cannot be used in the URI, percent-encode them beforehand. 102 */ 103 const char * cp_URL; 104 105 /** Specifies the size of the URL string. Specify a size that includes a string terminator. 106 */ 107 u32 urlSize; 108 109 /** Specifies a pointer to the callback URL string. 110 */ 111 const char * cp_CallbackURL; 112 113 /** Specifies the size of the callback URL string. Specify a size that includes a string terminator. 114 */ 115 u32 callbackUrlSize; 116 117 /** This flag indicates whether to prohibit the HOME Button menu in the browser. 118 */ 119 BOOL hbmDisable; 120 } SysBrowserArgsInForCallbackURL; 121 /*---------------------------------------------------------------------------*/ 122 /** 123 * Switch to the browser. 124 * 125 * @param[in] cp_Args Specifies a pointer to the argument structure to pass to the browser. If 0 is specified, it simply jumps to the browser. 126 * 127 * @retval 0 Indicates success. 128 * @retval -40000 Indicates that <span class="argument">anchorSize</span> is too big. Specify 0. 129 * @retval -50000 Indicates that <span class="argument">urlSize</span> is too big. Specify 1024 or less. 130 */ 131 s32 SYSSwitchToBrowserForCallbackURL( const SysBrowserArgsInForCallbackURL *cp_Args ); 132 //=============================================================================== 133 /* 134 * EManual 135 */ 136 /*---------------------------------------------------------------------------*/ 137 /** 138 * Switches to the e-manual. 139 */ 140 s32 SYSSwitchToEManual( void ); 141 //=============================================================================== 142 /** 143 * account 144 */ 145 /*---------------------------------------------------------------------------*/ 146 /** An argument passed when starting the account management screen. 147 */ 148 typedef struct SysAccountArgsIn 149 { 150 SysStandardArgsIn stdIn; ///< A common, standard argument. 151 152 /** Specifies the slot number you want to change. 153 */ 154 u32 slotId; 155 } SysAccountArgsIn; 156 /*---------------------------------------------------------------------------*/ 157 /** 158 * Starts the account management application. 159 * (The application exits.) 160 * @retval 0 Indicates success. 161 * @retval -100000 Indicates a fatal error. 162 * @retval -40000 Indicates that <span class="argument">anchorSize</span> is too big. Specify 0. 163 */ 164 s32 SYSLaunchAccount( const SysAccountArgsIn * cp_Args ); 165 //=============================================================================== 166 /** 167 * settings 168 */ 169 /*---------------------------------------------------------------------------*/ 170 /** 171 */ 172 typedef enum SysSettingsJumpTo 173 { 174 SYS_SETTINGS_JUMP_TO_TOP = 0, ///< Top screen. 175 SYS_SETTINGS_JUMP_TO_INTERNET, ///< Internet settings. 176 SYS_SETTINGS_JUMP_TO_DATA_MANAGE, ///< Data management screen. 177 SYS_SETTINGS_JUMP_TO_TV_REMOTE, ///< TV remote control settings screen. 178 SYS_SETTINGS_JUMP_TO_DATE_TIME, ///< Time and date management screen. 179 SYS_SETTINGS_JUMP_TO_COUNTRY, ///< Country settings screen. 180 SYS_SETTINGS_JUMP_TO_UPDATE, ///< System update screen. 181 } SysSettingsJumpTo; 182 /*---------------------------------------------------------------------------*/ 183 /** 184 */ 185 typedef struct SysSettingsArgsIn 186 { 187 SysStandardArgsIn stdIn; ///< A common, standard argument. 188 SysSettingsJumpTo jumpTo; ///< Specifies the jump destination. 189 } SysSettingsArgsIn; 190 /*---------------------------------------------------------------------------*/ 191 /** 192 * Starts System Settings. 193 * (The application exits.) 194 * @retval 0 Indicates success. 195 * @retval -100000 Indicates a fatal error. 196 * @retval -40000 Indicates that <span class="argument">anchorSize</span> is too big. Specify 0. 197 */ 198 s32 SYSLaunchSettings( const SysSettingsArgsIn * cp_Args ); 199 200 /*---------------------------------------------------------------------------*/ 201 /** 202 * Starts the Launcher. 203 * (The application exits.) 204 * @retval 0 Indicates success. 205 * @retval -100000 Indicates a fatal error. 206 */ 207 s32 SYSLaunchMenu( void ); 208 /*---------------------------------------------------------------------------*/ 209 /** 210 * Jumps to the Wii Remote pairing screen in the HOME Button menu. 211 * @retval 0 Indicates success. 212 * @retval -100000 Indicates a fatal error. 213 */ 214 s32 SYSSwitchToSyncControllerOnHBM( void ); 215 216 //=============================================================================== 217 /* 218 * vod 219 */ 220 /*---------------------------------------------------------------------------*/ 221 /** 222 * A structure for getting arguments for Video On Demand (VOD) applications. 223 */ 224 typedef struct SysVodArgs 225 { 226 SysStandardArgs std; ///< A common, standard argument. 227 228 const char * cp_URL; ///< Contains the URL string for the VOD application. 229 u32 urlSize; ///< The size of the URL string. 230 } SysVodArgs; 231 /*---------------------------------------------------------------------------*/ 232 /** 233 * Gets the VOD application arguments. 234 * 235 * Call this function right after starting the application and when returning from the HOME Button menu to get the arguments. 236 * @retval 1 Specifies that there are no arguments. 237 * @retval 0 Indicates success. 238 * @retval -100000 Specifies that a fatal error occurred. (<tt>NULL</tt> is specified in an argument.) 239 */ 240 s32 SYSGetVodArgs( SysVodArgs *p_Args ); 241 /*---------------------------------------------------------------------------*/ 242 /** 243 * Restarts itself. 244 * 245 * @retval 0 Indicates success. 246 * @retval -100000 Specifies that a fatal error occurred. (<tt>NULL</tt> is specified in an argument.) 247 */ 248 s32 SYSRelaunchTitle( u32 argc, char * pa_Argv[] ); 249 /*---------------------------------------------------------------------------*/ 250 /** 251 * Type representing arguments that are passed when jumping. 252 */ 253 typedef enum SysArgType 254 { 255 SYS_ARG_TYPE_NODATA = 0, 256 SYS_ARG_TYPE_U32, 257 SYS_ARG_TYPE_U64, 258 SYS_ARG_TYPE_DATA_BLOCK, 259 SYS_ARG_TYPE_CONST_DATA_BLOCK, 260 SYS_ARG_TYPE_NUM 261 } SysArgType; 262 /*---------------------------------------------------------------------------*/ 263 /** 264 * IDs of arguments that are passed when jumping. 265 */ 266 typedef enum SysArgID 267 { 268 SYS_ARG_ID_TERMINATOR = 0, ///< Specify the last element in the array. 269 270 SYS_ARG_ID_ANCHOR = 100, ///< The ID of the <span class="argument">anchor</span> argument. 271 SYS_ARG_ID_RESULT, ///< The ID of the <span class="argument">result</span> argument. 272 273 SYS_ARG_ID_VOD_URL = 200, ///< The ID of the <span class="argument">URL</span> argument for the video on demand application. 274 275 SYS_ARG_ID_MIIVERSE_DATA = 300, ///< The ID of the <span class="argument">Miiverse</span> argument. 276 277 SYS_ARG_ID_JOIN_PID = 400 ///< The ID of the join-in argument. 278 279 } SysArgID; 280 /*---------------------------------------------------------------------------*/ 281 /** 282 * 283 */ 284 typedef struct SysArgBase 285 { 286 SysArgID id; 287 SysArgType type; 288 } SysArgBase; 289 /*---------------------------------------------------------------------------*/ 290 /** 291 * Stores data of type <tt>u32</tt>. 292 */ 293 typedef struct SysArgU32 294 { 295 SysArgBase base; 296 u32 value; 297 } SysArgU32; 298 /*---------------------------------------------------------------------------*/ 299 /** 300 * Stores data of type <tt>u64</tt>. 301 */ 302 typedef struct SysArgU64 303 { 304 SysArgBase base; 305 u64 value; 306 } SysArgU64; 307 /*---------------------------------------------------------------------------*/ 308 /** 309 * Stores a data block. 310 */ 311 typedef struct SysArgDataBlock 312 { 313 SysArgBase base; 314 char * p_Data; 315 u32 dataSize; 316 } SysArgDataBlock; 317 /*---------------------------------------------------------------------------*/ 318 /** 319 * Stores a data block. 320 */ 321 typedef struct SysArgConstDataBlock 322 { 323 SysArgBase base; 324 const char * cp_Data; 325 u32 dataSize; 326 } SysArgConstDataBlock; 327 /*---------------------------------------------------------------------------*/ 328 /** 329 * 330 */ 331 typedef union SysArgSlot 332 { 333 SysArgBase _base; 334 SysArgU32 _u32; 335 SysArgU64 _u64; 336 SysArgDataBlock _blk; 337 SysArgConstDataBlock _cblk; 338 } SysArgSlot; 339 /*---------------------------------------------------------------------------*/ 340 /** 341 * Enumerates callers. 342 */ 343 typedef enum SysCallerType 344 { 345 SYS_CALLER_TYPE_INVALID = -1, 346 SYS_CALLER_TYPE_LAUNCHER = 2, 347 SYS_CALLER_TYPE_TVII = 3, 348 SYS_CALLER_TYPE_HBM = 5, 349 SYS_CALLER_TYPE_MINI_MIIVERSE = 7, 350 SYS_CALLER_TYPE_MIIVERSE = 9, 351 SYS_CALLER_TYPE_FRIEND_LIST = 11, 352 SYS_CALLER_TYPE_GAME = 15, 353 SYS_CALLER_TYPE_END 354 } SysCallerType; 355 /*---------------------------------------------------------------------------*/ 356 /** 357 * 358 */ 359 typedef struct SysCallerData 360 { 361 SysCallerType type; 362 u64 titleId; 363 } SysCallerData; 364 /*---------------------------------------------------------------------------*/ 365 /** 366 * This is a generic function for retrieving arguments. 367 * 368 * @param[in,out] ap_SysArgSlot Specifies a pointer to an array of <tt>SysArgSlot</tt> unions. 369 * @param[out] p_Caller Specifies a pointer to the <tt>SysCallerData</tt> structure that stores information on the application jump origin. 370 * 371 * @retval 0 Indicates success. 372 * @retval 1 Finished normally, but there were no retrievable arguments. 373 * @retval <0 Indicates a program error. Zero was passed to an argument. 374 * 375 * Prepare an array of <tt>SysArgSlot</tt> elements and set the IDs of the arguments to retrieve. 376 * Be sure to set <tt>SYS_ARG_ID_TERMINATOR</tt> in the last element of the array. 377 * 378 * If the function succeeds, information on the jump origin is stored in the <tt>SysCallerData</tt> structure. 379 * If the jump origin passes any arguments, the data is stored in the <tt>Slot</tt> with the corresponding ID. 380 * If no arguments are passed, <tt>_base.type</tt> becomes <tt>SYS_ARG_TYPE_NODATA</tt>. 381 * 382 * First, use <tt>SysCallerData</tt> to determine where the jump is from, and then access the <tt>Slot</tt> that contains the argument. 383 * 384 */ 385 s32 SYSGetArguments( SysArgSlot * ap_SysArgSlot, SysCallerData * p_Caller ); 386 /*---------------------------------------------------------------------------*/ 387 /** 388 * 389 */ 390 typedef enum SysCheckableSystemApplicationID 391 { 392 SYS_CHECK_ID_EMANUAL = 4, 393 SYS_CHECK_ID_MINI_MIIVERSE = 7, 394 SYS_CHECK_ID_BROWSER = 8, 395 SYS_CHECK_ID_MIIVERSE = 9, 396 SYS_CHECK_ID_ESHOP = 10, 397 SYS_CHECK_ID_END 398 } SysCheckableSystemApplicationID; 399 /*---------------------------------------------------------------------------*/ 400 /** 401 * Function that checks whether the specified system application is installed on the development hardware. 402 * 403 * @attention This is used for debugging purposes only. 404 */ 405 BOOL SYSCheckSystemApplicationExists( SysCheckableSystemApplicationID id ); 406 /*---------------------------------------------------------------------------*/ 407 /* 408 */ 409 #define SYS_ERROR_NO_ARGS (1) ///< The return value when no arguments could be retrieved. This value is returned when no arguments are passed from the jump origin. 410 #define SYS_ERROR_NONE (0) ///< Normal end. 411 412 #define SYS_ERROR_FATAL (-100000) ///< Fatal error. 413 414 #define SYS_ERROR_SERIALIZE_ANCHOR_SIZE_MAX (-40000) ///< The anchor size is too large. 415 #define SYS_ERROR_SERIALIZE_URL_SIZE_MAX (-50000) ///< The URL string is too large. 416 417 #ifdef __cplusplus 418 } 419 #endif 420 421 /// @} 422 423 #endif // __SYSAPP_H__ 424