1 /* libxml2 - Library for parsing XML documents
2 * Copyright (C) 2006-2019 Free Software Foundation, Inc.
3 *
4 * This file is not part of the GNU gettext program, but is used with
5 * GNU gettext.
6 *
7 * The original copyright notice is as follows:
8 */
9
10 /*
11 * Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved.
12 *
13 * Permission is hereby granted, free of charge, to any person obtaining a copy
14 * of this software and associated documentation files (the "Software"), to deal
15 * in the Software without restriction, including without limitation the rights
16 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17 * copies of the Software, and to permit persons to whom the Software is fur-
18 * nished to do so, subject to the following conditions:
19 *
20 * The above copyright notice and this permission notice shall be included in
21 * all copies or substantial portions of the Software.
22 *
23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FIT-
25 * NESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
29 * THE SOFTWARE.
30 *
31 * Author: Daniel Veillard
32 */
33
34 /*
35 * Summary: interface for the encoding conversion functions
36 * Description: interface for the encoding conversion functions needed for
37 * XML basic encoding and iconv() support.
38 *
39 * Related specs are
40 * rfc2044 (UTF-8 and UTF-16) F. Yergeau Alis Technologies
41 * [ISO-10646] UTF-8 and UTF-16 in Annexes
42 * [ISO-8859-1] ISO Latin-1 characters codes.
43 * [UNICODE] The Unicode Consortium, "The Unicode Standard --
44 * Worldwide Character Encoding -- Version 1.0", Addison-
45 * Wesley, Volume 1, 1991, Volume 2, 1992. UTF-8 is
46 * described in Unicode Technical Report #4.
47 * [US-ASCII] Coded Character Set--7-bit American Standard Code for
48 * Information Interchange, ANSI X3.4-1986.
49 */
50
51 #ifndef __XML_CHAR_ENCODING_H__
52 #define __XML_CHAR_ENCODING_H__
53
54 #include <libxml/xmlversion.h>
55
56 #ifdef LIBXML_ICONV_ENABLED
57 #include <iconv.h>
58 #endif
59 #ifdef LIBXML_ICU_ENABLED
60 #include <unicode/ucnv.h>
61 #endif
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65
66 /*
67 * xmlCharEncoding:
68 *
69 * Predefined values for some standard encodings.
70 * Libxml does not do beforehand translation on UTF8 and ISOLatinX.
71 * It also supports ASCII, ISO-8859-1, and UTF16 (LE and BE) by default.
72 *
73 * Anything else would have to be translated to UTF8 before being
74 * given to the parser itself. The BOM for UTF16 and the encoding
75 * declaration are looked at and a converter is looked for at that
76 * point. If not found the parser stops here as asked by the XML REC. A
77 * converter can be registered by the user using xmlRegisterCharEncodingHandler
78 * but the current form doesn't allow stateful transcoding (a serious
79 * problem agreed !). If iconv has been found it will be used
80 * automatically and allow stateful transcoding, the simplest is then
81 * to be sure to enable iconv and to provide iconv libs for the encoding
82 * support needed.
83 *
84 * Note that the generic "UTF-16" is not a predefined value. Instead, only
85 * the specific UTF-16LE and UTF-16BE are present.
86 */
87 typedef enum {
88 XML_CHAR_ENCODING_ERROR= -1, /* No char encoding detected */
89 XML_CHAR_ENCODING_NONE= 0, /* No char encoding detected */
90 XML_CHAR_ENCODING_UTF8= 1, /* UTF-8 */
91 XML_CHAR_ENCODING_UTF16LE= 2, /* UTF-16 little endian */
92 XML_CHAR_ENCODING_UTF16BE= 3, /* UTF-16 big endian */
93 XML_CHAR_ENCODING_UCS4LE= 4, /* UCS-4 little endian */
94 XML_CHAR_ENCODING_UCS4BE= 5, /* UCS-4 big endian */
95 XML_CHAR_ENCODING_EBCDIC= 6, /* EBCDIC uh! */
96 XML_CHAR_ENCODING_UCS4_2143=7, /* UCS-4 unusual ordering */
97 XML_CHAR_ENCODING_UCS4_3412=8, /* UCS-4 unusual ordering */
98 XML_CHAR_ENCODING_UCS2= 9, /* UCS-2 */
99 XML_CHAR_ENCODING_8859_1= 10,/* ISO-8859-1 ISO Latin 1 */
100 XML_CHAR_ENCODING_8859_2= 11,/* ISO-8859-2 ISO Latin 2 */
101 XML_CHAR_ENCODING_8859_3= 12,/* ISO-8859-3 */
102 XML_CHAR_ENCODING_8859_4= 13,/* ISO-8859-4 */
103 XML_CHAR_ENCODING_8859_5= 14,/* ISO-8859-5 */
104 XML_CHAR_ENCODING_8859_6= 15,/* ISO-8859-6 */
105 XML_CHAR_ENCODING_8859_7= 16,/* ISO-8859-7 */
106 XML_CHAR_ENCODING_8859_8= 17,/* ISO-8859-8 */
107 XML_CHAR_ENCODING_8859_9= 18,/* ISO-8859-9 */
108 XML_CHAR_ENCODING_2022_JP= 19,/* ISO-2022-JP */
109 XML_CHAR_ENCODING_SHIFT_JIS=20,/* Shift_JIS */
110 XML_CHAR_ENCODING_EUC_JP= 21,/* EUC-JP */
111 XML_CHAR_ENCODING_ASCII= 22 /* pure ASCII */
112 } xmlCharEncoding;
113
114 /**
115 * xmlCharEncodingInputFunc:
116 * @out: a pointer to an array of bytes to store the UTF-8 result
117 * @outlen: the length of @out
118 * @in: a pointer to an array of chars in the original encoding
119 * @inlen: the length of @in
120 *
121 * Take a block of chars in the original encoding and try to convert
122 * it to an UTF-8 block of chars out.
123 *
124 * Returns the number of bytes written, -1 if lack of space, or -2
125 * if the transcoding failed.
126 * The value of @inlen after return is the number of octets consumed
127 * if the return value is positive, else unpredictiable.
128 * The value of @outlen after return is the number of octets consumed.
129 */
130 typedef int (* xmlCharEncodingInputFunc)(unsigned char *out, int *outlen,
131 const unsigned char *in, int *inlen);
132
133
134 /**
135 * xmlCharEncodingOutputFunc:
136 * @out: a pointer to an array of bytes to store the result
137 * @outlen: the length of @out
138 * @in: a pointer to an array of UTF-8 chars
139 * @inlen: the length of @in
140 *
141 * Take a block of UTF-8 chars in and try to convert it to another
142 * encoding.
143 * Note: a first call designed to produce heading info is called with
144 * in = NULL. If stateful this should also initialize the encoder state.
145 *
146 * Returns the number of bytes written, -1 if lack of space, or -2
147 * if the transcoding failed.
148 * The value of @inlen after return is the number of octets consumed
149 * if the return value is positive, else unpredictiable.
150 * The value of @outlen after return is the number of octets produced.
151 */
152 typedef int (* xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen,
153 const unsigned char *in, int *inlen);
154
155
156 /*
157 * Block defining the handlers for non UTF-8 encodings.
158 * If iconv is supported, there are two extra fields.
159 */
160 #ifdef LIBXML_ICU_ENABLED
161 /* Size of pivot buffer, same as icu/source/common/ucnv.cpp CHUNK_SIZE */
162 #define ICU_PIVOT_BUF_SIZE 1024
163 struct _uconv_t {
164 UConverter *uconv; /* for conversion between an encoding and UTF-16 */
165 UConverter *utf8; /* for conversion between UTF-8 and UTF-16 */
166 UChar pivot_buf[ICU_PIVOT_BUF_SIZE];
167 UChar *pivot_source;
168 UChar *pivot_target;
169 };
170 typedef struct _uconv_t uconv_t;
171 #endif
172
173 typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler;
174 typedef xmlCharEncodingHandler *xmlCharEncodingHandlerPtr;
175 struct _xmlCharEncodingHandler {
176 char *name;
177 xmlCharEncodingInputFunc input;
178 xmlCharEncodingOutputFunc output;
179 #ifdef LIBXML_ICONV_ENABLED
180 iconv_t iconv_in;
181 iconv_t iconv_out;
182 #endif /* LIBXML_ICONV_ENABLED */
183 #ifdef LIBXML_ICU_ENABLED
184 uconv_t *uconv_in;
185 uconv_t *uconv_out;
186 #endif /* LIBXML_ICU_ENABLED */
187 };
188
189 #ifdef __cplusplus
190 }
191 #endif
192 #include <libxml/tree.h>
193 #ifdef __cplusplus
194 extern "C" {
195 #endif
196
197 /*
198 * Interfaces for encoding handlers.
199 */
200 XMLPUBFUN void XMLCALL
201 xmlInitCharEncodingHandlers (void);
202 XMLPUBFUN void XMLCALL
203 xmlCleanupCharEncodingHandlers (void);
204 XMLPUBFUN void XMLCALL
205 xmlRegisterCharEncodingHandler (xmlCharEncodingHandlerPtr handler);
206 XMLPUBFUN xmlCharEncodingHandlerPtr XMLCALL
207 xmlGetCharEncodingHandler (xmlCharEncoding enc);
208 XMLPUBFUN xmlCharEncodingHandlerPtr XMLCALL
209 xmlFindCharEncodingHandler (const char *name);
210 XMLPUBFUN xmlCharEncodingHandlerPtr XMLCALL
211 xmlNewCharEncodingHandler (const char *name,
212 xmlCharEncodingInputFunc input,
213 xmlCharEncodingOutputFunc output);
214
215 /*
216 * Interfaces for encoding names and aliases.
217 */
218 XMLPUBFUN int XMLCALL
219 xmlAddEncodingAlias (const char *name,
220 const char *alias);
221 XMLPUBFUN int XMLCALL
222 xmlDelEncodingAlias (const char *alias);
223 XMLPUBFUN const char * XMLCALL
224 xmlGetEncodingAlias (const char *alias);
225 XMLPUBFUN void XMLCALL
226 xmlCleanupEncodingAliases (void);
227 XMLPUBFUN xmlCharEncoding XMLCALL
228 xmlParseCharEncoding (const char *name);
229 XMLPUBFUN const char * XMLCALL
230 xmlGetCharEncodingName (xmlCharEncoding enc);
231
232 /*
233 * Interfaces directly used by the parsers.
234 */
235 XMLPUBFUN xmlCharEncoding XMLCALL
236 xmlDetectCharEncoding (const unsigned char *in,
237 int len);
238
239 XMLPUBFUN int XMLCALL
240 xmlCharEncOutFunc (xmlCharEncodingHandler *handler,
241 xmlBufferPtr out,
242 xmlBufferPtr in);
243
244 XMLPUBFUN int XMLCALL
245 xmlCharEncInFunc (xmlCharEncodingHandler *handler,
246 xmlBufferPtr out,
247 xmlBufferPtr in);
248 XMLPUBFUN int XMLCALL
249 xmlCharEncFirstLine (xmlCharEncodingHandler *handler,
250 xmlBufferPtr out,
251 xmlBufferPtr in);
252 XMLPUBFUN int XMLCALL
253 xmlCharEncCloseFunc (xmlCharEncodingHandler *handler);
254
255 /*
256 * Export a few useful functions
257 */
258 #ifdef LIBXML_OUTPUT_ENABLED
259 XMLPUBFUN int XMLCALL
260 UTF8Toisolat1 (unsigned char *out,
261 int *outlen,
262 const unsigned char *in,
263 int *inlen);
264 #endif /* LIBXML_OUTPUT_ENABLED */
265 XMLPUBFUN int XMLCALL
266 isolat1ToUTF8 (unsigned char *out,
267 int *outlen,
268 const unsigned char *in,
269 int *inlen);
270 #ifdef __cplusplus
271 }
272 #endif
273
274 #endif /* __XML_CHAR_ENCODING_H__ */