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

source code of include/unicode/ucnv_err.h