OSX/libsecurity_asn1/lib/prerror.h

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