michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef prerror_h___
michael@0: #define prerror_h___
michael@0: 
michael@0: #include "prtypes.h"
michael@0: 
michael@0: PR_BEGIN_EXTERN_C
michael@0: 
michael@0: typedef PRInt32 PRErrorCode;
michael@0: 
michael@0: #define PR_NSPR_ERROR_BASE -6000
michael@0: 
michael@0: #include "prerr.h"
michael@0: 
michael@0: /*
michael@0: ** Set error will preserve an error condition within a thread context.
michael@0: ** The values stored are the NSPR (platform independent) translation of
michael@0: ** the error. Also, if available, the platform specific oserror is stored.
michael@0: ** If there is no appropriate OS error number, a zero my be supplied.
michael@0: */
michael@0: NSPR_API(void) PR_SetError(PRErrorCode errorCode, PRInt32 oserr);
michael@0: 
michael@0: /*
michael@0: ** The text value specified may be NULL. If it is not NULL and the text length
michael@0: ** is zero, the string is assumed to be a null terminated C string. Otherwise
michael@0: ** the text is assumed to be the length specified and possibly include NULL
michael@0: ** characters (e.g., a multi-national string).
michael@0: **
michael@0: ** The text will be copied into to thread structure and remain there
michael@0: ** until the next call to PR_SetError.
michael@0: */
michael@0: NSPR_API(void) PR_SetErrorText(
michael@0:     PRIntn textLength, const char *text);
michael@0: 
michael@0: /*
michael@0: ** Return the current threads last set error code.
michael@0: */
michael@0: NSPR_API(PRErrorCode) PR_GetError(void);
michael@0: 
michael@0: /*
michael@0: ** Return the current threads last set os error code. This is used for
michael@0: ** machine specific code that desires the underlying os error.
michael@0: */
michael@0: NSPR_API(PRInt32) PR_GetOSError(void);
michael@0: 
michael@0: /*
michael@0: ** Get the length of the error text. If a zero is returned, then there
michael@0: ** is no text. Otherwise, the value returned is sufficient to contain
michael@0: ** the error text currently available.
michael@0: */
michael@0: NSPR_API(PRInt32) PR_GetErrorTextLength(void);
michael@0: 
michael@0: /*
michael@0: ** Copy the current threads current error text. Then actual number of bytes
michael@0: ** copied is returned as the result. If the result is zero, the 'text' area
michael@0: ** is unaffected.
michael@0: */
michael@0: NSPR_API(PRInt32) PR_GetErrorText(char *text);
michael@0: 
michael@0: 
michael@0: /*
michael@0: Copyright (C) 1987, 1988 Student Information Processing Board of the
michael@0: Massachusetts Institute of Technology.
michael@0: 
michael@0: Permission to use, copy, modify, and distribute this software and its
michael@0: documentation for any purpose and without fee is hereby granted, provided
michael@0: that the above copyright notice appear in all copies and that both that
michael@0: copyright notice and this permission notice appear in supporting
michael@0: documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
michael@0: used in advertising or publicity pertaining to distribution of the software
michael@0: without specific, written prior permission.  M.I.T. and the M.I.T. S.I.P.B.
michael@0: make no representations about the suitability of this software for any
michael@0: purpose.  It is provided "as is" without express or implied warranty.
michael@0: */
michael@0: 
michael@0: 
michael@0: /*
michael@0:  * NOTE:
michael@0:  *		The interfaces for error-code-translation described in the rest of
michael@0:  *		this file are preliminary in the 3.1 release of nspr and are subject 
michael@0:  *		to change in future releases.
michael@0:  */
michael@0: 
michael@0: /*
michael@0: ** Description:	Localizable error code to string function.
michael@0: **
michael@0: **
michael@0: ** NSPR provides a mechanism for converting an error code to a
michael@0: ** descriptive string, in a caller-specified language.
michael@0: **
michael@0: ** Error codes themselves are 32 bit (signed) integers.  Typically,
michael@0: ** the high order 24 bits are an identifier of which error table the
michael@0: ** error code is from, and the low order 8 bits are a sequential error
michael@0: ** number within the table.  NSPR supports error tables whose first
michael@0: ** error code is not a multiple of 256, such error code assignments
michael@0: ** should be avoided when possible.
michael@0: **
michael@0: ** Error table 0 is defined to match the UNIX system call error table
michael@0: ** (sys_errlist); this allows errno values to be used directly in the
michael@0: ** library.  Other error table numbers are typically formed by
michael@0: ** compacting together the first four characters of the error table
michael@0: ** name.  The mapping between characters in the name and numeric
michael@0: ** values in the error code are defined in a system-independent
michael@0: ** fashion, so that two systems that can pass integral values between
michael@0: ** them can reliably pass error codes without loss of meaning; this
michael@0: ** should work even if the character sets used are not the
michael@0: ** same. (However, if this is to be done, error table 0 should be
michael@0: ** avoided, since the local system call error tables may differ.)
michael@0: **
michael@0: ** Libraries defining error codes need only provide a table mapping
michael@0: ** error code numbers to names and default English descriptions,
michael@0: ** calling a routine to install the table, making it ``known'' to NSPR
michael@0: ** library.  Once installed, a table may not be removed.  Any error
michael@0: ** code the library generates can be converted to the corresponding
michael@0: ** error message.  There is also a default format for error codes
michael@0: ** accidentally returned before making the table known, which is of
michael@0: ** the form "unknown code foo 32", where "foo" would be the name of
michael@0: ** the table.
michael@0: **
michael@0: ** Normally, the error code conversion routine only supports the
michael@0: ** languages "i-default" and "en", returning the error-table-provided
michael@0: ** English description for both languages.  The application may
michael@0: ** provide a localization plugin, allowing support for additional
michael@0: ** languages.
michael@0: **
michael@0: **/
michael@0: 
michael@0: /**********************************************************************/
michael@0: /************************* TYPES AND CONSTANTS ************************/
michael@0: /**********************************************************************/
michael@0: 
michael@0: /*
michael@0:  * PRLanguageCode --
michael@0:  *
michael@0:  *    NSPR represents a language code as a non-negative integer.
michael@0:  *    Languages 0 is always "i-default" the language you get without
michael@0:  *    explicit negotiation.  Language 1 is always "en", English
michael@0:  *    which has been explicitly negotiated.  Additional language
michael@0:  *    codes are defined by an application-provided localization plugin.
michael@0:  */
michael@0: typedef PRUint32 PRLanguageCode;
michael@0: #define PR_LANGUAGE_I_DEFAULT 0 /* i-default, the default language */
michael@0: #define PR_LANGUAGE_EN 1 /* English, explicitly negotiated */
michael@0: 
michael@0: /*
michael@0:  * struct PRErrorMessage --
michael@0:  *
michael@0:  *    An error message in an error table.
michael@0:  */
michael@0: struct PRErrorMessage {
michael@0:     const char * name;    /* Macro name for error */
michael@0:     const char * en_text; /* Default English text */
michael@0: };
michael@0: 
michael@0: /*
michael@0:  * struct PRErrorTable --
michael@0:  *
michael@0:  *    An error table, provided by a library.
michael@0:  */
michael@0: struct PRErrorTable {
michael@0:     const struct PRErrorMessage * msgs; /* Array of error information */
michael@0:     const char *name; /* Name of error table source */
michael@0:     PRErrorCode base; /* Error code for first error in table */
michael@0:     int n_msgs; /* Number of codes in table */
michael@0: };
michael@0: 
michael@0: /*
michael@0:  * struct PRErrorCallbackPrivate --
michael@0:  *
michael@0:  *    A private structure for the localization plugin 
michael@0:  */
michael@0: struct PRErrorCallbackPrivate;
michael@0: 
michael@0: /*
michael@0:  * struct PRErrorCallbackTablePrivate --
michael@0:  *
michael@0:  *    A data structure under which the localization plugin may store information,
michael@0:  *    associated with an error table, that is private to itself.
michael@0:  */
michael@0: struct PRErrorCallbackTablePrivate;
michael@0: 
michael@0: /*
michael@0:  * PRErrorCallbackLookupFn --
michael@0:  *
michael@0:  *    A function of PRErrorCallbackLookupFn type is a localization
michael@0:  *    plugin callback which converts an error code into a description
michael@0:  *    in the requested language.  The callback is provided the
michael@0:  *    appropriate error table, private data for the plugin and the table.
michael@0:  *    The callback returns the appropriate UTF-8 encoded description, or NULL
michael@0:  *    if no description can be found.
michael@0:  */
michael@0: typedef const char *
michael@0: PRErrorCallbackLookupFn(PRErrorCode code, PRLanguageCode language, 
michael@0: 		   const struct PRErrorTable *table,
michael@0: 		   struct PRErrorCallbackPrivate *cb_private,
michael@0: 		   struct PRErrorCallbackTablePrivate *table_private);
michael@0: 
michael@0: /*
michael@0:  * PRErrorCallbackNewTableFn --
michael@0:  *
michael@0:  *    A function PRErrorCallbackNewTableFn type is a localization plugin
michael@0:  *    callback which is called once with each error table registered
michael@0:  *    with NSPR.  The callback is provided with the error table and
michael@0:  *    the plugin's private structure.  The callback returns any table private
michael@0:  *    data it wishes to associate with the error table.  Does not need to be thread
michael@0:  *    safe.
michael@0:  */
michael@0: typedef struct PRErrorCallbackTablePrivate *
michael@0: PRErrorCallbackNewTableFn(const struct PRErrorTable *table,
michael@0: 			struct PRErrorCallbackPrivate *cb_private);
michael@0: 
michael@0: /**********************************************************************/
michael@0: /****************************** FUNCTIONS *****************************/
michael@0: /**********************************************************************/
michael@0: 
michael@0: /***********************************************************************
michael@0: ** FUNCTION:    PR_ErrorToString
michael@0: ** DESCRIPTION:
michael@0: **  Returns the UTF-8 message for an error code in
michael@0: **  the requested language.  May return the message
michael@0: **  in the default language if a translation in the requested
michael@0: **  language is not available.  The returned string is
michael@0: **  valid for the duration of the process.  Never returns NULL.
michael@0: **
michael@0: ***********************************************************************/
michael@0: NSPR_API(const char *) PR_ErrorToString(PRErrorCode code,
michael@0:     PRLanguageCode language);
michael@0: 
michael@0: 
michael@0: /***********************************************************************
michael@0: ** FUNCTION:    PR_ErrorToName
michael@0: ** DESCRIPTION:
michael@0: **  Returns the macro name for an error code, or NULL
michael@0: **  if the error code is not known.  The returned string is
michael@0: **  valid for the duration of the process.
michael@0: **
michael@0: **  Does not work for error table 0, the system error codes.
michael@0: **
michael@0: ***********************************************************************/
michael@0: NSPR_API(const char *) PR_ErrorToName(PRErrorCode code);
michael@0: 
michael@0: 
michael@0: /***********************************************************************
michael@0: ** FUNCTION:    PR_ErrorLanguages
michael@0: ** DESCRIPTION:
michael@0: **  Returns the RFC 1766 language tags for the language
michael@0: **  codes PR_ErrorToString() supports.  The returned array is valid
michael@0: **  for the duration of the process.  Never returns NULL.  The first
michael@0: **  item in the returned array is the language tag for PRLanguageCode 0,
michael@0: **  the second is for PRLanguageCode 1, and so on.  The array is terminated
michael@0: **  with a null pointer.
michael@0: **
michael@0: ***********************************************************************/
michael@0: NSPR_API(const char * const *) PR_ErrorLanguages(void);
michael@0: 
michael@0: 
michael@0: /***********************************************************************
michael@0: ** FUNCTION:    PR_ErrorInstallTable
michael@0: ** DESCRIPTION:
michael@0: **  Registers an error table with NSPR.  Must be done exactly once per
michael@0: **  table.  Memory pointed to by `table' must remain valid for the life
michael@0: **  of the process.
michael@0: **
michael@0: **  NOT THREAD SAFE!
michael@0: **  
michael@0: ***********************************************************************/
michael@0: NSPR_API(PRErrorCode) PR_ErrorInstallTable(const struct PRErrorTable *table);
michael@0: 
michael@0: 
michael@0: /***********************************************************************
michael@0: ** FUNCTION:    PR_ErrorInstallCallback
michael@0: ** DESCRIPTION:
michael@0: **  Registers an error localization plugin with NSPR.  May be called
michael@0: **  at most one time.  `languages' contains the language codes supported
michael@0: **  by this plugin.  Languages 0 and 1 must be "i-default" and "en"
michael@0: **  respectively.  `lookup' and `newtable' contain pointers to
michael@0: **  the plugin callback functions.  `cb_private' contains any information
michael@0: **  private to the plugin functions.
michael@0: **
michael@0: **  NOT THREAD SAFE!
michael@0: **
michael@0: ***********************************************************************/
michael@0: NSPR_API(void) PR_ErrorInstallCallback(const char * const * languages,
michael@0: 			      PRErrorCallbackLookupFn *lookup, 
michael@0: 			      PRErrorCallbackNewTableFn *newtable,
michael@0: 			      struct PRErrorCallbackPrivate *cb_private);
michael@0: 
michael@0: PR_END_EXTERN_C
michael@0: 
michael@0: #endif /* prerror_h___ */