libnx  v4.7.0
error.h
Go to the documentation of this file.
1 /**
2  * @file error.h
3  * @brief Wrapper for using the error LibraryApplet.
4  * @author StuntHacks, yellows8
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../services/set.h"
10 
11 /// Error type for ErrorCommonHeader.type.
12 typedef enum {
13  ErrorType_Normal = 0, ///< Normal
14  ErrorType_System = 1, ///< System
15  ErrorType_Application = 2, ///< Application
16  ErrorType_Eula = 3, ///< EULA
17  ErrorType_Pctl = 4, ///< Parental Controls
18  ErrorType_Record = 5, ///< Record
19  ErrorType_SystemUpdateEula = 8, ///< SystemUpdateEula
20 } ErrorType;
21 
22 /// Stores error-codes which are displayed as XXXX-XXXX, low for the former and desc for the latter.
23 typedef struct {
24  u32 low; ///< The module portion of the error, normally this should be set to module + 2000.
25  u32 desc; ///< The error description.
26 } ErrorCode;
27 
28 /// Error type for ErrorContext.type
29 typedef enum {
30  ErrorContextType_None = 0, ///< None
31  ErrorContextType_Http = 1, ///< Http
32  ErrorContextType_FileSystem = 2, ///< FileSystem
33  ErrorContextType_WebMediaPlayer = 3, ///< WebMediaPlayer
34  ErrorContextType_LocalContentShare = 4, ///< LocalContentShare
36 
37 /// Error context.
38 typedef struct {
39  u8 type; ///< Type, see \ref ErrorContextType.
40  u8 pad[7]; ///< Padding
41  u8 data[0x1f4]; ///< Data
42  Result res; ///< Result
43 } ErrorContext;
44 
45 /// Common header for the start of the arg storage.
46 typedef struct {
47  u8 type; ///< Type, see \ref ErrorType.
48  u8 jumpFlag; ///< When clear, this indicates WithoutJump.
49  u8 unk_x2[3]; ///< Unknown
50  u8 contextFlag; ///< When set with ::ErrorType_Normal, indicates that an additional storage is pushed for \ref ErrorResultBacktrace. [4.0.0+] Otherwise, when set indicates that an additional storage is pushed for \ref ErrorContext.
51  u8 resultFlag; ///< ErrorCommonArg: When clear, errorCode is used, otherwise the applet generates the error-code from res.
52  u8 contextFlag2; ///< Similar to contextFlag except for ErrorCommonArg, indicating \ref ErrorContext is used.
54 
55 /// Common error arg data.
56 typedef struct {
57  ErrorCommonHeader hdr; ///< Common header.
58  ErrorCode errorCode; ///< \ref ErrorCode
59  Result res; ///< Result
61 
62 /// Error arg data for certain errors with module PCTL.
63 typedef struct {
64  ErrorCommonHeader hdr; ///< Common header.
65  Result res; ///< Result
66 } ErrorPctlArg;
67 
68 /// ResultBacktrace
69 typedef struct {
70  s32 count; ///< Total entries in the backtrace array.
71  Result backtrace[0x20]; ///< Result backtrace.
73 
74 /// Error arg data for EULA.
75 typedef struct {
76  ErrorCommonHeader hdr; ///< Common header.
77  SetRegion regionCode; ///< \ref SetRegion
78 } ErrorEulaArg;
79 
80 /// Additional input storage data for \ref errorSystemUpdateEulaShow.
81 typedef struct {
82  u8 data[0x20000]; ///< data
84 
85 /// Error arg data for Record.
86 typedef struct {
87  ErrorCommonHeader hdr; ///< Common header.
88  ErrorCode errorCode; ///< \ref ErrorCode
89  u64 timestamp; ///< POSIX timestamp.
91 
92 /// SystemErrorArg
93 typedef struct {
94  ErrorCommonHeader hdr; ///< Common header.
95  ErrorCode errorCode; ///< \ref ErrorCode
96  u64 languageCode; ///< See set.h.
97  char dialogMessage[0x800]; ///< UTF-8 Dialog message.
98  char fullscreenMessage[0x800]; ///< UTF-8 Fullscreen message (displayed when the user clicks on "Details").
100 
101 /// Error system config.
102 typedef struct {
103  ErrorSystemArg arg; ///< Arg data.
104  ErrorContext ctx; ///< Optional error context.
106 
107 /// ApplicationErrorArg
108 typedef struct {
109  ErrorCommonHeader hdr; ///< Common header.
110  u32 errorNumber; ///< Raw decimal error number which is displayed in the dialog.
111  u64 languageCode; ///< See set.h.
112  char dialogMessage[0x800]; ///< UTF-8 Dialog message.
113  char fullscreenMessage[0x800]; ///< UTF-8 Fullscreen message (displayed when the user clicks on "Details").
115 
116 /// Error application config.
117 typedef struct {
118  ErrorApplicationArg arg; ///< Arg data.
120 
121 /**
122  * @brief Creates an \ref ErrorCode.
123  * @param low The module portion of the error, normally this should be set to module + 2000.
124  * @param desc The error description.
125  */
126 static inline ErrorCode errorCodeCreate(u32 low, u32 desc) {
127  return (ErrorCode){low, desc};
128 }
129 
130 /**
131  * @brief Creates an \ref ErrorCode with the input Result. Wrapper for \ref errorCodeCreate.
132  * @param res Input Result.
133  */
135  return errorCodeCreate(2000 + R_MODULE(res), R_DESCRIPTION(res));
136 }
137 
138 /**
139  * @brief Creates an invalid \ref ErrorCode.
140  */
141 static inline ErrorCode errorCodeCreateInvalid(void) {
142  return (ErrorCode){0};
143 }
144 
145 /**
146  * @brief Checks whether the input ErrorCode is valid.
147  * @param errorCode \ref ErrorCode
148  */
149 static inline bool errorCodeIsValid(ErrorCode errorCode) {
150  return errorCode.low!=0;
151 }
152 
153 /**
154  * @brief Launches the applet for displaying the specified Result.
155  * @param res Result
156  * @param jumpFlag Jump flag, normally this is true.
157  * @param ctx Optional \ref ErrorContext, can be NULL. Unused when jumpFlag=false. Ignored on pre-4.0.0, since it's only available for [4.0.0+].
158  * @note Sets the following fields: jumpFlag and contextFlag2. Uses ::ErrorType_Normal normally.
159  * @note For module=PCTL errors with desc 100-119 this sets uses ::ErrorType_Pctl, in which case the applet will display the following special dialog: "This software is restricted by Parental Controls".
160  * @note If the input Result is 0xC8A2, the applet will display a special dialog regarding the current application requiring a software update, with buttons "Later" and "Restart".
161  * @note [3.0.0+] If the input Result is 0xCAA2, the applet will display a special dialog related to DLC version.
162  * @warning This applet creates an error report that is logged in the system, when not handling the above special dialogs. Proceed at your own risk!
163  */
164 Result errorResultShow(Result res, bool jumpFlag, const ErrorContext* ctx);
165 
166 /**
167  * @brief Launches the applet for displaying the specified ErrorCode.
168  * @param errorCode \ref ErrorCode
169  * @param jumpFlag Jump flag, normally this is true.
170  * @param ctx Optional \ref ErrorContext, can be NULL. Unused when jumpFlag=false. Ignored on pre-4.0.0, since it's only available for [4.0.0+].
171  * @note Sets the following fields: jumpFlag and contextFlag2. resultFlag=1. Uses ::ErrorType_Normal.
172  * @warning This applet creates an error report that is logged in the system. Proceed at your own risk!
173  */
174 Result errorCodeShow(ErrorCode errorCode, bool jumpFlag, const ErrorContext* ctx);
175 
176 /**
177  * @brief Creates an ErrorResultBacktrace struct.
178  * @param backtrace \ref ErrorResultBacktrace struct.
179  * @param count Total number of entries.
180  * @param entries Input array of Result.
181  */
183 
184 /**
185  * @brief Launches the applet for \ref ErrorResultBacktrace.
186  * @param backtrace ErrorResultBacktrace struct.
187  * @param res Result
188  * @note Sets the following fields: jumpFlag=1, contextFlag=1, and uses ::ErrorType_Normal.
189  * @warning This applet creates an error report that is logged in the system. Proceed at your own risk!
190  */
192 
193 /**
194  * @brief Launches the applet for displaying the EULA.
195  * @param RegionCode \ref SetRegion
196  * @note Sets the following fields: jumpFlag=1, regionCode, and uses ::ErrorType_Eula.
197  */
199 
200 /**
201  * @brief Launches the applet for displaying the system-update EULA.
202  * @param RegionCode \ref SetRegion
203  * @param eula EULA data. Address must be 0x1000-byte aligned.
204  * @note Sets the following fields: jumpFlag=1, regionCode, and uses ::ErrorType_SystemUpdateEula.
205  */
207 
208 /**
209  * @brief Launches the applet for displaying an error full-screen, using the specified ErrorCode and timestamp.
210  * @param errorCode \ref ErrorCode
211  * @param timestamp POSIX timestamp.
212  * @note Sets the following fields: jumpFlag=1, errorCode, timestamp, and uses ::ErrorType_Record.
213  * @note The applet does not log an error report for this. error*RecordShow is used by qlaunch for displaying previously logged error reports.
214  */
215 Result errorCodeRecordShow(ErrorCode errorCode, u64 timestamp);
216 
217 /**
218  * @brief Launches the applet for displaying an error full-screen, using the specified Result and timestamp.
219  * @param res Result
220  * @param timestamp POSIX timestamp.
221  * @note Wrapper for \ref errorCodeRecordShow, see \ref errorCodeRecordShow notes.
222  */
223 static inline Result errorResultRecordShow(Result res, u64 timestamp) {
224  return errorCodeRecordShow(errorCodeCreateResult(res), timestamp);
225 }
226 
227 /**
228  * @brief Creates an ErrorSystemConfig struct.
229  * @param c ErrorSystemConfig struct.
230  * @param dialog_message UTF-8 dialog message.
231  * @param fullscreen_message UTF-8 fullscreen message, displayed when the user clicks on "Details". Optional, can be NULL (which disables displaying Details).
232  * @note Sets the following fields: {strings}, and uses ::ErrorType_System. The rest are cleared.
233  * @note On pre-5.0.0 this will initialize languageCode by using: setInitialize(), setMakeLanguageCode(SetLanguage_ENUS, ...), and setExit(). This is needed since an empty languageCode wasn't supported until [5.0.0+] (which would also use SetLanguage_ENUS).
234  * @warning This applet creates an error report that is logged in the system. Proceed at your own risk!
235  */
236 Result errorSystemCreate(ErrorSystemConfig* c, const char* dialog_message, const char* fullscreen_message);
237 
238 /**
239  * @brief Launches the applet with the specified config.
240  * @param c ErrorSystemConfig struct.
241  */
243 
244 /**
245  * @brief Sets the error code.
246  * @param c ErrorSystemConfig struct.
247  * @param errorCode \ref ErrorCode
248  */
249 static inline void errorSystemSetCode(ErrorSystemConfig* c, ErrorCode errorCode) {
250  c->arg.errorCode = errorCode;
251 }
252 
253 /**
254  * @brief Sets the error code, using the input Result. Wrapper for \ref errorSystemSetCode.
255  * @param c ErrorSystemConfig struct.
256  * @param res The Result to set.
257  */
258 static inline void errorSystemSetResult(ErrorSystemConfig* c, Result res) {
260 }
261 
262 /**
263  * @brief Sets the LanguageCode.
264  * @param c ErrorSystemConfig struct.
265  * @param LanguageCode LanguageCode, see set.h.
266  */
267 static inline void errorSystemSetLanguageCode(ErrorSystemConfig* c, u64 LanguageCode) {
268  c->arg.languageCode = LanguageCode;
269 }
270 
271 /**
272  * @brief Sets the ErrorContext.
273  * @note Only available on [4.0.0+], on older versions this will return without setting the context.
274  * @param c ErrorSystemConfig struct.
275  * @param ctx ErrorContext, NULL to clear it.
276  */
278 
279 /**
280  * @brief Creates an ErrorApplicationConfig struct.
281  * @param c ErrorApplicationConfig struct.
282  * @param dialog_message UTF-8 dialog message.
283  * @param fullscreen_message UTF-8 fullscreen message, displayed when the user clicks on "Details". Optional, can be NULL (which disables displaying Details).
284  * @note Sets the following fields: jumpFlag=1, {strings}, and uses ::ErrorType_Application. The rest are cleared.
285  * @note On pre-5.0.0 this will initialize languageCode by using: setInitialize(), setMakeLanguageCode(SetLanguage_ENUS, ...), and setExit(). This is needed since an empty languageCode wasn't supported until [5.0.0+] (which would also use SetLanguage_ENUS).
286  * @note With [10.0.0+] this must only be used when running under an Application, since otherwise the applet will trigger a fatalerr.
287  * @warning This applet creates an error report that is logged in the system. Proceed at your own risk!
288  */
289 Result errorApplicationCreate(ErrorApplicationConfig* c, const char* dialog_message, const char* fullscreen_message);
290 
291 /**
292  * @brief Launches the applet with the specified config.
293  * @param c ErrorApplicationConfig struct.
294  */
296 
297 /**
298  * @brief Sets the error code number.
299  * @param c ErrorApplicationConfig struct.
300  * @param errorNumber Error code number. Raw decimal error number which is displayed in the dialog.
301  */
302 static inline void errorApplicationSetNumber(ErrorApplicationConfig* c, u32 errorNumber) {
303  c->arg.errorNumber = errorNumber;
304 }
305 
306 /**
307  * @brief Sets the LanguageCode.
308  * @param c ErrorApplicationConfig struct.
309  * @param LanguageCode LanguageCode, see set.h.
310  */
311 static inline void errorApplicationSetLanguageCode(ErrorApplicationConfig* c, u64 LanguageCode) {
312  c->arg.languageCode = LanguageCode;
313 }
314 
Result errorResultBacktraceShow(Result res, const ErrorResultBacktrace *backtrace)
Launches the applet for ErrorResultBacktrace.
Result errorResultBacktraceCreate(ErrorResultBacktrace *backtrace, s32 count, const Result *entries)
Creates an ErrorResultBacktrace struct.
Result errorCodeRecordShow(ErrorCode errorCode, u64 timestamp)
Launches the applet for displaying an error full-screen, using the specified ErrorCode and timestamp.
static void errorSystemSetCode(ErrorSystemConfig *c, ErrorCode errorCode)
Sets the error code.
Definition: error.h:249
static void errorApplicationSetNumber(ErrorApplicationConfig *c, u32 errorNumber)
Sets the error code number.
Definition: error.h:302
Result errorSystemCreate(ErrorSystemConfig *c, const char *dialog_message, const char *fullscreen_message)
Creates an ErrorSystemConfig struct.
static bool errorCodeIsValid(ErrorCode errorCode)
Checks whether the input ErrorCode is valid.
Definition: error.h:149
Result errorEulaShow(SetRegion RegionCode)
Launches the applet for displaying the EULA.
ErrorContextType
Error type for ErrorContext.type.
Definition: error.h:29
@ ErrorContextType_None
None.
Definition: error.h:30
@ ErrorContextType_FileSystem
FileSystem.
Definition: error.h:32
@ ErrorContextType_WebMediaPlayer
WebMediaPlayer.
Definition: error.h:33
@ ErrorContextType_Http
Http.
Definition: error.h:31
@ ErrorContextType_LocalContentShare
LocalContentShare.
Definition: error.h:34
Result errorApplicationShow(ErrorApplicationConfig *c)
Launches the applet with the specified config.
static void errorApplicationSetLanguageCode(ErrorApplicationConfig *c, u64 LanguageCode)
Sets the LanguageCode.
Definition: error.h:311
Result errorCodeShow(ErrorCode errorCode, bool jumpFlag, const ErrorContext *ctx)
Launches the applet for displaying the specified ErrorCode.
Result errorResultShow(Result res, bool jumpFlag, const ErrorContext *ctx)
Launches the applet for displaying the specified Result.
Result errorSystemUpdateEulaShow(SetRegion RegionCode, const ErrorEulaData *eula)
Launches the applet for displaying the system-update EULA.
Result errorApplicationCreate(ErrorApplicationConfig *c, const char *dialog_message, const char *fullscreen_message)
Creates an ErrorApplicationConfig struct.
static ErrorCode errorCodeCreate(u32 low, u32 desc)
Creates an ErrorCode.
Definition: error.h:126
static ErrorCode errorCodeCreateInvalid(void)
Creates an invalid ErrorCode.
Definition: error.h:141
ErrorType
Error type for ErrorCommonHeader.type.
Definition: error.h:12
@ ErrorType_Application
Application.
Definition: error.h:15
@ ErrorType_System
System.
Definition: error.h:14
@ ErrorType_Eula
EULA.
Definition: error.h:16
@ ErrorType_SystemUpdateEula
SystemUpdateEula.
Definition: error.h:19
@ ErrorType_Normal
Normal.
Definition: error.h:13
@ ErrorType_Pctl
Parental Controls.
Definition: error.h:17
@ ErrorType_Record
Record.
Definition: error.h:18
void errorSystemSetContext(ErrorSystemConfig *c, const ErrorContext *ctx)
Sets the ErrorContext.
static void errorSystemSetResult(ErrorSystemConfig *c, Result res)
Sets the error code, using the input Result.
Definition: error.h:258
static void errorSystemSetLanguageCode(ErrorSystemConfig *c, u64 LanguageCode)
Sets the LanguageCode.
Definition: error.h:267
Result errorSystemShow(ErrorSystemConfig *c)
Launches the applet with the specified config.
static ErrorCode errorCodeCreateResult(Result res)
Creates an ErrorCode with the input Result.
Definition: error.h:134
static Result errorResultRecordShow(Result res, u64 timestamp)
Launches the applet for displaying an error full-screen, using the specified Result and timestamp.
Definition: error.h:223
#define R_MODULE(res)
Returns the module ID of a result code.
Definition: result.h:14
#define R_DESCRIPTION(res)
Returns the description of a result code.
Definition: result.h:16
SetRegion
Region codes.
Definition: set.h:62
ApplicationErrorArg.
Definition: error.h:108
ErrorCommonHeader hdr
Common header.
Definition: error.h:109
u64 languageCode
See set.h.
Definition: error.h:111
u32 errorNumber
Raw decimal error number which is displayed in the dialog.
Definition: error.h:110
Error application config.
Definition: error.h:117
ErrorApplicationArg arg
Arg data.
Definition: error.h:118
Stores error-codes which are displayed as XXXX-XXXX, low for the former and desc for the latter.
Definition: error.h:23
u32 low
The module portion of the error, normally this should be set to module + 2000.
Definition: error.h:24
u32 desc
The error description.
Definition: error.h:25
Common error arg data.
Definition: error.h:56
ErrorCode errorCode
ErrorCode
Definition: error.h:58
ErrorCommonHeader hdr
Common header.
Definition: error.h:57
Result res
Result.
Definition: error.h:59
Common header for the start of the arg storage.
Definition: error.h:46
u8 resultFlag
ErrorCommonArg: When clear, errorCode is used, otherwise the applet generates the error-code from res...
Definition: error.h:51
u8 type
Type, see ErrorType.
Definition: error.h:47
u8 jumpFlag
When clear, this indicates WithoutJump.
Definition: error.h:48
u8 contextFlag
When set with ErrorType_Normal, indicates that an additional storage is pushed for ErrorResultBacktra...
Definition: error.h:50
u8 contextFlag2
Similar to contextFlag except for ErrorCommonArg, indicating ErrorContext is used.
Definition: error.h:52
Error context.
Definition: error.h:38
Result res
Result.
Definition: error.h:42
u8 type
Type, see ErrorContextType.
Definition: error.h:39
Error arg data for EULA.
Definition: error.h:75
ErrorCommonHeader hdr
Common header.
Definition: error.h:76
SetRegion regionCode
SetRegion
Definition: error.h:77
Additional input storage data for errorSystemUpdateEulaShow.
Definition: error.h:81
Error arg data for certain errors with module PCTL.
Definition: error.h:63
Result res
Result.
Definition: error.h:65
ErrorCommonHeader hdr
Common header.
Definition: error.h:64
Error arg data for Record.
Definition: error.h:86
u64 timestamp
POSIX timestamp.
Definition: error.h:89
ErrorCommonHeader hdr
Common header.
Definition: error.h:87
ErrorCode errorCode
ErrorCode
Definition: error.h:88
ResultBacktrace.
Definition: error.h:69
s32 count
Total entries in the backtrace array.
Definition: error.h:70
SystemErrorArg.
Definition: error.h:93
ErrorCommonHeader hdr
Common header.
Definition: error.h:94
ErrorCode errorCode
ErrorCode
Definition: error.h:95
u64 languageCode
See set.h.
Definition: error.h:96
Error system config.
Definition: error.h:102
ErrorContext ctx
Optional error context.
Definition: error.h:104
ErrorSystemArg arg
Arg data.
Definition: error.h:103
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
#define NX_PACKED
Packs a struct so that it won't include padding bytes.
Definition: types.h:63
u32 Result
Function error code result type.
Definition: types.h:44
int32_t s32
32-bit signed integer.
Definition: types.h:27
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21