1/* 2 * Summary: interface for the encoding conversion functions 3 * Description: interface for the encoding conversion functions needed for 4 * XML basic encoding and iconv() support. 5 * 6 * Related specs are 7 * rfc2044 (UTF-8 and UTF-16) F. Yergeau Alis Technologies 8 * [ISO-10646] UTF-8 and UTF-16 in Annexes 9 * [ISO-8859-1] ISO Latin-1 characters codes. 10 * [UNICODE] The Unicode Consortium, "The Unicode Standard -- 11 * Worldwide Character Encoding -- Version 1.0", Addison- 12 * Wesley, Volume 1, 1991, Volume 2, 1992. UTF-8 is 13 * described in Unicode Technical Report #4. 14 * [US-ASCII] Coded Character Set--7-bit American Standard Code for 15 * Information Interchange, ANSI X3.4-1986. 16 * 17 * Copy: See Copyright for the status of this software. 18 * 19 * Author: Daniel Veillard 20 */ 21 22#ifndef __XML_CHAR_ENCODING_H__ 23#define __XML_CHAR_ENCODING_H__ 24 25#include <libxml/xmlversion.h> 26 27#ifdef LIBXML_ICONV_ENABLED 28#include <iconv.h> 29#endif 30#ifdef LIBXML_ICU_ENABLED 31struct UConverter; 32typedef struct UConverter UConverter; 33#endif 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/* 39 * xmlCharEncoding: 40 * 41 * Predefined values for some standard encodings. 42 * Libxml does not do beforehand translation on UTF8 and ISOLatinX. 43 * It also supports ASCII, ISO-8859-1, and UTF16 (LE and BE) by default. 44 * 45 * Anything else would have to be translated to UTF8 before being 46 * given to the parser itself. The BOM for UTF16 and the encoding 47 * declaration are looked at and a converter is looked for at that 48 * point. If not found the parser stops here as asked by the XML REC. A 49 * converter can be registered by the user using xmlRegisterCharEncodingHandler 50 * but the current form doesn't allow stateful transcoding (a serious 51 * problem agreed !). If iconv has been found it will be used 52 * automatically and allow stateful transcoding, the simplest is then 53 * to be sure to enable iconv and to provide iconv libs for the encoding 54 * support needed. 55 * 56 * Note that the generic "UTF-16" is not a predefined value. Instead, only 57 * the specific UTF-16LE and UTF-16BE are present. 58 */ 59typedef enum { 60 XML_CHAR_ENCODING_ERROR= -1, /* No char encoding detected */ 61 XML_CHAR_ENCODING_NONE= 0, /* No char encoding detected */ 62 XML_CHAR_ENCODING_UTF8= 1, /* UTF-8 */ 63 XML_CHAR_ENCODING_UTF16LE= 2, /* UTF-16 little endian */ 64 XML_CHAR_ENCODING_UTF16BE= 3, /* UTF-16 big endian */ 65 XML_CHAR_ENCODING_UCS4LE= 4, /* UCS-4 little endian */ 66 XML_CHAR_ENCODING_UCS4BE= 5, /* UCS-4 big endian */ 67 XML_CHAR_ENCODING_EBCDIC= 6, /* EBCDIC uh! */ 68 XML_CHAR_ENCODING_UCS4_2143=7, /* UCS-4 unusual ordering */ 69 XML_CHAR_ENCODING_UCS4_3412=8, /* UCS-4 unusual ordering */ 70 XML_CHAR_ENCODING_UCS2= 9, /* UCS-2 */ 71 XML_CHAR_ENCODING_8859_1= 10,/* ISO-8859-1 ISO Latin 1 */ 72 XML_CHAR_ENCODING_8859_2= 11,/* ISO-8859-2 ISO Latin 2 */ 73 XML_CHAR_ENCODING_8859_3= 12,/* ISO-8859-3 */ 74 XML_CHAR_ENCODING_8859_4= 13,/* ISO-8859-4 */ 75 XML_CHAR_ENCODING_8859_5= 14,/* ISO-8859-5 */ 76 XML_CHAR_ENCODING_8859_6= 15,/* ISO-8859-6 */ 77 XML_CHAR_ENCODING_8859_7= 16,/* ISO-8859-7 */ 78 XML_CHAR_ENCODING_8859_8= 17,/* ISO-8859-8 */ 79 XML_CHAR_ENCODING_8859_9= 18,/* ISO-8859-9 */ 80 XML_CHAR_ENCODING_2022_JP= 19,/* ISO-2022-JP */ 81 XML_CHAR_ENCODING_SHIFT_JIS=20,/* Shift_JIS */ 82 XML_CHAR_ENCODING_EUC_JP= 21,/* EUC-JP */ 83 XML_CHAR_ENCODING_ASCII= 22 /* pure ASCII */ 84} xmlCharEncoding; 85 86/** 87 * xmlCharEncodingInputFunc: 88 * @out: a pointer to an array of bytes to store the UTF-8 result 89 * @outlen: the length of @out 90 * @in: a pointer to an array of chars in the original encoding 91 * @inlen: the length of @in 92 * 93 * Take a block of chars in the original encoding and try to convert 94 * it to an UTF-8 block of chars out. 95 * 96 * Returns the number of bytes written, -1 if lack of space, or -2 97 * if the transcoding failed. 98 * The value of @inlen after return is the number of octets consumed 99 * if the return value is positive, else unpredictiable. 100 * The value of @outlen after return is the number of octets consumed. 101 */ 102typedef int (* xmlCharEncodingInputFunc)(unsigned char *out, int *outlen, 103 const unsigned char *in, int *inlen); 104 105 106/** 107 * xmlCharEncodingOutputFunc: 108 * @out: a pointer to an array of bytes to store the result 109 * @outlen: the length of @out 110 * @in: a pointer to an array of UTF-8 chars 111 * @inlen: the length of @in 112 * 113 * Take a block of UTF-8 chars in and try to convert it to another 114 * encoding. 115 * Note: a first call designed to produce heading info is called with 116 * in = NULL. If stateful this should also initialize the encoder state. 117 * 118 * Returns the number of bytes written, -1 if lack of space, or -2 119 * if the transcoding failed. 120 * The value of @inlen after return is the number of octets consumed 121 * if the return value is positive, else unpredictiable. 122 * The value of @outlen after return is the number of octets produced. 123 */ 124typedef int (* xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen, 125 const unsigned char *in, int *inlen); 126 127 128/* 129 * Block defining the handlers for non UTF-8 encodings. 130 * If iconv is supported, there are two extra fields. 131 */ 132#ifdef LIBXML_ICU_ENABLED 133struct _uconv_t { 134 UConverter *uconv; /* for conversion between an encoding and UTF-16 */ 135 UConverter *utf8; /* for conversion between UTF-8 and UTF-16 */ 136}; 137typedef struct _uconv_t uconv_t; 138#endif 139 140typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler; 141typedef xmlCharEncodingHandler *xmlCharEncodingHandlerPtr; 142struct _xmlCharEncodingHandler { 143 char *name; 144 xmlCharEncodingInputFunc input; 145 xmlCharEncodingOutputFunc output; 146#ifdef LIBXML_ICONV_ENABLED 147 iconv_t iconv_in; 148 iconv_t iconv_out; 149#endif /* LIBXML_ICONV_ENABLED */ 150#ifdef LIBXML_ICU_ENABLED 151 uconv_t *uconv_in; 152 uconv_t *uconv_out; 153#endif /* LIBXML_ICU_ENABLED */ 154}; 155 156#ifdef __cplusplus 157} 158#endif 159#include <libxml/tree.h> 160#ifdef __cplusplus 161extern "C" { 162#endif 163 164/* 165 * Interfaces for encoding handlers. 166 */ 167XMLPUBFUN void XMLCALL 168 xmlInitCharEncodingHandlers (void); 169XMLPUBFUN void XMLCALL 170 xmlCleanupCharEncodingHandlers (void); 171XMLPUBFUN void XMLCALL 172 xmlRegisterCharEncodingHandler (xmlCharEncodingHandlerPtr handler); 173XMLPUBFUN xmlCharEncodingHandlerPtr XMLCALL 174 xmlGetCharEncodingHandler (xmlCharEncoding enc); 175XMLPUBFUN xmlCharEncodingHandlerPtr XMLCALL 176 xmlFindCharEncodingHandler (const char *name); 177XMLPUBFUN xmlCharEncodingHandlerPtr XMLCALL 178 xmlNewCharEncodingHandler (const char *name, 179 xmlCharEncodingInputFunc input, 180 xmlCharEncodingOutputFunc output); 181 182/* 183 * Interfaces for encoding names and aliases. 184 */ 185XMLPUBFUN int XMLCALL 186 xmlAddEncodingAlias (const char *name, 187 const char *alias); 188XMLPUBFUN int XMLCALL 189 xmlDelEncodingAlias (const char *alias); 190XMLPUBFUN const char * XMLCALL 191 xmlGetEncodingAlias (const char *alias); 192XMLPUBFUN void XMLCALL 193 xmlCleanupEncodingAliases (void); 194XMLPUBFUN xmlCharEncoding XMLCALL 195 xmlParseCharEncoding (const char *name); 196XMLPUBFUN const char * XMLCALL 197 xmlGetCharEncodingName (xmlCharEncoding enc); 198 199/* 200 * Interfaces directly used by the parsers. 201 */ 202XMLPUBFUN xmlCharEncoding XMLCALL 203 xmlDetectCharEncoding (const unsigned char *in, 204 int len); 205 206XMLPUBFUN int XMLCALL 207 xmlCharEncOutFunc (xmlCharEncodingHandler *handler, 208 xmlBufferPtr out, 209 xmlBufferPtr in); 210 211XMLPUBFUN int XMLCALL 212 xmlCharEncInFunc (xmlCharEncodingHandler *handler, 213 xmlBufferPtr out, 214 xmlBufferPtr in); 215XMLPUBFUN int XMLCALL 216 xmlCharEncFirstLine (xmlCharEncodingHandler *handler, 217 xmlBufferPtr out, 218 xmlBufferPtr in); 219XMLPUBFUN int XMLCALL 220 xmlCharEncCloseFunc (xmlCharEncodingHandler *handler); 221 222/* 223 * Export a few useful functions 224 */ 225#ifdef LIBXML_OUTPUT_ENABLED 226XMLPUBFUN int XMLCALL 227 UTF8Toisolat1 (unsigned char *out, 228 int *outlen, 229 const unsigned char *in, 230 int *inlen); 231#endif /* LIBXML_OUTPUT_ENABLED */ 232XMLPUBFUN int XMLCALL 233 isolat1ToUTF8 (unsigned char *out, 234 int *outlen, 235 const unsigned char *in, 236 int *inlen); 237#ifdef __cplusplus 238} 239#endif 240 241#endif /* __XML_CHAR_ENCODING_H__ */ 242