The Tor Browser / file comparison

comparison: intl/icu/source/common/unicode/ucnv_err.h

intl/icu/source/common/unicode/ucnv_err.h

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:df368e82c481
1 /*
2 **********************************************************************
3 * Copyright (C) 1999-2009, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 **********************************************************************
6 *
7 *
8 * ucnv_err.h:
9 */
10
11 /**
12 * \file
13 * \brief C UConverter predefined error callbacks
14 *
15 * <h2>Error Behaviour Functions</h2>
16 * Defines some error behaviour functions called by ucnv_{from,to}Unicode
17 * These are provided as part of ICU and many are stable, but they
18 * can also be considered only as an example of what can be done with
19 * callbacks. You may of course write your own.
20 *
21 * If you want to write your own, you may also find the functions from
22 * ucnv_cb.h useful when writing your own callbacks.
23 *
24 * These functions, although public, should NEVER be called directly.
25 * They should be used as parameters to the ucnv_setFromUCallback
26 * and ucnv_setToUCallback functions, to set the behaviour of a converter
27 * when it encounters ILLEGAL/UNMAPPED/INVALID sequences.
28 *
29 * usage example: 'STOP' doesn't need any context, but newContext
30 * could be set to something other than 'NULL' if needed. The available
31 * contexts in this header can modify the default behavior of the callback.
32 *
33 * \code
34 * UErrorCode err = U_ZERO_ERROR;
35 * UConverter *myConverter = ucnv_open("ibm-949", &err);
36 * const void *oldContext;
37 * UConverterFromUCallback oldAction;
38 *
39 *
40 * if (U_SUCCESS(err))
41 * {
42 * ucnv_setFromUCallBack(myConverter,
43 * UCNV_FROM_U_CALLBACK_STOP,
44 * NULL,
45 * &oldAction,
46 * &oldContext,
47 * &status);
48 * }
49 * \endcode
50 *
51 * The code above tells "myConverter" to stop when it encounters an
52 * ILLEGAL/TRUNCATED/INVALID sequences when it is used to convert from
53 * Unicode -> Codepage. The behavior from Codepage to Unicode is not changed,
54 * and ucnv_setToUCallBack would need to be called in order to change
55 * that behavior too.
56 *
57 * Here is an example with a context:
58 *
59 * \code
60 * UErrorCode err = U_ZERO_ERROR;
61 * UConverter *myConverter = ucnv_open("ibm-949", &err);
62 * const void *oldContext;
63 * UConverterFromUCallback oldAction;
64 *
65 *
66 * if (U_SUCCESS(err))
67 * {
68 * ucnv_setToUCallBack(myConverter,
69 * UCNV_TO_U_CALLBACK_SUBSTITUTE,
70 * UCNV_SUB_STOP_ON_ILLEGAL,
71 * &oldAction,
72 * &oldContext,
73 * &status);
74 * }
75 * \endcode
76 *
77 * The code above tells "myConverter" to stop when it encounters an
78 * ILLEGAL/TRUNCATED/INVALID sequences when it is used to convert from
79 * Codepage -> Unicode. Any unmapped and legal characters will be
80 * substituted to be the default substitution character.
81 */
82
83 #ifndef UCNV_ERR_H
84 #define UCNV_ERR_H
85
86 #include "unicode/utypes.h"
87
88 #if !UCONFIG_NO_CONVERSION
89
90 /** Forward declaring the UConverter structure. @stable ICU 2.0 */
91 struct UConverter;
92
93 /** @stable ICU 2.0 */
94 typedef struct UConverter UConverter;
95
96 /**
97 * FROM_U, TO_U context options for sub callback
98 * @stable ICU 2.0
99 */
100 #define UCNV_SUB_STOP_ON_ILLEGAL "i"
101
102 /**
103 * FROM_U, TO_U context options for skip callback
104 * @stable ICU 2.0
105 */
106 #define UCNV_SKIP_STOP_ON_ILLEGAL "i"
107
108 /**
109 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to ICU (%UXXXX)
110 * @stable ICU 2.0
111 */
112 #define UCNV_ESCAPE_ICU NULL
113 /**
114 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to JAVA (\\uXXXX)
115 * @stable ICU 2.0
116 */
117 #define UCNV_ESCAPE_JAVA "J"
118 /**
119 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to C (\\uXXXX \\UXXXXXXXX)
120 * TO_U_CALLBACK_ESCAPE option to escape the character value accoding to C (\\xXXXX)
121 * @stable ICU 2.0
122 */
123 #define UCNV_ESCAPE_C "C"
124 /**
125 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to XML Decimal escape \htmlonly(&amp;#DDDD;)\endhtmlonly
126 * TO_U_CALLBACK_ESCAPE context option to escape the character value accoding to XML Decimal escape \htmlonly(&amp;#DDDD;)\endhtmlonly
127 * @stable ICU 2.0
128 */
129 #define UCNV_ESCAPE_XML_DEC "D"
130 /**
131 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to XML Hex escape \htmlonly(&amp;#xXXXX;)\endhtmlonly
132 * TO_U_CALLBACK_ESCAPE context option to escape the character value accoding to XML Hex escape \htmlonly(&amp;#xXXXX;)\endhtmlonly
133 * @stable ICU 2.0
134 */
135 #define UCNV_ESCAPE_XML_HEX "X"
136 /**
137 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to Unicode (U+XXXXX)
138 * @stable ICU 2.0
139 */
140 #define UCNV_ESCAPE_UNICODE "U"
141
142 /**
143 * FROM_U_CALLBACK_ESCAPE context option to escape the code unit according to CSS2 conventions (\\HH..H<space>, that is,
144 * a backslash, 1..6 hex digits, and a space)
145 * @stable ICU 4.0
146 */
147 #define UCNV_ESCAPE_CSS2 "S"
148
149 /**
150 * The process condition code to be used with the callbacks.
151 * Codes which are greater than UCNV_IRREGULAR should be
152 * passed on to any chained callbacks.
153 * @stable ICU 2.0
154 */
155 typedef enum {
156 UCNV_UNASSIGNED = 0, /**< The code point is unassigned.
157 The error code U_INVALID_CHAR_FOUND will be set. */
158 UCNV_ILLEGAL = 1, /**< The code point is illegal. For example,
159 \\x81\\x2E is illegal in SJIS because \\x2E
160 is not a valid trail byte for the \\x81
161 lead byte.
162 Also, starting with Unicode 3.0.1, non-shortest byte sequences
163 in UTF-8 (like \\xC1\\xA1 instead of \\x61 for U+0061)
164 are also illegal, not just irregular.
165 The error code U_ILLEGAL_CHAR_FOUND will be set. */
166 UCNV_IRREGULAR = 2, /**< The codepoint is not a regular sequence in
167 the encoding. For example, \\xED\\xA0\\x80..\\xED\\xBF\\xBF
168 are irregular UTF-8 byte sequences for single surrogate
169 code points.
170 The error code U_INVALID_CHAR_FOUND will be set. */
171 UCNV_RESET = 3, /**< The callback is called with this reason when a
172 'reset' has occured. Callback should reset all
173 state. */
174 UCNV_CLOSE = 4, /**< Called when the converter is closed. The
175 callback should release any allocated memory.*/
176 UCNV_CLONE = 5 /**< Called when ucnv_safeClone() is called on the
177 converter. the pointer available as the
178 'context' is an alias to the original converters'
179 context pointer. If the context must be owned
180 by the new converter, the callback must clone
181 the data and call ucnv_setFromUCallback
182 (or setToUCallback) with the correct pointer.
183 @stable ICU 2.2
184 */
185 } UConverterCallbackReason;
186
187
188 /**
189 * The structure for the fromUnicode callback function parameter.
190 * @stable ICU 2.0
191 */
192 typedef struct {
193 uint16_t size; /**< The size of this struct. @stable ICU 2.0 */
194 UBool flush; /**< The internal state of converter will be reset and data flushed if set to TRUE. @stable ICU 2.0 */
195 UConverter *converter; /**< Pointer to the converter that is opened and to which this struct is passed as an argument. @stable ICU 2.0 */
196 const UChar *source; /**< Pointer to the source source buffer. @stable ICU 2.0 */
197 const UChar *sourceLimit; /**< Pointer to the limit (end + 1) of source buffer. @stable ICU 2.0 */
198 char *target; /**< Pointer to the target buffer. @stable ICU 2.0 */
199 const char *targetLimit; /**< Pointer to the limit (end + 1) of target buffer. @stable ICU 2.0 */
200 int32_t *offsets; /**< Pointer to the buffer that recieves the offsets. *offset = blah ; offset++;. @stable ICU 2.0 */
201 } UConverterFromUnicodeArgs;
202
203
204 /**
205 * The structure for the toUnicode callback function parameter.
206 * @stable ICU 2.0
207 */
208 typedef struct {
209 uint16_t size; /**< The size of this struct @stable ICU 2.0 */
210 UBool flush; /**< The internal state of converter will be reset and data flushed if set to TRUE. @stable ICU 2.0 */
211 UConverter *converter; /**< Pointer to the converter that is opened and to which this struct is passed as an argument. @stable ICU 2.0 */
212 const char *source; /**< Pointer to the source source buffer. @stable ICU 2.0 */
213 const char *sourceLimit; /**< Pointer to the limit (end + 1) of source buffer. @stable ICU 2.0 */
214 UChar *target; /**< Pointer to the target buffer. @stable ICU 2.0 */
215 const UChar *targetLimit; /**< Pointer to the limit (end + 1) of target buffer. @stable ICU 2.0 */
216 int32_t *offsets; /**< Pointer to the buffer that recieves the offsets. *offset = blah ; offset++;. @stable ICU 2.0 */
217 } UConverterToUnicodeArgs;
218
219
220 /**
221 * DO NOT CALL THIS FUNCTION DIRECTLY!
222 * This From Unicode callback STOPS at the ILLEGAL_SEQUENCE,
223 * returning the error code back to the caller immediately.
224 *
225 * @param context Pointer to the callback's private data
226 * @param fromUArgs Information about the conversion in progress
227 * @param codeUnits Points to 'length' UChars of the concerned Unicode sequence
228 * @param length Size (in bytes) of the concerned codepage sequence
229 * @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint.
230 * @param reason Defines the reason the callback was invoked
231 * @param err This should always be set to a failure status prior to calling.
232 * @stable ICU 2.0
233 */
234 U_STABLE void U_EXPORT2 UCNV_FROM_U_CALLBACK_STOP (
235 const void *context,
236 UConverterFromUnicodeArgs *fromUArgs,
237 const UChar* codeUnits,
238 int32_t length,
239 UChar32 codePoint,
240 UConverterCallbackReason reason,
241 UErrorCode * err);
242
243
244
245 /**
246 * DO NOT CALL THIS FUNCTION DIRECTLY!
247 * This To Unicode callback STOPS at the ILLEGAL_SEQUENCE,
248 * returning the error code back to the caller immediately.
249 *
250 * @param context Pointer to the callback's private data
251 * @param toUArgs Information about the conversion in progress
252 * @param codeUnits Points to 'length' bytes of the concerned codepage sequence
253 * @param length Size (in bytes) of the concerned codepage sequence
254 * @param reason Defines the reason the callback was invoked
255 * @param err This should always be set to a failure status prior to calling.
256 * @stable ICU 2.0
257 */
258 U_STABLE void U_EXPORT2 UCNV_TO_U_CALLBACK_STOP (
259 const void *context,
260 UConverterToUnicodeArgs *toUArgs,
261 const char* codeUnits,
262 int32_t length,
263 UConverterCallbackReason reason,
264 UErrorCode * err);
265
266 /**
267 * DO NOT CALL THIS FUNCTION DIRECTLY!
268 * This From Unicode callback skips any ILLEGAL_SEQUENCE, or
269 * skips only UNASSINGED_SEQUENCE depending on the context parameter
270 * simply ignoring those characters.
271 *
272 * @param context The function currently recognizes the callback options:
273 * UCNV_SKIP_STOP_ON_ILLEGAL: STOPS at the ILLEGAL_SEQUENCE,
274 * returning the error code back to the caller immediately.
275 * NULL: Skips any ILLEGAL_SEQUENCE
276 * @param fromUArgs Information about the conversion in progress
277 * @param codeUnits Points to 'length' UChars of the concerned Unicode sequence
278 * @param length Size (in bytes) of the concerned codepage sequence
279 * @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint.
280 * @param reason Defines the reason the callback was invoked
281 * @param err Return value will be set to success if the callback was handled,
282 * otherwise this value will be set to a failure status.
283 * @stable ICU 2.0
284 */
285 U_STABLE void U_EXPORT2 UCNV_FROM_U_CALLBACK_SKIP (
286 const void *context,
287 UConverterFromUnicodeArgs *fromUArgs,
288 const UChar* codeUnits,
289 int32_t length,
290 UChar32 codePoint,
291 UConverterCallbackReason reason,
292 UErrorCode * err);
293
294 /**
295 * DO NOT CALL THIS FUNCTION DIRECTLY!
296 * This From Unicode callback will Substitute the ILLEGAL SEQUENCE, or
297 * UNASSIGNED_SEQUENCE depending on context parameter, with the
298 * current substitution string for the converter. This is the default
299 * callback.
300 *
301 * @param context The function currently recognizes the callback options:
302 * UCNV_SUB_STOP_ON_ILLEGAL: STOPS at the ILLEGAL_SEQUENCE,
303 * returning the error code back to the caller immediately.
304 * NULL: Substitutes any ILLEGAL_SEQUENCE
305 * @param fromUArgs Information about the conversion in progress
306 * @param codeUnits Points to 'length' UChars of the concerned Unicode sequence
307 * @param length Size (in bytes) of the concerned codepage sequence
308 * @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint.
309 * @param reason Defines the reason the callback was invoked
310 * @param err Return value will be set to success if the callback was handled,
311 * otherwise this value will be set to a failure status.
312 * @see ucnv_setSubstChars
313 * @stable ICU 2.0
314 */
315 U_STABLE void U_EXPORT2 UCNV_FROM_U_CALLBACK_SUBSTITUTE (
316 const void *context,
317 UConverterFromUnicodeArgs *fromUArgs,
318 const UChar* codeUnits,
319 int32_t length,
320 UChar32 codePoint,
321 UConverterCallbackReason reason,
322 UErrorCode * err);
323
324 /**
325 * DO NOT CALL THIS FUNCTION DIRECTLY!
326 * This From Unicode callback will Substitute the ILLEGAL SEQUENCE with the
327 * hexadecimal representation of the illegal codepoints
328 *
329 * @param context The function currently recognizes the callback options:
330 * <ul>
331 * <li>UCNV_ESCAPE_ICU: Substitues the ILLEGAL SEQUENCE with the hexadecimal
332 * representation in the format %UXXXX, e.g. "%uFFFE%u00AC%uC8FE").
333 * In the Event the converter doesn't support the characters {%,U}[A-F][0-9],
334 * it will substitute the illegal sequence with the substitution characters.
335 * Note that codeUnit(32bit int eg: unit of a surrogate pair) is represented as
336 * %UD84D%UDC56</li>
337 * <li>UCNV_ESCAPE_JAVA: Substitues the ILLEGAL SEQUENCE with the hexadecimal
338 * representation in the format \\uXXXX, e.g. "\\uFFFE\\u00AC\\uC8FE").
339 * In the Event the converter doesn't support the characters {\,u}[A-F][0-9],
340 * it will substitute the illegal sequence with the substitution characters.
341 * Note that codeUnit(32bit int eg: unit of a surrogate pair) is represented as
342 * \\uD84D\\uDC56</li>
343 * <li>UCNV_ESCAPE_C: Substitues the ILLEGAL SEQUENCE with the hexadecimal
344 * representation in the format \\uXXXX, e.g. "\\uFFFE\\u00AC\\uC8FE").
345 * In the Event the converter doesn't support the characters {\,u,U}[A-F][0-9],
346 * it will substitute the illegal sequence with the substitution characters.
347 * Note that codeUnit(32bit int eg: unit of a surrogate pair) is represented as
348 * \\U00023456</li>
349 * <li>UCNV_ESCAPE_XML_DEC: Substitues the ILLEGAL SEQUENCE with the decimal
350 * representation in the format \htmlonly&amp;#DDDDDDDD;, e.g. "&amp;#65534;&amp;#172;&amp;#51454;")\endhtmlonly.
351 * In the Event the converter doesn't support the characters {&amp;,#}[0-9],
352 * it will substitute the illegal sequence with the substitution characters.
353 * Note that codeUnit(32bit int eg: unit of a surrogate pair) is represented as
354 * &amp;#144470; and Zero padding is ignored.</li>
355 * <li>UCNV_ESCAPE_XML_HEX:Substitues the ILLEGAL SEQUENCE with the decimal
356 * representation in the format \htmlonly&amp;#xXXXX; e.g. "&amp;#xFFFE;&amp;#x00AC;&amp;#xC8FE;")\endhtmlonly.
357 * In the Event the converter doesn't support the characters {&,#,x}[0-9],
358 * it will substitute the illegal sequence with the substitution characters.
359 * Note that codeUnit(32bit int eg: unit of a surrogate pair) is represented as
360 * \htmlonly&amp;#x23456;\endhtmlonly</li>
361 * </ul>
362 * @param fromUArgs Information about the conversion in progress
363 * @param codeUnits Points to 'length' UChars of the concerned Unicode sequence
364 * @param length Size (in bytes) of the concerned codepage sequence
365 * @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint.
366 * @param reason Defines the reason the callback was invoked
367 * @param err Return value will be set to success if the callback was handled,
368 * otherwise this value will be set to a failure status.
369 * @stable ICU 2.0
370 */
371 U_STABLE void U_EXPORT2 UCNV_FROM_U_CALLBACK_ESCAPE (
372 const void *context,
373 UConverterFromUnicodeArgs *fromUArgs,
374 const UChar* codeUnits,
375 int32_t length,
376 UChar32 codePoint,
377 UConverterCallbackReason reason,
378 UErrorCode * err);
379
380
381 /**
382 * DO NOT CALL THIS FUNCTION DIRECTLY!
383 * This To Unicode callback skips any ILLEGAL_SEQUENCE, or
384 * skips only UNASSINGED_SEQUENCE depending on the context parameter
385 * simply ignoring those characters.
386 *
387 * @param context The function currently recognizes the callback options:
388 * UCNV_SKIP_STOP_ON_ILLEGAL: STOPS at the ILLEGAL_SEQUENCE,
389 * returning the error code back to the caller immediately.
390 * NULL: Skips any ILLEGAL_SEQUENCE
391 * @param toUArgs Information about the conversion in progress
392 * @param codeUnits Points to 'length' bytes of the concerned codepage sequence
393 * @param length Size (in bytes) of the concerned codepage sequence
394 * @param reason Defines the reason the callback was invoked
395 * @param err Return value will be set to success if the callback was handled,
396 * otherwise this value will be set to a failure status.
397 * @stable ICU 2.0
398 */
399 U_STABLE void U_EXPORT2 UCNV_TO_U_CALLBACK_SKIP (
400 const void *context,
401 UConverterToUnicodeArgs *toUArgs,
402 const char* codeUnits,
403 int32_t length,
404 UConverterCallbackReason reason,
405 UErrorCode * err);
406
407 /**
408 * DO NOT CALL THIS FUNCTION DIRECTLY!
409 * This To Unicode callback will Substitute the ILLEGAL SEQUENCE,or
410 * UNASSIGNED_SEQUENCE depending on context parameter, with the
411 * Unicode substitution character, U+FFFD.
412 *
413 * @param context The function currently recognizes the callback options:
414 * UCNV_SUB_STOP_ON_ILLEGAL: STOPS at the ILLEGAL_SEQUENCE,
415 * returning the error code back to the caller immediately.
416 * NULL: Substitutes any ILLEGAL_SEQUENCE
417 * @param toUArgs Information about the conversion in progress
418 * @param codeUnits Points to 'length' bytes of the concerned codepage sequence
419 * @param length Size (in bytes) of the concerned codepage sequence
420 * @param reason Defines the reason the callback was invoked
421 * @param err Return value will be set to success if the callback was handled,
422 * otherwise this value will be set to a failure status.
423 * @stable ICU 2.0
424 */
425 U_STABLE void U_EXPORT2 UCNV_TO_U_CALLBACK_SUBSTITUTE (
426 const void *context,
427 UConverterToUnicodeArgs *toUArgs,
428 const char* codeUnits,
429 int32_t length,
430 UConverterCallbackReason reason,
431 UErrorCode * err);
432
433 /**
434 * DO NOT CALL THIS FUNCTION DIRECTLY!
435 * This To Unicode callback will Substitute the ILLEGAL SEQUENCE with the
436 * hexadecimal representation of the illegal bytes
437 * (in the format %XNN, e.g. "%XFF%X0A%XC8%X03").
438 *
439 * @param context This function currently recognizes the callback options:
440 * UCNV_ESCAPE_ICU, UCNV_ESCAPE_JAVA, UCNV_ESCAPE_C, UCNV_ESCAPE_XML_DEC,
441 * UCNV_ESCAPE_XML_HEX and UCNV_ESCAPE_UNICODE.
442 * @param toUArgs Information about the conversion in progress
443 * @param codeUnits Points to 'length' bytes of the concerned codepage sequence
444 * @param length Size (in bytes) of the concerned codepage sequence
445 * @param reason Defines the reason the callback was invoked
446 * @param err Return value will be set to success if the callback was handled,
447 * otherwise this value will be set to a failure status.
448 * @stable ICU 2.0
449 */
450
451 U_STABLE void U_EXPORT2 UCNV_TO_U_CALLBACK_ESCAPE (
452 const void *context,
453 UConverterToUnicodeArgs *toUArgs,
454 const char* codeUnits,
455 int32_t length,
456 UConverterCallbackReason reason,
457 UErrorCode * err);
458
459 #endif
460
461 #endif
462
463 /*UCNV_ERR_H*/

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial