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