prerror.h (11505B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #ifndef prerror_h___ 7 #define prerror_h___ 8 9 #include "prtypes.h" 10 11 PR_BEGIN_EXTERN_C 12 13 typedef PRInt32 PRErrorCode; 14 15 #define PR_NSPR_ERROR_BASE -6000 16 17 #include "prerr.h" 18 19 /* 20 ** Set error will preserve an error condition within a thread context. 21 ** The values stored are the NSPR (platform independent) translation of 22 ** the error. Also, if available, the platform specific oserror is stored. 23 ** If there is no appropriate OS error number, a zero my be supplied. 24 */ 25 NSPR_API(void) PR_SetError(PRErrorCode errorCode, PRInt32 oserr); 26 27 /* 28 ** The text value specified may be NULL. If it is not NULL and the text length 29 ** is zero, the string is assumed to be a null terminated C string. Otherwise 30 ** the text is assumed to be the length specified and possibly include NULL 31 ** characters (e.g., a multi-national string). 32 ** 33 ** The text will be copied into to thread structure and remain there 34 ** until the next call to PR_SetError. 35 */ 36 NSPR_API(void) PR_SetErrorText( 37 PRIntn textLength, const char *text); 38 39 /* 40 ** Return the current threads last set error code. 41 */ 42 NSPR_API(PRErrorCode) PR_GetError(void); 43 44 /* 45 ** Return the current threads last set os error code. This is used for 46 ** machine specific code that desires the underlying os error. 47 */ 48 NSPR_API(PRInt32) PR_GetOSError(void); 49 50 /* 51 ** Get the length of the error text. If a zero is returned, then there 52 ** is no text. Otherwise, the value returned is sufficient to contain 53 ** the error text currently available. 54 */ 55 NSPR_API(PRInt32) PR_GetErrorTextLength(void); 56 57 /* 58 ** Copy the current threads current error text. Then actual number of bytes 59 ** copied is returned as the result. If the result is zero, the 'text' area 60 ** is unaffected. 61 */ 62 NSPR_API(PRInt32) PR_GetErrorText(char *text); 63 64 65 /* 66 Copyright (C) 1987, 1988 Student Information Processing Board of the 67 Massachusetts Institute of Technology. 68 69 Permission to use, copy, modify, and distribute this software and its 70 documentation for any purpose and without fee is hereby granted, provided 71 that the above copyright notice appear in all copies and that both that 72 copyright notice and this permission notice appear in supporting 73 documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 74 used in advertising or publicity pertaining to distribution of the software 75 without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B. 76 make no representations about the suitability of this software for any 77 purpose. It is provided "as is" without express or implied warranty. 78 */ 79 80 81 /* 82 * NOTE: 83 * The interfaces for error-code-translation described in the rest of 84 * this file are preliminary in the 3.1 release of nspr and are subject 85 * to change in future releases. 86 */ 87 88 /* 89 ** Description: Localizable error code to string function. 90 ** 91 ** 92 ** NSPR provides a mechanism for converting an error code to a 93 ** descriptive string, in a caller-specified language. 94 ** 95 ** Error codes themselves are 32 bit (signed) integers. Typically, 96 ** the high order 24 bits are an identifier of which error table the 97 ** error code is from, and the low order 8 bits are a sequential error 98 ** number within the table. NSPR supports error tables whose first 99 ** error code is not a multiple of 256, such error code assignments 100 ** should be avoided when possible. 101 ** 102 ** Error table 0 is defined to match the UNIX system call error table 103 ** (sys_errlist); this allows errno values to be used directly in the 104 ** library. Other error table numbers are typically formed by 105 ** compacting together the first four characters of the error table 106 ** name. The mapping between characters in the name and numeric 107 ** values in the error code are defined in a system-independent 108 ** fashion, so that two systems that can pass integral values between 109 ** them can reliably pass error codes without loss of meaning; this 110 ** should work even if the character sets used are not the 111 ** same. (However, if this is to be done, error table 0 should be 112 ** avoided, since the local system call error tables may differ.) 113 ** 114 ** Libraries defining error codes need only provide a table mapping 115 ** error code numbers to names and default English descriptions, 116 ** calling a routine to install the table, making it ``known'' to NSPR 117 ** library. Once installed, a table may not be removed. Any error 118 ** code the library generates can be converted to the corresponding 119 ** error message. There is also a default format for error codes 120 ** accidentally returned before making the table known, which is of 121 ** the form "unknown code foo 32", where "foo" would be the name of 122 ** the table. 123 ** 124 ** Normally, the error code conversion routine only supports the 125 ** languages "i-default" and "en", returning the error-table-provided 126 ** English description for both languages. The application may 127 ** provide a localization plugin, allowing support for additional 128 ** languages. 129 ** 130 **/ 131 132 /**********************************************************************/ 133 /************************* TYPES AND CONSTANTS ************************/ 134 /**********************************************************************/ 135 136 /* 137 * PRLanguageCode -- 138 * 139 * NSPR represents a language code as a non-negative integer. 140 * Languages 0 is always "i-default" the language you get without 141 * explicit negotiation. Language 1 is always "en", English 142 * which has been explicitly negotiated. Additional language 143 * codes are defined by an application-provided localization plugin. 144 */ 145 typedef PRUint32 PRLanguageCode; 146 #define PR_LANGUAGE_I_DEFAULT 0 /* i-default, the default language */ 147 #define PR_LANGUAGE_EN 1 /* English, explicitly negotiated */ 148 149 /* 150 * struct PRErrorMessage -- 151 * 152 * An error message in an error table. 153 */ 154 struct PRErrorMessage { 155 const char * name; /* Macro name for error */ 156 const char * en_text; /* Default English text */ 157 }; 158 159 /* 160 * struct PRErrorTable -- 161 * 162 * An error table, provided by a library. 163 */ 164 struct PRErrorTable { 165 const struct PRErrorMessage * msgs; /* Array of error information */ 166 const char *name; /* Name of error table source */ 167 PRErrorCode base; /* Error code for first error in table */ 168 int n_msgs; /* Number of codes in table */ 169 }; 170 171 /* 172 * struct PRErrorCallbackPrivate -- 173 * 174 * A private structure for the localization plugin 175 */ 176 struct PRErrorCallbackPrivate; 177 178 /* 179 * struct PRErrorCallbackTablePrivate -- 180 * 181 * A data structure under which the localization plugin may store information, 182 * associated with an error table, that is private to itself. 183 */ 184 struct PRErrorCallbackTablePrivate; 185 186 /* 187 * PRErrorCallbackLookupFn -- 188 * 189 * A function of PRErrorCallbackLookupFn type is a localization 190 * plugin callback which converts an error code into a description 191 * in the requested language. The callback is provided the 192 * appropriate error table, private data for the plugin and the table. 193 * The callback returns the appropriate UTF-8 encoded description, or NULL 194 * if no description can be found. 195 */ 196 typedef const char * 197 PRErrorCallbackLookupFn(PRErrorCode code, PRLanguageCode language, 198 const struct PRErrorTable *table, 199 struct PRErrorCallbackPrivate *cb_private, 200 struct PRErrorCallbackTablePrivate *table_private); 201 202 /* 203 * PRErrorCallbackNewTableFn -- 204 * 205 * A function PRErrorCallbackNewTableFn type is a localization plugin 206 * callback which is called once with each error table registered 207 * with NSPR. The callback is provided with the error table and 208 * the plugin's private structure. The callback returns any table private 209 * data it wishes to associate with the error table. Does not need to be thread 210 * safe. 211 */ 212 typedef struct PRErrorCallbackTablePrivate * 213 PRErrorCallbackNewTableFn(const struct PRErrorTable *table, 214 struct PRErrorCallbackPrivate *cb_private); 215 216 /**********************************************************************/ 217 /****************************** FUNCTIONS *****************************/ 218 /**********************************************************************/ 219 220 /*********************************************************************** 221 ** FUNCTION: PR_ErrorToString 222 ** DESCRIPTION: 223 ** Returns the UTF-8 message for an error code in 224 ** the requested language. May return the message 225 ** in the default language if a translation in the requested 226 ** language is not available. The returned string is 227 ** valid for the duration of the process. Never returns NULL. 228 ** 229 ***********************************************************************/ 230 NSPR_API(const char *) PR_ErrorToString(PRErrorCode code, 231 PRLanguageCode language); 232 233 234 /*********************************************************************** 235 ** FUNCTION: PR_ErrorToName 236 ** DESCRIPTION: 237 ** Returns the macro name for an error code, or NULL 238 ** if the error code is not known. The returned string is 239 ** valid for the duration of the process. 240 ** 241 ** Does not work for error table 0, the system error codes. 242 ** 243 ***********************************************************************/ 244 NSPR_API(const char *) PR_ErrorToName(PRErrorCode code); 245 246 247 /*********************************************************************** 248 ** FUNCTION: PR_ErrorLanguages 249 ** DESCRIPTION: 250 ** Returns the RFC 1766 language tags for the language 251 ** codes PR_ErrorToString() supports. The returned array is valid 252 ** for the duration of the process. Never returns NULL. The first 253 ** item in the returned array is the language tag for PRLanguageCode 0, 254 ** the second is for PRLanguageCode 1, and so on. The array is terminated 255 ** with a null pointer. 256 ** 257 ***********************************************************************/ 258 NSPR_API(const char * const *) PR_ErrorLanguages(void); 259 260 261 /*********************************************************************** 262 ** FUNCTION: PR_ErrorInstallTable 263 ** DESCRIPTION: 264 ** Registers an error table with NSPR. Must be done exactly once per 265 ** table. Memory pointed to by `table' must remain valid for the life 266 ** of the process. 267 ** 268 ** NOT THREAD SAFE! 269 ** 270 ***********************************************************************/ 271 NSPR_API(PRErrorCode) PR_ErrorInstallTable(const struct PRErrorTable *table); 272 273 274 /*********************************************************************** 275 ** FUNCTION: PR_ErrorInstallCallback 276 ** DESCRIPTION: 277 ** Registers an error localization plugin with NSPR. May be called 278 ** at most one time. `languages' contains the language codes supported 279 ** by this plugin. Languages 0 and 1 must be "i-default" and "en" 280 ** respectively. `lookup' and `newtable' contain pointers to 281 ** the plugin callback functions. `cb_private' contains any information 282 ** private to the plugin functions. 283 ** 284 ** NOT THREAD SAFE! 285 ** 286 ***********************************************************************/ 287 NSPR_API(void) PR_ErrorInstallCallback(const char * const * languages, 288 PRErrorCallbackLookupFn *lookup, 289 PRErrorCallbackNewTableFn *newtable, 290 struct PRErrorCallbackPrivate *cb_private); 291 292 PR_END_EXTERN_C 293 294 #endif /* prerror_h___ */