nsprpub/pr/include/prerror.h

   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___ */