Back to index

lightning-sunbird  0.9+nobinonly
prerror.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prerror_h___
00039 #define prerror_h___
00040 
00041 #include "prtypes.h"
00042 
00043 PR_BEGIN_EXTERN_C
00044 
00045 typedef PRInt32 PRErrorCode;
00046 
00047 #define PR_NSPR_ERROR_BASE -6000
00048 
00049 #include "prerr.h"
00050 
00051 /*
00052 ** Set error will preserve an error condition within a thread context.
00053 ** The values stored are the NSPR (platform independent) translation of
00054 ** the error. Also, if available, the platform specific oserror is stored.
00055 ** If there is no appropriate OS error number, a zero my be supplied.
00056 */
00057 NSPR_API(void) PR_SetError(PRErrorCode errorCode, PRInt32 oserr);
00058 
00059 /*
00060 ** The text value specified may be NULL. If it is not NULL and the text length
00061 ** is zero, the string is assumed to be a null terminated C string. Otherwise
00062 ** the text is assumed to be the length specified and possibly include NULL
00063 ** characters (e.g., a multi-national string).
00064 **
00065 ** The text will be copied into to thread structure and remain there
00066 ** until the next call to PR_SetError.
00067 */
00068 NSPR_API(void) PR_SetErrorText(
00069     PRIntn textLength, const char *text);
00070 
00071 /*
00072 ** Return the current threads last set error code.
00073 */
00074 NSPR_API(PRErrorCode) PR_GetError(void);
00075 
00076 /*
00077 ** Return the current threads last set os error code. This is used for
00078 ** machine specific code that desires the underlying os error.
00079 */
00080 NSPR_API(PRInt32) PR_GetOSError(void);
00081 
00082 /*
00083 ** Get the length of the error text. If a zero is returned, then there
00084 ** is no text. Otherwise, the value returned is sufficient to contain
00085 ** the error text currently available.
00086 */
00087 NSPR_API(PRInt32) PR_GetErrorTextLength(void);
00088 
00089 /*
00090 ** Copy the current threads current error text. Then actual number of bytes
00091 ** copied is returned as the result. If the result is zero, the 'text' area
00092 ** is unaffected.
00093 */
00094 NSPR_API(PRInt32) PR_GetErrorText(char *text);
00095 
00096 
00097 /*
00098 Copyright (C) 1987, 1988 Student Information Processing Board of the
00099 Massachusetts Institute of Technology.
00100 
00101 Permission to use, copy, modify, and distribute this software and its
00102 documentation for any purpose and without fee is hereby granted, provided
00103 that the above copyright notice appear in all copies and that both that
00104 copyright notice and this permission notice appear in supporting
00105 documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
00106 used in advertising or publicity pertaining to distribution of the software
00107 without specific, written prior permission.  M.I.T. and the M.I.T. S.I.P.B.
00108 make no representations about the suitability of this software for any
00109 purpose.  It is provided "as is" without express or implied warranty.
00110 */
00111 
00112 
00113 /*
00114  * NOTE:
00115  *            The interfaces for error-code-translation described in the rest of
00116  *            this file are preliminary in the 3.1 release of nspr and are subject 
00117  *            to change in future releases.
00118  */
00119 
00120 /*
00121 ** Description:      Localizable error code to string function.
00122 **
00123 **
00124 ** NSPR provides a mechanism for converting an error code to a
00125 ** descriptive string, in a caller-specified language.
00126 **
00127 ** Error codes themselves are 32 bit (signed) integers.  Typically,
00128 ** the high order 24 bits are an identifier of which error table the
00129 ** error code is from, and the low order 8 bits are a sequential error
00130 ** number within the table.  NSPR supports error tables whose first
00131 ** error code is not a multiple of 256, such error code assignments
00132 ** should be avoided when possible.
00133 **
00134 ** Error table 0 is defined to match the UNIX system call error table
00135 ** (sys_errlist); this allows errno values to be used directly in the
00136 ** library.  Other error table numbers are typically formed by
00137 ** compacting together the first four characters of the error table
00138 ** name.  The mapping between characters in the name and numeric
00139 ** values in the error code are defined in a system-independent
00140 ** fashion, so that two systems that can pass integral values between
00141 ** them can reliably pass error codes without loss of meaning; this
00142 ** should work even if the character sets used are not the
00143 ** same. (However, if this is to be done, error table 0 should be
00144 ** avoided, since the local system call error tables may differ.)
00145 **
00146 ** Libraries defining error codes need only provide a table mapping
00147 ** error code numbers to names and default English descriptions,
00148 ** calling a routine to install the table, making it ``known'' to NSPR
00149 ** library.  Once installed, a table may not be removed.  Any error
00150 ** code the library generates can be converted to the corresponding
00151 ** error message.  There is also a default format for error codes
00152 ** accidentally returned before making the table known, which is of
00153 ** the form "unknown code foo 32", where "foo" would be the name of
00154 ** the table.
00155 **
00156 ** Normally, the error code conversion routine only supports the
00157 ** languages "i-default" and "en", returning the error-table-provided
00158 ** English description for both languages.  The application may
00159 ** provide a localization plugin, allowing support for additional
00160 ** languages.
00161 **
00162 **/
00163 
00164 /**********************************************************************/
00165 /************************* TYPES AND CONSTANTS ************************/
00166 /**********************************************************************/
00167 
00168 /*
00169  * PRLanguageCode --
00170  *
00171  *    NSPR represents a language code as a non-negative integer.
00172  *    Languages 0 is always "i-default" the language you get without
00173  *    explicit negotiation.  Language 1 is always "en", English
00174  *    which has been explicitly negotiated.  Additional language
00175  *    codes are defined by an application-provided localization plugin.
00176  */
00177 typedef PRUint32 PRLanguageCode;
00178 #define PR_LANGUAGE_I_DEFAULT 0 /* i-default, the default language */
00179 #define PR_LANGUAGE_EN 1 /* English, explicitly negotiated */
00180 
00181 /*
00182  * struct PRErrorMessage --
00183  *
00184  *    An error message in an error table.
00185  */
00186 struct PRErrorMessage {
00187     const char * name;    /* Macro name for error */
00188     const char * en_text; /* Default English text */
00189 };
00190 
00191 /*
00192  * struct PRErrorTable --
00193  *
00194  *    An error table, provided by a library.
00195  */
00196 struct PRErrorTable {
00197     const struct PRErrorMessage * msgs; /* Array of error information */
00198     const char *name; /* Name of error table source */
00199     PRErrorCode base; /* Error code for first error in table */
00200     int n_msgs; /* Number of codes in table */
00201 };
00202 
00203 /*
00204  * struct PRErrorCallbackPrivate --
00205  *
00206  *    A private structure for the localization plugin 
00207  */
00208 struct PRErrorCallbackPrivate;
00209 
00210 /*
00211  * struct PRErrorCallbackTablePrivate --
00212  *
00213  *    A data structure under which the localization plugin may store information,
00214  *    associated with an error table, that is private to itself.
00215  */
00216 struct PRErrorCallbackTablePrivate;
00217 
00218 /*
00219  * PRErrorCallbackLookupFn --
00220  *
00221  *    A function of PRErrorCallbackLookupFn type is a localization
00222  *    plugin callback which converts an error code into a description
00223  *    in the requested language.  The callback is provided the
00224  *    appropriate error table, private data for the plugin and the table.
00225  *    The callback returns the appropriate UTF-8 encoded description, or NULL
00226  *    if no description can be found.
00227  */
00228 typedef const char *
00229 PRErrorCallbackLookupFn(PRErrorCode code, PRLanguageCode language, 
00230                  const struct PRErrorTable *table,
00231                  struct PRErrorCallbackPrivate *cb_private,
00232                  struct PRErrorCallbackTablePrivate *table_private);
00233 
00234 /*
00235  * PRErrorCallbackNewTableFn --
00236  *
00237  *    A function PRErrorCallbackNewTableFn type is a localization plugin
00238  *    callback which is called once with each error table registered
00239  *    with NSPR.  The callback is provided with the error table and
00240  *    the plugin's private structure.  The callback returns any table private
00241  *    data it wishes to associate with the error table.  Does not need to be thread
00242  *    safe.
00243  */
00244 typedef struct PRErrorCallbackTablePrivate *
00245 PRErrorCallbackNewTableFn(const struct PRErrorTable *table,
00246                      struct PRErrorCallbackPrivate *cb_private);
00247 
00248 /**********************************************************************/
00249 /****************************** FUNCTIONS *****************************/
00250 /**********************************************************************/
00251 
00252 /***********************************************************************
00253 ** FUNCTION:    PR_ErrorToString
00254 ** DESCRIPTION:
00255 **  Returns the UTF-8 message for an error code in
00256 **  the requested language.  May return the message
00257 **  in the default language if a translation in the requested
00258 **  language is not available.  The returned string is
00259 **  valid for the duration of the process.  Never returns NULL.
00260 **
00261 ***********************************************************************/
00262 NSPR_API(const char *) PR_ErrorToString(PRErrorCode code,
00263     PRLanguageCode language);
00264 
00265 
00266 /***********************************************************************
00267 ** FUNCTION:    PR_ErrorToName
00268 ** DESCRIPTION:
00269 **  Returns the macro name for an error code, or NULL
00270 **  if the error code is not known.  The returned string is
00271 **  valid for the duration of the process.
00272 **
00273 **  Does not work for error table 0, the system error codes.
00274 **
00275 ***********************************************************************/
00276 NSPR_API(const char *) PR_ErrorToName(PRErrorCode code);
00277 
00278 
00279 /***********************************************************************
00280 ** FUNCTION:    PR_ErrorLanguages
00281 ** DESCRIPTION:
00282 **  Returns the RFC 1766 language tags for the language
00283 **  codes PR_ErrorToString() supports.  The returned array is valid
00284 **  for the duration of the process.  Never returns NULL.  The first
00285 **  item in the returned array is the language tag for PRLanguageCode 0,
00286 **  the second is for PRLanguageCode 1, and so on.  The array is terminated
00287 **  with a null pointer.
00288 **
00289 ***********************************************************************/
00290 NSPR_API(const char * const *) PR_ErrorLanguages(void);
00291 
00292 
00293 /***********************************************************************
00294 ** FUNCTION:    PR_ErrorInstallTable
00295 ** DESCRIPTION:
00296 **  Registers an error table with NSPR.  Must be done exactly once per
00297 **  table.  Memory pointed to by `table' must remain valid for the life
00298 **  of the process.
00299 **
00300 **  NOT THREAD SAFE!
00301 **  
00302 ***********************************************************************/
00303 NSPR_API(PRErrorCode) PR_ErrorInstallTable(const struct PRErrorTable *table);
00304 
00305 
00306 /***********************************************************************
00307 ** FUNCTION:    PR_ErrorInstallCallback
00308 ** DESCRIPTION:
00309 **  Registers an error localization plugin with NSPR.  May be called
00310 **  at most one time.  `languages' contains the language codes supported
00311 **  by this plugin.  Languages 0 and 1 must be "i-default" and "en"
00312 **  respectively.  `lookup' and `newtable' contain pointers to
00313 **  the plugin callback functions.  `cb_private' contains any information
00314 **  private to the plugin functions.
00315 **
00316 **  NOT THREAD SAFE!
00317 **
00318 ***********************************************************************/
00319 NSPR_API(void) PR_ErrorInstallCallback(const char * const * languages,
00320                            PRErrorCallbackLookupFn *lookup, 
00321                            PRErrorCallbackNewTableFn *newtable,
00322                            struct PRErrorCallbackPrivate *cb_private);
00323 
00324 PR_END_EXTERN_C
00325 
00326 #endif /* prerror_h___ */