]>
Commit | Line | Data |
---|---|---|
b75a7d8f A |
1 | /* |
2 | ********************************************************************** | |
46f4442e | 3 | * Copyright (C) 1999-2007, International Business Machines |
b75a7d8f A |
4 | * Corporation and others. All Rights Reserved. |
5 | ********************************************************************** | |
6 | * | |
46f4442e A |
7 | * ucnv_cnv.h: |
8 | * Definitions for converter implementations. | |
b75a7d8f A |
9 | * |
10 | * Modification History: | |
11 | * | |
12 | * Date Name Description | |
13 | * 05/09/00 helena Added implementation to handle fallback mappings. | |
14 | * 06/29/2000 helena Major rewrite of the callback APIs. | |
15 | */ | |
16 | ||
17 | #ifndef UCNV_CNV_H | |
18 | #define UCNV_CNV_H | |
19 | ||
20 | #include "unicode/utypes.h" | |
b75a7d8f | 21 | |
374ca955 | 22 | #if !UCONFIG_NO_CONVERSION |
b75a7d8f | 23 | |
374ca955 A |
24 | #include "unicode/ucnv.h" |
25 | #include "unicode/ucnv_err.h" | |
26 | #include "unicode/uset.h" | |
27 | #include "uset_imp.h" | |
b75a7d8f A |
28 | |
29 | U_CDECL_BEGIN | |
30 | ||
31 | /* this is used in fromUnicode DBCS tables as an "unassigned" marker */ | |
32 | #define missingCharMarker 0xFFFF | |
33 | ||
34 | /* | |
35 | * #define missingUCharMarker 0xfffe | |
36 | * | |
374ca955 | 37 | * commented out because there are actually two values used in toUnicode tables: |
b75a7d8f A |
38 | * U+fffe "unassigned" |
39 | * U+ffff "illegal" | |
40 | */ | |
41 | ||
374ca955 A |
42 | /** Forward declaration, see ucnv_bld.h */ |
43 | struct UConverterSharedData; | |
44 | typedef struct UConverterSharedData UConverterSharedData; | |
45 | ||
46 | /* function types for UConverterImpl ---------------------------------------- */ | |
b75a7d8f | 47 | |
374ca955 A |
48 | /* struct with arguments for UConverterLoad and ucnv_load() */ |
49 | typedef struct { | |
50 | int32_t size; /* sizeof(UConverterLoadArgs) */ | |
51 | int32_t nestedLoads; /* count nested ucnv_load() calls */ | |
52 | int32_t reserved; /* reserved - for good alignment of the pointers */ | |
53 | uint32_t options; | |
54 | const char *pkg, *name; | |
55 | } UConverterLoadArgs; | |
b75a7d8f | 56 | |
374ca955 A |
57 | typedef void (*UConverterLoad) (UConverterSharedData *sharedData, |
58 | UConverterLoadArgs *pArgs, | |
59 | const uint8_t *raw, UErrorCode *pErrorCode); | |
b75a7d8f A |
60 | typedef void (*UConverterUnload) (UConverterSharedData *sharedData); |
61 | ||
62 | typedef void (*UConverterOpen) (UConverter *cnv, const char *name, const char *locale,uint32_t options, UErrorCode *pErrorCode); | |
63 | typedef void (*UConverterClose) (UConverter *cnv); | |
64 | ||
65 | typedef enum UConverterResetChoice { | |
66 | UCNV_RESET_BOTH, | |
67 | UCNV_RESET_TO_UNICODE, | |
68 | UCNV_RESET_FROM_UNICODE | |
69 | } UConverterResetChoice; | |
70 | ||
71 | typedef void (*UConverterReset) (UConverter *cnv, UConverterResetChoice choice); | |
72 | ||
374ca955 A |
73 | /* |
74 | * Converter implementation function(s) for ucnv_toUnicode(). | |
75 | * If the toUnicodeWithOffsets function pointer is NULL, | |
76 | * then the toUnicode function will be used and the offsets will be set to -1. | |
77 | * | |
78 | * Must maintain state across buffers. Use toUBytes[toULength] for partial input | |
79 | * sequences; it will be checked in ucnv.c at the end of the input stream | |
80 | * to detect truncated input. | |
81 | * Some converters may need additional detection and may then set U_TRUNCATED_CHAR_FOUND. | |
82 | * | |
83 | * The toUnicodeWithOffsets must write exactly as many offset values as target | |
84 | * units. Write offset values of -1 for when the source index corresponding to | |
85 | * the output unit is not known (e.g., the character started in an earlier buffer). | |
86 | * The pArgs->offsets pointer need not be moved forward. | |
87 | * | |
88 | * At function return, either one of the following conditions must be true: | |
89 | * - U_BUFFER_OVERFLOW_ERROR and the target is full: target==targetLimit | |
90 | * - another error code with toUBytes[toULength] set to the offending input | |
91 | * - no error, and the source is consumed: source==sourceLimit | |
92 | * | |
93 | * The ucnv.c code will handle the end of the input (reset) | |
94 | * (reset, and truncation detection) and callbacks. | |
95 | */ | |
96 | typedef void (*UConverterToUnicode) (UConverterToUnicodeArgs *, UErrorCode *); | |
b75a7d8f | 97 | |
374ca955 A |
98 | /* |
99 | * Same rules as for UConverterToUnicode. | |
100 | * A lead surrogate is kept in fromUChar32 across buffers, and if an error | |
101 | * occurs, then the offending input code point must be put into fromUChar32 | |
102 | * as well. | |
103 | */ | |
104 | typedef void (*UConverterFromUnicode) (UConverterFromUnicodeArgs *, UErrorCode *); | |
b75a7d8f | 105 | |
46f4442e A |
106 | /* |
107 | * Converter implementation function for ucnv_convertEx(), for direct conversion | |
108 | * between two charsets without pivoting through UTF-16. | |
109 | * The rules are the same as for UConverterToUnicode and UConverterFromUnicode. | |
110 | * In addition, | |
111 | * - The toUnicode side must behave and keep state exactly like the | |
112 | * UConverterToUnicode implementation for the same source charset. | |
113 | * - A U_USING_DEFAULT_WARNING can be set to request to temporarily fall back | |
114 | * to pivoting. When this function is called, the conversion framework makes | |
115 | * sure that this warning is not set on input. | |
116 | * - Continuing a partial match and flushing the toUnicode replay buffer | |
117 | * are handled by pivoting, using the toUnicode and fromUnicode functions. | |
118 | */ | |
119 | typedef void (*UConverterConvert) (UConverterFromUnicodeArgs *pFromUArgs, | |
120 | UConverterToUnicodeArgs *pToUArgs, | |
121 | UErrorCode *pErrorCode); | |
122 | ||
374ca955 A |
123 | /* |
124 | * Converter implementation function for ucnv_getNextUChar(). | |
125 | * If the function pointer is NULL, then the toUnicode function will be used. | |
126 | * | |
127 | * Will be called at a character boundary (toULength==0). | |
128 | * May return with | |
129 | * - U_INDEX_OUTOFBOUNDS_ERROR if there was no output for the input | |
130 | * (the return value will be ignored) | |
131 | * - U_TRUNCATED_CHAR_FOUND or another error code (never U_BUFFER_OVERFLOW_ERROR!) | |
132 | * with toUBytes[toULength] set to the offending input | |
133 | * (the return value will be ignored) | |
134 | * - return UCNV_GET_NEXT_UCHAR_USE_TO_U, without moving the source pointer, | |
135 | * to indicate that the ucnv.c code shall call the toUnicode function instead | |
136 | * - return a real code point result | |
137 | * | |
138 | * Unless UCNV_GET_NEXT_UCHAR_USE_TO_U is returned, the source bytes must be consumed. | |
139 | * | |
140 | * The ucnv.c code will handle the end of the input (reset) | |
141 | * (except for truncation detection!) and callbacks. | |
142 | */ | |
143 | typedef UChar32 (*UConverterGetNextUChar) (UConverterToUnicodeArgs *, UErrorCode *); | |
b75a7d8f A |
144 | |
145 | typedef void (*UConverterGetStarters)(const UConverter* converter, | |
146 | UBool starters[256], | |
147 | UErrorCode *pErrorCode); | |
148 | ||
149 | /* If this function pointer is null or if the function returns null | |
150 | * the name field in static data struct should be returned by | |
151 | * ucnv_getName() API function | |
152 | */ | |
153 | typedef const char * (*UConverterGetName) (const UConverter *cnv); | |
154 | ||
155 | /** | |
156 | * Write the codepage substitution character. | |
157 | * If this function is not set, then ucnv_cbFromUWriteSub() writes | |
158 | * the substitution character from UConverter. | |
159 | * For stateful converters, it is typically necessary to handle this | |
160 | * specificially for the converter in order to properly maintain the state. | |
161 | */ | |
162 | typedef void (*UConverterWriteSub) (UConverterFromUnicodeArgs *pArgs, int32_t offsetIndex, UErrorCode *pErrorCode); | |
163 | ||
164 | /** | |
165 | * For converter-specific safeClone processing | |
166 | * If this function is not set, then ucnv_safeClone assumes that the converter has no private data that changes | |
167 | * after the converter is done opening. | |
168 | * If this function is set, then it is called just after a memcpy() of | |
169 | * converter data to the new, empty converter, and is expected to set up | |
170 | * the initial state of the converter. It is not expected to increment the | |
171 | * reference counts of the standard data types such as the shared data. | |
172 | */ | |
173 | typedef UConverter * (*UConverterSafeClone) (const UConverter *cnv, | |
174 | void *stackBuffer, | |
175 | int32_t *pBufferSize, | |
176 | UErrorCode *status); | |
177 | ||
46f4442e A |
178 | /** |
179 | * Filters for some ucnv_getUnicodeSet() implementation code. | |
180 | */ | |
181 | typedef enum UConverterSetFilter { | |
182 | UCNV_SET_FILTER_NONE, | |
183 | UCNV_SET_FILTER_DBCS_ONLY, | |
184 | UCNV_SET_FILTER_2022_CN, | |
185 | UCNV_SET_FILTER_SJIS, | |
186 | UCNV_SET_FILTER_GR94DBCS, | |
187 | UCNV_SET_FILTER_HZ, | |
188 | UCNV_SET_FILTER_COUNT | |
189 | } UConverterSetFilter; | |
190 | ||
b75a7d8f A |
191 | /** |
192 | * Fills the set of Unicode code points that can be converted by an ICU converter. | |
193 | * The API function ucnv_getUnicodeSet() clears the USet before calling | |
194 | * the converter's getUnicodeSet() implementation; the converter should only | |
195 | * add the appropriate code points to allow recursive use. | |
196 | * For example, the ISO-2022-JP converter will call each subconverter's | |
197 | * getUnicodeSet() implementation to consecutively add code points to | |
198 | * the same USet, which will result in a union of the sets of all subconverters. | |
199 | * | |
200 | * For more documentation, see ucnv_getUnicodeSet() in ucnv.h. | |
201 | */ | |
202 | typedef void (*UConverterGetUnicodeSet) (const UConverter *cnv, | |
73c04bcf | 203 | const USetAdder *sa, |
b75a7d8f A |
204 | UConverterUnicodeSet which, |
205 | UErrorCode *pErrorCode); | |
206 | ||
207 | UBool CONVERSION_U_SUCCESS (UErrorCode err); | |
208 | ||
b75a7d8f A |
209 | /** |
210 | * UConverterImpl contains all the data and functions for a converter type. | |
211 | * Its function pointers work much like a C++ vtable. | |
212 | * Many converter types need to define only a subset of the functions; | |
213 | * when a function pointer is NULL, then a default action will be performed. | |
214 | * | |
215 | * Every converter type must implement toUnicode, fromUnicode, and getNextUChar, | |
216 | * otherwise the converter may crash. | |
217 | * Every converter type that has variable-length codepage sequences should | |
218 | * also implement toUnicodeWithOffsets and fromUnicodeWithOffsets for | |
219 | * correct offset handling. | |
220 | * All other functions may or may not be implemented - it depends only on | |
221 | * whether the converter type needs them. | |
222 | * | |
223 | * When open() fails, then close() will be called, if present. | |
224 | */ | |
225 | struct UConverterImpl { | |
226 | UConverterType type; | |
227 | ||
228 | UConverterLoad load; | |
229 | UConverterUnload unload; | |
230 | ||
231 | UConverterOpen open; | |
232 | UConverterClose close; | |
233 | UConverterReset reset; | |
234 | ||
374ca955 A |
235 | UConverterToUnicode toUnicode; |
236 | UConverterToUnicode toUnicodeWithOffsets; | |
237 | UConverterFromUnicode fromUnicode; | |
238 | UConverterFromUnicode fromUnicodeWithOffsets; | |
239 | UConverterGetNextUChar getNextUChar; | |
b75a7d8f A |
240 | |
241 | UConverterGetStarters getStarters; | |
242 | UConverterGetName getName; | |
243 | UConverterWriteSub writeSub; | |
244 | UConverterSafeClone safeClone; | |
245 | UConverterGetUnicodeSet getUnicodeSet; | |
46f4442e A |
246 | |
247 | UConverterConvert toUTF8; | |
248 | UConverterConvert fromUTF8; | |
b75a7d8f A |
249 | }; |
250 | ||
251 | extern const UConverterSharedData | |
252 | _MBCSData, _Latin1Data, | |
253 | _UTF8Data, _UTF16BEData, _UTF16LEData, _UTF32BEData, _UTF32LEData, | |
254 | _ISO2022Data, | |
255 | _LMBCSData1,_LMBCSData2, _LMBCSData3, _LMBCSData4, _LMBCSData5, _LMBCSData6, | |
256 | _LMBCSData8,_LMBCSData11,_LMBCSData16,_LMBCSData17,_LMBCSData18,_LMBCSData19, | |
257 | _HZData,_ISCIIData, _SCSUData, _ASCIIData, | |
258 | _UTF7Data, _Bocu1Data, _UTF16Data, _UTF32Data, _CESU8Data, _IMAPData; | |
259 | ||
260 | U_CDECL_END | |
261 | ||
b75a7d8f A |
262 | /** Always use fallbacks from codepage to Unicode */ |
263 | #define TO_U_USE_FALLBACK(useFallback) TRUE | |
264 | #define UCNV_TO_U_USE_FALLBACK(cnv) TRUE | |
265 | ||
266 | /** Use fallbacks from Unicode to codepage when cnv->useFallback or for private-use code points */ | |
267 | #define IS_PRIVATE_USE(c) ((uint32_t)((c)-0xe000)<0x1900 || (uint32_t)((c)-0xf0000)<0x20000) | |
268 | #define FROM_U_USE_FALLBACK(useFallback, c) ((useFallback) || IS_PRIVATE_USE(c)) | |
269 | #define UCNV_FROM_U_USE_FALLBACK(cnv, c) FROM_U_USE_FALLBACK((cnv)->useFallback, c) | |
270 | ||
271 | /** | |
374ca955 A |
272 | * Magic number for ucnv_getNextUChar(), returned by a |
273 | * getNextUChar() implementation to indicate to use the converter's toUnicode() | |
274 | * instead of the native function. | |
275 | * @internal | |
b75a7d8f | 276 | */ |
374ca955 | 277 | #define UCNV_GET_NEXT_UCHAR_USE_TO_U -9 |
b75a7d8f A |
278 | |
279 | U_CFUNC void | |
280 | ucnv_getCompleteUnicodeSet(const UConverter *cnv, | |
73c04bcf | 281 | const USetAdder *sa, |
b75a7d8f A |
282 | UConverterUnicodeSet which, |
283 | UErrorCode *pErrorCode); | |
284 | ||
285 | U_CFUNC void | |
286 | ucnv_getNonSurrogateUnicodeSet(const UConverter *cnv, | |
73c04bcf | 287 | const USetAdder *sa, |
b75a7d8f A |
288 | UConverterUnicodeSet which, |
289 | UErrorCode *pErrorCode); | |
290 | ||
374ca955 A |
291 | U_CFUNC void |
292 | ucnv_fromUWriteBytes(UConverter *cnv, | |
293 | const char *bytes, int32_t length, | |
294 | char **target, const char *targetLimit, | |
295 | int32_t **offsets, | |
296 | int32_t sourceIndex, | |
297 | UErrorCode *pErrorCode); | |
298 | U_CFUNC void | |
299 | ucnv_toUWriteUChars(UConverter *cnv, | |
300 | const UChar *uchars, int32_t length, | |
301 | UChar **target, const UChar *targetLimit, | |
302 | int32_t **offsets, | |
303 | int32_t sourceIndex, | |
304 | UErrorCode *pErrorCode); | |
305 | ||
306 | U_CFUNC void | |
307 | ucnv_toUWriteCodePoint(UConverter *cnv, | |
308 | UChar32 c, | |
309 | UChar **target, const UChar *targetLimit, | |
310 | int32_t **offsets, | |
311 | int32_t sourceIndex, | |
312 | UErrorCode *pErrorCode); | |
313 | ||
314 | #endif | |
315 | ||
b75a7d8f | 316 | #endif /* UCNV_CNV */ |