/gecko_api/include/prerror.h

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