Return to prerror.h CVS log

Up to [Synchronet] / sbbs / include / mozilla / nspr

Annotation of sbbs/include/mozilla/nspr/prerror.h, revision 1.1

1.1     ! root        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 "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___ */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.