/*---------------------------------------------------------------------------* Copyright (C) Nintendo. 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. *---------------------------------------------------------------------------*/ //------------------------------------------------------------------------------ /** @file erreula_Api.h * @brief Error Viewer Library API */ //------------------------------------------------------------------------------ #ifndef NN_ERREULA_API_H_ #define NN_ERREULA_API_H_ #include // The VPADStatus structure is defined here. #include // The KPADStatus structure is defined here. #include #include "erreula_Types.h" #include "erreula_AppearArg.h" /** @namespace nn::erreula * The namespace for erreula. */ namespace nn { //------------------------------------------------------------------------------ namespace erreula { //------------------------------------------------------------------------------ ///@defgroup basic_api Basic Error Viewer (ERREULA) API ///@{ /** * Initial settings class. * * Pass as parameters to the nn::erreula::Create function. */ class CreateArg { public: /// Working buffer used by the library.
Allocate and specify a memory region of the size returned by the nn::erreula::GetWorkMemorySize function. u8* mBuffer; /// Region.
Specify the system region. Defaults to Japan if not specified. RegionType mRegion; /// Specify the language for error messages. This defaults to Japanese if not specified. LangType mLang; /// Specify the file client to use when loading error viewer resources. For more information, see the SDK file system (FS library) function FSAddClient. FSClient* mFSClient; /// Instantiates an object. CreateArg() : mBuffer( NULL ), mRegion( cRegionType_Jp ), mLang( cLangType_Ja ), mFSClient( NULL ) { } }; //------------------------------------------------------------------------------ /** * Construct the error viewer. * * You need a working buffer equal in size to the value obtained with the nn::erreula::GetWorkMemorySize function. * Allocate a buffer of the size obtained and specify it in the parameter. * If you omit this parameter, working memory is allocated using the MEMAllocFromDefaultHeapEx function. * * 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. * 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. * * 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. * Call GX2Init in advance for the same reason. * * The OSDynLoad_SetAllocator function is also used internally. * Note that if there is already an allocator set by the application, it will be overwritten. * * 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. * For more on affinity, see CreateThread in the Cafe SDK API Reference. * * @param[in] arg Initialization class. * * @return Returns true if the object is constructed successfully. */ bool Create( const nn::erreula::CreateArg& arg ); //------------------------------------------------------------------------------ /** * Gets the memory size required to create the error viewer. * * @return Returns the memory size (in bytes) required to create the error viewer. */ u32 GetWorkMemorySize(); //------------------------------------------------------------------------------ /** * Closes the library. * When no parameters were specified for the nn::erreula::Create function, the memory allocated from the MEMAllocFromDefaultHeapEx function is deallocated within this function. * * 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. * For more on affinity, see CreateThread in the Cafe SDK API Reference. */ void Destroy(); //------------------------------------------------------------------------------ /** * This class is for passing controller input to the error viewer. * Pass as parameters to the nn::erreula::Calc function. The VPAD / KPADStatus structure is maintained by making an internal copy. * Because the VPADGetTPCalibratedPoint function is not called within the library, pass the values calibrated by the application using data obtained by the VPADRead function. */ class ControllerInfo { public: /// Data obtained from VPADRead. const VPADStatus* vpad_status; /// Data obtained from KPADRead. const KPADStatus* kpad_status[ WPAD_MAX_CONTROLLERS ]; /// Instantiates an object. ControllerInfo() : vpad_status( NULL ) { for( int i = 0; i < WPAD_MAX_CONTROLLERS; ++i ) { kpad_status[i] = NULL; } } }; //------------------------------------------------------------------------------ /** * The main error viewer process. Call this function in every game frame. * * @param[in] controller_info Controller input information. */ void Calc( const nn::erreula::ControllerInfo& controller_info ); //------------------------------------------------------------------------------ /** * Issues commands for rendering graphics for display on the TV. * The library does not create a frame buffer. * * Also refer to the demo/erreula/simple sample program included in the package. */ void DrawTV(); //------------------------------------------------------------------------------ /** * Issues commands for rendering graphics for display on the Wii U GamePad (DRC). * The library does not create a frame buffer. * * Also refer to the demo/erreula/simple sample program included in the package. */ void DrawDRC(); //------------------------------------------------------------------------------ /** * Displays the error viewer. * * @param[in] arg Specifies the class for setting options. * @note Call this function after confirming that the error viewer is being hidden (nn::erreula::cState_Blank). */ void AppearErrorViewer( const nn::erreula::AppearArg& arg ); //------------------------------------------------------------------------------ /** * Reverts the displayed error viewer to the hidden state. * * @note Call this function after confirming that the error viewer is being displayed (nn::erreula::cState_Display). */ void DisappearErrorViewer(); //------------------------------------------------------------------------------ /** * Gets whether the error viewer's SELECT button was pressed. * This indicates that the user has checked the displayed message, so close the error viewer and transition to the next process. * * @return Returns true if the SELECT button was pressed. * @note Note that once the button has been pressed the same value will be returned until the next call to the nn::erreula::AppearErrorViewer function. * @note This value does not depend on the number of buttons. With more than one button, the function returns true no matter which button is pressed. * @note In the code specification, some error codes require subsequent action, so refer to nn::erreula::ResultType. */ bool IsDecideSelectButtonError(); //------------------------------------------------------------------------------ /** * Gets whether the error viewer's left button was pressed. * * @return Returns true if the SELECT button was pressed. * @note Note that once the button has been pressed the same value will be returned until the next call to the nn::erreula::AppearErrorViewer function. * @note In the code specification, this is normally not used. (Returns true if for some reason the user has canceled execution.) Use the nn::erreula::IsDecideSelectButtonError function to confirm that the button has been pressed, and then refer to nn::erreula::RegionType and move to the next action. */ bool IsDecideSelectLeftButtonError(); //------------------------------------------------------------------------------ /** * Gets whether the error viewer's right button was pressed. * * @return Returns true if the SELECT button was pressed. * @note Note that once the button has been pressed the same value will be returned until the next call to the nn::erreula::AppearErrorViewer function. * @note In the code specification, this is normally not used. (Returns true if for some reason the user has selected execution.) Use the nn::erreula::IsDecideSelectButtonError function to confirm that the button has been pressed, and then refer to nn::erreula::RegionType and move to the next action. */ bool IsDecideSelectRightButtonError(); //------------------------------------------------------------------------------ /** * Gets the display state of the error viewer. * * @retval nn::erreula::cState_Blank Hidden. * @retval nn::erreula::cState_Appear Appearing. * @retval nn::erreula::cState_Display Displayed. * @retval nn::erreula::cState_Disappear Disappearing. */ nn::erreula::State GetStateErrorViewer(); //------------------------------------------------------------------------------ /** * Gets the result type corresponding to the button pressed when the error viewer is displaying. * Refer to nn::erreula::ResultType and move to the next process. * * @return The result type. */ nn::erreula::ResultType GetResultType(); //------------------------------------------------------------------------------ /** * Gets the result code corresponding to the button pressed when the error viewer is displaying. * The meaning of this value varies, depending on the result type, so refer to nn::erreula::ResultType to see how to use the obtained value. * * @return Returns the result code. */ s32 GetResultCode(); //------------------------------------------------------------------------------ /** * Gets the number of error viewer SELECT buttons. * * @return Returns the number of SELECT buttons. */ s32 GetSelectButtonNumError(); //------------------------------------------------------------------------------ /** * Switches the Wii Remote that can operate the error viewer. * * @note If the error viewer is displaying on the Wii U GamePad, even if a Wii Remote has been specified, it is ignored. */ void SetControllerRemo( const nn::erreula::ControllerType type ); //------------------------------------------------------------------------------ /** * Displays the HOME Button prohibition icon. */ void AppearHomeNixSign( const nn::erreula::HomeNixSignArg& arg ); //------------------------------------------------------------------------------ /** * Gets whether the HOME Button prohibition icon is being displayed. */ bool IsAppearHomeNixSign(); //------------------------------------------------------------------------------ /** * Hides the HOME Button prohibition icon. */ void DisappearHomeNixSign(); //------------------------------------------------------------------------------ /** * Changes the language set for the error viewer. * * @param[in] lang Specifies the language to change to. */ void ChangeLangError( const nn::erreula::LangType lang ); //------------------------------------------------------------------------------ /** * Gets whether the selection cursor that indicates whether the focus is on a button is being displayed. * * @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. */ bool IsSelectCursorActive(); //------------------------------------------------------------------------------ /** * Sets whether to play sound effects when displaying the error viewer. * * @param[in] use If true, play sound effects. If false (the default), do not play sound effects. */ void PlayAppearSE( bool use ); //------------------------------------------------------------------------------ /** * When the current nn::erreula::ResultType is nn::erreula::cResultType_Jump, this function jumps to an application or restarts based on the value of the nn::erreula::GetResultCode function. * Also refer to the demo/erreula/jump sample program included in the package. * * @param[in] anchor Specifies the anchor string received by the application when control returns from the jump (up to OS_ARGS_SIZE - 1 bytes). * @param[in] anchorSize Specifies the size, in bytes, of the data passed to anchor. * @return Returns true on success, or false on failure (cannot jump to application). * @note Potential applications to jump to include System Settings, Account Management, and the calling application (restarting the application). * @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.) * @note Until SDK 2.10, the application needed to look at nn::erreula::ResultType or the nn::erreula::GetResultCode function to differentiate between the SYSLaunchAccount, SYSLaunchSettings, and SYSRelaunchTitle functions. The application does not need to do this now if you use the nn::erreula::Jump function. * @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. * @note If the application has been restarted, you can get the anchor string using the OSGetArgcArgv function. * @note If the application has returned from a jump, you can get the anchor string by calling the SYSGetArguments function with SYS_ARG_ID_ANCHOR specified. */ bool Jump( const char* anchor, u32 anchorSize ); ///@} //------------------------------------------------------------------------------ } // namespace erreula //------------------------------------------------------------------------------ } // namespace nn #endif /* NN_ERREULA_API_H_ */