1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 //------------------------------------------------------------------------------ 14 /** @file erreula_Api.h 15 * @brief Error Viewer Library API 16 */ 17 //------------------------------------------------------------------------------ 18 #ifndef NN_ERREULA_API_H_ 19 #define NN_ERREULA_API_H_ 20 21 #include <cafe/vpad.h> // The <tt>VPADStatus</tt> structure is defined here. 22 #include <cafe/pads/kpad/kpad.h> // The <tt>KPADStatus</tt> structure is defined here. 23 #include <cafe/fs.h> 24 25 #include "erreula_Types.h" 26 #include "erreula_AppearArg.h" 27 28 /** @namespace nn::erreula 29 * The namespace for <tt>erreula</tt>. 30 */ 31 namespace nn { 32 //------------------------------------------------------------------------------ 33 namespace erreula { 34 //------------------------------------------------------------------------------ 35 ///@defgroup basic_api Basic Error Viewer (ERREULA) API 36 ///@{ 37 /** 38 * Initial settings class. 39 * 40 * Pass as parameters to the <tt>nn::erreula::Create</tt> function. 41 */ 42 class CreateArg 43 { 44 public: 45 /// Working buffer used by the library.<br/>Allocate and specify a memory region of the size returned by the <tt> nn::erreula::GetWorkMemorySize</tt> function. 46 u8* mBuffer; 47 /// Region.<br/>Specify the system region. Defaults to Japan if not specified. 48 RegionType mRegion; 49 /// Specify the language for error messages. This defaults to Japanese if not specified. 50 LangType mLang; 51 /// Specify the file client to use when loading error viewer resources. For more information, see the SDK file system (FS library) function <tt>FSAddClient</tt>. 52 FSClient* mFSClient; 53 /// Instantiates an object. CreateArg()54 CreateArg() : mBuffer( NULL ), mRegion( cRegionType_Jp ), mLang( cLangType_Ja ), mFSClient( NULL ) 55 { 56 } 57 }; 58 59 //------------------------------------------------------------------------------ 60 /** 61 * Construct the error viewer. 62 * 63 * You need a working buffer equal in size to the value obtained with the <tt>nn::erreula::GetWorkMemorySize</tt> function. 64 * Allocate a buffer of the size obtained and specify it in the parameter. 65 * If you omit this parameter, working memory is allocated using the <tt>MEMAllocFromDefaultHeapEx</tt> function. 66 * 67 * We recommend that you call this function in a thread that has lower priority than that of the main thread because files are loaded internally from NAND memory. 68 * The thread that called this function may be referenced while calling other functions. Therefore note that it should not be destroyed until the Error Viewer terminates. 69 * 70 * In addition, because GX2 display list operations are performed from inside this function, do not perform GX2 operations in parallel with this function on the same core. 71 * Call <tt>GX2Init</tt> in advance for the same reason. 72 * 73 * The <tt>OSDynLoad_SetAllocator</tt> function is also used internally. 74 * Note that if there is already an allocator set by the application, it will be overwritten. 75 * 76 * When specifying cores, call the function with just one core specified. Setting thread affinity to multiple cores and then calling functions from that thread can result in failure. 77 * For more on affinity, see <tt>CreateThread</tt> in the <i>Cafe SDK API Reference</i>. 78 * 79 * @param[in] arg Initialization class. 80 * 81 * @return Returns <tt>true</tt> if the object is constructed successfully. 82 83 84 85 86 87 88 */ 89 bool Create( const nn::erreula::CreateArg& arg ); 90 91 //------------------------------------------------------------------------------ 92 /** 93 * Gets the memory size required to create the error viewer. 94 * 95 * @return Returns the memory size (in bytes) required to create the error viewer. 96 */ 97 u32 GetWorkMemorySize(); 98 99 //------------------------------------------------------------------------------ 100 /** 101 * Closes the library. 102 * When no parameters were specified for the <tt>nn::erreula::Create</tt> function, the memory allocated from the <tt>MEMAllocFromDefaultHeapEx</tt> function is deallocated within this function. 103 * 104 * When specifying cores, call the function with just one core specified. Setting thread affinity to multiple cores and then calling functions from that thread can result in failure. 105 * For more on affinity, see <tt>CreateThread</tt> in the <i>Cafe SDK API Reference</i>. 106 107 108 */ 109 void Destroy(); 110 111 //------------------------------------------------------------------------------ 112 /** 113 * This class is for passing controller input to the error viewer. 114 * Pass as parameters to the <tt>nn::erreula::Calc</tt> function. The <tt>VPAD</tt> / <tt>KPADStatus</tt> structure is maintained by making an internal copy. 115 * Because the <tt>VPADGetTPCalibratedPoint</tt> function is not called within the library, pass the values calibrated by the application using data obtained by the <tt>VPADRead</tt> function. 116 117 118 */ 119 class ControllerInfo 120 { 121 public: 122 /// Data obtained from <tt>VPADRead</tt>. 123 const VPADStatus* vpad_status; 124 /// Data obtained from <tt>KPADRead</tt>. 125 const KPADStatus* kpad_status[ WPAD_MAX_CONTROLLERS ]; 126 127 /// Instantiates an object. ControllerInfo()128 ControllerInfo() : vpad_status( NULL ) 129 { 130 for( int i = 0; i < WPAD_MAX_CONTROLLERS; ++i ) 131 { 132 kpad_status[i] = NULL; 133 } 134 } 135 }; 136 137 //------------------------------------------------------------------------------ 138 /** 139 * The main error viewer process. Call this function in every game frame. 140 * 141 * @param[in] controller_info Controller input information. 142 */ 143 void Calc( const nn::erreula::ControllerInfo& controller_info ); 144 145 //------------------------------------------------------------------------------ 146 /** 147 * Issues commands for rendering graphics for display on the TV. 148 * The library does not create a frame buffer. 149 * 150 * Also refer to the <tt> demo/erreula/simple</tt> sample program included in the package. 151 */ 152 void DrawTV(); 153 154 //------------------------------------------------------------------------------ 155 /** 156 * Issues commands for rendering graphics for display on the Wii U GamePad (DRC). 157 * The library does not create a frame buffer. 158 * 159 * Also refer to the <tt> demo/erreula/simple</tt> sample program included in the package. 160 */ 161 void DrawDRC(); 162 163 //------------------------------------------------------------------------------ 164 /** 165 * Displays the error viewer. 166 * 167 * @param[in] arg Specifies the class for setting options. 168 * @note Call this function after confirming that the error viewer is being hidden (<tt>nn::erreula::cState_Blank</tt>). 169 */ 170 void AppearErrorViewer( const nn::erreula::AppearArg& arg ); 171 172 //------------------------------------------------------------------------------ 173 /** 174 * Reverts the displayed error viewer to the hidden state. 175 * 176 * @note Call this function after confirming that the error viewer is being displayed (<tt>nn::erreula::cState_Display</tt>). 177 */ 178 void DisappearErrorViewer(); 179 180 //------------------------------------------------------------------------------ 181 /** 182 * Gets whether the error viewer's SELECT button was pressed. 183 * This indicates that the user has checked the displayed message, so close the error viewer and transition to the next process. 184 * 185 * @return Returns <tt>true</tt> if the SELECT button was pressed. 186 * @note Note that once the button has been pressed the same value will be returned until the next call to the <tt>nn::erreula::AppearErrorViewer</tt> function. 187 * @note This value does not depend on the number of buttons. With more than one button, the function returns <tt>true</tt> no matter which button is pressed. 188 * @note In the code specification, some error codes require subsequent action, so refer to <tt>nn::erreula::ResultType</tt>. 189 */ 190 bool IsDecideSelectButtonError(); 191 192 //------------------------------------------------------------------------------ 193 /** 194 * Gets whether the error viewer's left button was pressed. 195 * 196 * @return Returns <tt>true</tt> if the SELECT button was pressed. 197 * @note Note that once the button has been pressed the same value will be returned until the next call to the <tt>nn::erreula::AppearErrorViewer</tt> function. 198 * @note In the code specification, this is normally not used. (Returns <tt>true</tt> if for some reason the user has canceled execution.) Use the <tt>nn::erreula::IsDecideSelectButtonError</tt> function to confirm that the button has been pressed, and then refer to <tt>nn::erreula::RegionType</tt> and move to the next action. 199 */ 200 bool IsDecideSelectLeftButtonError(); 201 202 //------------------------------------------------------------------------------ 203 /** 204 * Gets whether the error viewer's right button was pressed. 205 * 206 * @return Returns <tt>true</tt> if the SELECT button was pressed. 207 * @note Note that once the button has been pressed the same value will be returned until the next call to the <tt>nn::erreula::AppearErrorViewer</tt> function. 208 * @note In the code specification, this is normally not used. (Returns <tt>true</tt> if for some reason the user has selected execution.) Use the <tt>nn::erreula::IsDecideSelectButtonError</tt> function to confirm that the button has been pressed, and then refer to <tt>nn::erreula::RegionType</tt> and move to the next action. 209 */ 210 bool IsDecideSelectRightButtonError(); 211 212 //------------------------------------------------------------------------------ 213 /** 214 * Gets the display state of the error viewer. 215 * 216 * @retval nn::erreula::cState_Blank Hidden. 217 * @retval nn::erreula::cState_Appear Appearing. 218 * @retval nn::erreula::cState_Display Displayed. 219 * @retval nn::erreula::cState_Disappear Disappearing. 220 */ 221 nn::erreula::State GetStateErrorViewer(); 222 223 //------------------------------------------------------------------------------ 224 /** 225 * Gets the result type corresponding to the button pressed when the error viewer is displaying. 226 * Refer to <tt>nn::erreula::ResultType</tt> and move to the next process. 227 * 228 * @return The result type. 229 */ 230 nn::erreula::ResultType GetResultType(); 231 232 //------------------------------------------------------------------------------ 233 /** 234 * Gets the result code corresponding to the button pressed when the error viewer is displaying. 235 * The meaning of this value varies, depending on the result type, so refer to <tt>nn::erreula::ResultType</tt> to see how to use the obtained value. 236 * 237 * @return Returns the result code. 238 */ 239 s32 GetResultCode(); 240 241 //------------------------------------------------------------------------------ 242 /** 243 * Gets the number of error viewer SELECT buttons. 244 * 245 * @return Returns the number of SELECT buttons. 246 */ 247 s32 GetSelectButtonNumError(); 248 249 //------------------------------------------------------------------------------ 250 /** 251 * Switches the Wii Remote that can operate the error viewer. 252 * 253 * @note If the error viewer is displaying on the Wii U GamePad, even if a Wii Remote has been specified, it is ignored. 254 */ 255 void SetControllerRemo( const nn::erreula::ControllerType type ); 256 257 //------------------------------------------------------------------------------ 258 /** 259 * Displays the HOME Button prohibition icon. 260 */ 261 void AppearHomeNixSign( const nn::erreula::HomeNixSignArg& arg ); 262 263 //------------------------------------------------------------------------------ 264 /** 265 * Gets whether the HOME Button prohibition icon is being displayed. 266 */ 267 bool IsAppearHomeNixSign(); 268 269 //------------------------------------------------------------------------------ 270 /** 271 * Hides the HOME Button prohibition icon. 272 */ 273 void DisappearHomeNixSign(); 274 275 //------------------------------------------------------------------------------ 276 /** 277 * Changes the language set for the error viewer. 278 * 279 * @param[in] lang Specifies the language to change to. 280 */ 281 void ChangeLangError( const nn::erreula::LangType lang ); 282 283 //------------------------------------------------------------------------------ 284 /** 285 * Gets whether the selection cursor that indicates whether the focus is on a button is being displayed. 286 * 287 * @note Indicates that the user is operating the error viewer by using a controller such as the +Control Pad, rather than by touching the screen. When control is returned to the caller application, display the selection cursor (the focus) so it is easy to continue operating the error viewer using a controller such as the +Control Pad. 288 */ 289 bool IsSelectCursorActive(); 290 291 //------------------------------------------------------------------------------ 292 /** 293 * Sets whether to play sound effects when displaying the error viewer. 294 * 295 * @param[in] use If <tt>true</tt>, play sound effects. If <tt>false</tt> (the default), do not play sound effects. 296 */ 297 void PlayAppearSE( bool use ); 298 299 //------------------------------------------------------------------------------ 300 /** 301 * When the current <tt>nn::erreula::ResultType</tt> is <tt>nn::erreula::cResultType_Jump</tt>, this function jumps to an application or restarts based on the value of the <tt>nn::erreula::GetResultCode</tt> function. 302 * Also refer to the <tt>demo/erreula/jump</tt> sample program included in the package. 303 * 304 * @param[in] anchor Specifies the anchor string received by the application when control returns from the jump (up to <tt>OS_ARGS_SIZE - 1</tt> bytes). 305 * @param[in] anchorSize Specifies the size, in bytes, of the data passed to <var>anchor</var>. 306 * @return Returns <tt>true</tt> on success, or <tt>false</tt> on failure (cannot jump to application). 307 * @note Potential applications to jump to include System Settings, Account Management, and the calling application (restarting the application). 308 * @note After exiting Account Management and some parts of System Settings, control may not return to the caller. (The anchor string parameter cannot be used in such cases.) 309 * @note Until SDK 2.10, the application needed to look at <tt>nn::erreula::ResultType</tt> or the <tt>nn::erreula::GetResultCode</tt> function to differentiate between the <tt>SYSLaunchAccount</tt>, <tt>SYSLaunchSettings</tt>, and <tt>SYSRelaunchTitle</tt> functions. The application does not need to do this now if you use the <tt>nn::erreula::Jump</tt> function. 310 * @note By specifying an anchor string, you can determine whether the application has been restarted or has returned from an application to which it jumped. 311 * @note If the application has been restarted, you can get the anchor string using the <tt>OSGetArgcArgv</tt> function. 312 * @note If the application has returned from a jump, you can get the anchor string by calling the <tt>SYSGetArguments</tt> function with <tt>SYS_ARG_ID_ANCHOR</tt> specified. 313 */ 314 bool Jump( const char* anchor, u32 anchorSize ); 315 316 ///@} 317 318 //------------------------------------------------------------------------------ 319 } // namespace erreula 320 //------------------------------------------------------------------------------ 321 } // namespace nn 322 323 #endif /* NN_ERREULA_API_H_ */ 324