1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prerror.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,294 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prerror_h___
1.10 +#define prerror_h___
1.11 +
1.12 +#include "prtypes.h"
1.13 +
1.14 +PR_BEGIN_EXTERN_C
1.15 +
1.16 +typedef PRInt32 PRErrorCode;
1.17 +
1.18 +#define PR_NSPR_ERROR_BASE -6000
1.19 +
1.20 +#include "prerr.h"
1.21 +
1.22 +/*
1.23 +** Set error will preserve an error condition within a thread context.
1.24 +** The values stored are the NSPR (platform independent) translation of
1.25 +** the error. Also, if available, the platform specific oserror is stored.
1.26 +** If there is no appropriate OS error number, a zero my be supplied.
1.27 +*/
1.28 +NSPR_API(void) PR_SetError(PRErrorCode errorCode, PRInt32 oserr);
1.29 +
1.30 +/*
1.31 +** The text value specified may be NULL. If it is not NULL and the text length
1.32 +** is zero, the string is assumed to be a null terminated C string. Otherwise
1.33 +** the text is assumed to be the length specified and possibly include NULL
1.34 +** characters (e.g., a multi-national string).
1.35 +**
1.36 +** The text will be copied into to thread structure and remain there
1.37 +** until the next call to PR_SetError.
1.38 +*/
1.39 +NSPR_API(void) PR_SetErrorText(
1.40 + PRIntn textLength, const char *text);
1.41 +
1.42 +/*
1.43 +** Return the current threads last set error code.
1.44 +*/
1.45 +NSPR_API(PRErrorCode) PR_GetError(void);
1.46 +
1.47 +/*
1.48 +** Return the current threads last set os error code. This is used for
1.49 +** machine specific code that desires the underlying os error.
1.50 +*/
1.51 +NSPR_API(PRInt32) PR_GetOSError(void);
1.52 +
1.53 +/*
1.54 +** Get the length of the error text. If a zero is returned, then there
1.55 +** is no text. Otherwise, the value returned is sufficient to contain
1.56 +** the error text currently available.
1.57 +*/
1.58 +NSPR_API(PRInt32) PR_GetErrorTextLength(void);
1.59 +
1.60 +/*
1.61 +** Copy the current threads current error text. Then actual number of bytes
1.62 +** copied is returned as the result. If the result is zero, the 'text' area
1.63 +** is unaffected.
1.64 +*/
1.65 +NSPR_API(PRInt32) PR_GetErrorText(char *text);
1.66 +
1.67 +
1.68 +/*
1.69 +Copyright (C) 1987, 1988 Student Information Processing Board of the
1.70 +Massachusetts Institute of Technology.
1.71 +
1.72 +Permission to use, copy, modify, and distribute this software and its
1.73 +documentation for any purpose and without fee is hereby granted, provided
1.74 +that the above copyright notice appear in all copies and that both that
1.75 +copyright notice and this permission notice appear in supporting
1.76 +documentation, and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
1.77 +used in advertising or publicity pertaining to distribution of the software
1.78 +without specific, written prior permission. M.I.T. and the M.I.T. S.I.P.B.
1.79 +make no representations about the suitability of this software for any
1.80 +purpose. It is provided "as is" without express or implied warranty.
1.81 +*/
1.82 +
1.83 +
1.84 +/*
1.85 + * NOTE:
1.86 + * The interfaces for error-code-translation described in the rest of
1.87 + * this file are preliminary in the 3.1 release of nspr and are subject
1.88 + * to change in future releases.
1.89 + */
1.90 +
1.91 +/*
1.92 +** Description: Localizable error code to string function.
1.93 +**
1.94 +**
1.95 +** NSPR provides a mechanism for converting an error code to a
1.96 +** descriptive string, in a caller-specified language.
1.97 +**
1.98 +** Error codes themselves are 32 bit (signed) integers. Typically,
1.99 +** the high order 24 bits are an identifier of which error table the
1.100 +** error code is from, and the low order 8 bits are a sequential error
1.101 +** number within the table. NSPR supports error tables whose first
1.102 +** error code is not a multiple of 256, such error code assignments
1.103 +** should be avoided when possible.
1.104 +**
1.105 +** Error table 0 is defined to match the UNIX system call error table
1.106 +** (sys_errlist); this allows errno values to be used directly in the
1.107 +** library. Other error table numbers are typically formed by
1.108 +** compacting together the first four characters of the error table
1.109 +** name. The mapping between characters in the name and numeric
1.110 +** values in the error code are defined in a system-independent
1.111 +** fashion, so that two systems that can pass integral values between
1.112 +** them can reliably pass error codes without loss of meaning; this
1.113 +** should work even if the character sets used are not the
1.114 +** same. (However, if this is to be done, error table 0 should be
1.115 +** avoided, since the local system call error tables may differ.)
1.116 +**
1.117 +** Libraries defining error codes need only provide a table mapping
1.118 +** error code numbers to names and default English descriptions,
1.119 +** calling a routine to install the table, making it ``known'' to NSPR
1.120 +** library. Once installed, a table may not be removed. Any error
1.121 +** code the library generates can be converted to the corresponding
1.122 +** error message. There is also a default format for error codes
1.123 +** accidentally returned before making the table known, which is of
1.124 +** the form "unknown code foo 32", where "foo" would be the name of
1.125 +** the table.
1.126 +**
1.127 +** Normally, the error code conversion routine only supports the
1.128 +** languages "i-default" and "en", returning the error-table-provided
1.129 +** English description for both languages. The application may
1.130 +** provide a localization plugin, allowing support for additional
1.131 +** languages.
1.132 +**
1.133 +**/
1.134 +
1.135 +/**********************************************************************/
1.136 +/************************* TYPES AND CONSTANTS ************************/
1.137 +/**********************************************************************/
1.138 +
1.139 +/*
1.140 + * PRLanguageCode --
1.141 + *
1.142 + * NSPR represents a language code as a non-negative integer.
1.143 + * Languages 0 is always "i-default" the language you get without
1.144 + * explicit negotiation. Language 1 is always "en", English
1.145 + * which has been explicitly negotiated. Additional language
1.146 + * codes are defined by an application-provided localization plugin.
1.147 + */
1.148 +typedef PRUint32 PRLanguageCode;
1.149 +#define PR_LANGUAGE_I_DEFAULT 0 /* i-default, the default language */
1.150 +#define PR_LANGUAGE_EN 1 /* English, explicitly negotiated */
1.151 +
1.152 +/*
1.153 + * struct PRErrorMessage --
1.154 + *
1.155 + * An error message in an error table.
1.156 + */
1.157 +struct PRErrorMessage {
1.158 + const char * name; /* Macro name for error */
1.159 + const char * en_text; /* Default English text */
1.160 +};
1.161 +
1.162 +/*
1.163 + * struct PRErrorTable --
1.164 + *
1.165 + * An error table, provided by a library.
1.166 + */
1.167 +struct PRErrorTable {
1.168 + const struct PRErrorMessage * msgs; /* Array of error information */
1.169 + const char *name; /* Name of error table source */
1.170 + PRErrorCode base; /* Error code for first error in table */
1.171 + int n_msgs; /* Number of codes in table */
1.172 +};
1.173 +
1.174 +/*
1.175 + * struct PRErrorCallbackPrivate --
1.176 + *
1.177 + * A private structure for the localization plugin
1.178 + */
1.179 +struct PRErrorCallbackPrivate;
1.180 +
1.181 +/*
1.182 + * struct PRErrorCallbackTablePrivate --
1.183 + *
1.184 + * A data structure under which the localization plugin may store information,
1.185 + * associated with an error table, that is private to itself.
1.186 + */
1.187 +struct PRErrorCallbackTablePrivate;
1.188 +
1.189 +/*
1.190 + * PRErrorCallbackLookupFn --
1.191 + *
1.192 + * A function of PRErrorCallbackLookupFn type is a localization
1.193 + * plugin callback which converts an error code into a description
1.194 + * in the requested language. The callback is provided the
1.195 + * appropriate error table, private data for the plugin and the table.
1.196 + * The callback returns the appropriate UTF-8 encoded description, or NULL
1.197 + * if no description can be found.
1.198 + */
1.199 +typedef const char *
1.200 +PRErrorCallbackLookupFn(PRErrorCode code, PRLanguageCode language,
1.201 + const struct PRErrorTable *table,
1.202 + struct PRErrorCallbackPrivate *cb_private,
1.203 + struct PRErrorCallbackTablePrivate *table_private);
1.204 +
1.205 +/*
1.206 + * PRErrorCallbackNewTableFn --
1.207 + *
1.208 + * A function PRErrorCallbackNewTableFn type is a localization plugin
1.209 + * callback which is called once with each error table registered
1.210 + * with NSPR. The callback is provided with the error table and
1.211 + * the plugin's private structure. The callback returns any table private
1.212 + * data it wishes to associate with the error table. Does not need to be thread
1.213 + * safe.
1.214 + */
1.215 +typedef struct PRErrorCallbackTablePrivate *
1.216 +PRErrorCallbackNewTableFn(const struct PRErrorTable *table,
1.217 + struct PRErrorCallbackPrivate *cb_private);
1.218 +
1.219 +/**********************************************************************/
1.220 +/****************************** FUNCTIONS *****************************/
1.221 +/**********************************************************************/
1.222 +
1.223 +/***********************************************************************
1.224 +** FUNCTION: PR_ErrorToString
1.225 +** DESCRIPTION:
1.226 +** Returns the UTF-8 message for an error code in
1.227 +** the requested language. May return the message
1.228 +** in the default language if a translation in the requested
1.229 +** language is not available. The returned string is
1.230 +** valid for the duration of the process. Never returns NULL.
1.231 +**
1.232 +***********************************************************************/
1.233 +NSPR_API(const char *) PR_ErrorToString(PRErrorCode code,
1.234 + PRLanguageCode language);
1.235 +
1.236 +
1.237 +/***********************************************************************
1.238 +** FUNCTION: PR_ErrorToName
1.239 +** DESCRIPTION:
1.240 +** Returns the macro name for an error code, or NULL
1.241 +** if the error code is not known. The returned string is
1.242 +** valid for the duration of the process.
1.243 +**
1.244 +** Does not work for error table 0, the system error codes.
1.245 +**
1.246 +***********************************************************************/
1.247 +NSPR_API(const char *) PR_ErrorToName(PRErrorCode code);
1.248 +
1.249 +
1.250 +/***********************************************************************
1.251 +** FUNCTION: PR_ErrorLanguages
1.252 +** DESCRIPTION:
1.253 +** Returns the RFC 1766 language tags for the language
1.254 +** codes PR_ErrorToString() supports. The returned array is valid
1.255 +** for the duration of the process. Never returns NULL. The first
1.256 +** item in the returned array is the language tag for PRLanguageCode 0,
1.257 +** the second is for PRLanguageCode 1, and so on. The array is terminated
1.258 +** with a null pointer.
1.259 +**
1.260 +***********************************************************************/
1.261 +NSPR_API(const char * const *) PR_ErrorLanguages(void);
1.262 +
1.263 +
1.264 +/***********************************************************************
1.265 +** FUNCTION: PR_ErrorInstallTable
1.266 +** DESCRIPTION:
1.267 +** Registers an error table with NSPR. Must be done exactly once per
1.268 +** table. Memory pointed to by `table' must remain valid for the life
1.269 +** of the process.
1.270 +**
1.271 +** NOT THREAD SAFE!
1.272 +**
1.273 +***********************************************************************/
1.274 +NSPR_API(PRErrorCode) PR_ErrorInstallTable(const struct PRErrorTable *table);
1.275 +
1.276 +
1.277 +/***********************************************************************
1.278 +** FUNCTION: PR_ErrorInstallCallback
1.279 +** DESCRIPTION:
1.280 +** Registers an error localization plugin with NSPR. May be called
1.281 +** at most one time. `languages' contains the language codes supported
1.282 +** by this plugin. Languages 0 and 1 must be "i-default" and "en"
1.283 +** respectively. `lookup' and `newtable' contain pointers to
1.284 +** the plugin callback functions. `cb_private' contains any information
1.285 +** private to the plugin functions.
1.286 +**
1.287 +** NOT THREAD SAFE!
1.288 +**
1.289 +***********************************************************************/
1.290 +NSPR_API(void) PR_ErrorInstallCallback(const char * const * languages,
1.291 + PRErrorCallbackLookupFn *lookup,
1.292 + PRErrorCallbackNewTableFn *newtable,
1.293 + struct PRErrorCallbackPrivate *cb_private);
1.294 +
1.295 +PR_END_EXTERN_C
1.296 +
1.297 +#endif /* prerror_h___ */
