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