![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prerror.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / javascript / include / mozilla / nspr|
Return to prerror.h CVS log | Up to [Synchronet] / sbbs / javascript / include / mozilla / nspr |
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.