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