libxml2/libxml/encoding.h

0001 /**
0002  * @file
0003  *
0004  * @brief Character encoding conversion functions
0005  *
0006  * @copyright See Copyright for the status of this software.
0007  *
0008  * @author Daniel Veillard
0009  */
0010
0011 #ifndef __XML_CHAR_ENCODING_H__
0012 #define __XML_CHAR_ENCODING_H__
0013
0014 #include <libxml/xmlversion.h>
0015 #include <libxml/xmlerror.h>
0016
0017 #ifdef __cplusplus
0018 extern "C" {
0019 #endif
0020
0021 /*
0022  * Backward compatibility
0023  */
0024 /** @cond ignore */
0025 #define UTF8Toisolat1 xmlUTF8ToIsolat1
0026 #define isolat1ToUTF8 xmlIsolat1ToUTF8
0027 /** @endcond */
0028
0029 /**
0030  * Encoding conversion errors
0031  */
0032 typedef enum {
0033     /** Success */
0034     XML_ENC_ERR_SUCCESS     =  0,
0035     /** Internal or unclassified error */
0036     XML_ENC_ERR_INTERNAL    = -1,
0037     /** Invalid or untranslatable input sequence */
0038     XML_ENC_ERR_INPUT       = -2,
0039     /** Not enough space in output buffer */
0040     XML_ENC_ERR_SPACE       = -3,
0041     /** Out-of-memory error */
0042     XML_ENC_ERR_MEMORY      = -4
0043 } xmlCharEncError;
0044
0045 /**
0046  * Predefined values for some standard encodings.
0047  */
0048 typedef enum {
0049     /** No char encoding detected */
0050     XML_CHAR_ENCODING_ERROR=   -1,
0051     /** No char encoding detected */
0052     XML_CHAR_ENCODING_NONE= 0,
0053     /** UTF-8 */
0054     XML_CHAR_ENCODING_UTF8= 1,
0055     /** UTF-16 little endian */
0056     XML_CHAR_ENCODING_UTF16LE=  2,
0057     /** UTF-16 big endian */
0058     XML_CHAR_ENCODING_UTF16BE=  3,
0059     /** UCS-4 little endian */
0060     XML_CHAR_ENCODING_UCS4LE=   4,
0061     /** UCS-4 big endian */
0062     XML_CHAR_ENCODING_UCS4BE=   5,
0063     /** EBCDIC uh! */
0064     XML_CHAR_ENCODING_EBCDIC=   6,
0065     /** UCS-4 unusual ordering */
0066     XML_CHAR_ENCODING_UCS4_2143=7,
0067     /** UCS-4 unusual ordering */
0068     XML_CHAR_ENCODING_UCS4_3412=8,
0069     /** UCS-2 */
0070     XML_CHAR_ENCODING_UCS2= 9,
0071     /** ISO-8859-1 ISO Latin 1 */
0072     XML_CHAR_ENCODING_8859_1=   10,
0073     /** ISO-8859-2 ISO Latin 2 */
0074     XML_CHAR_ENCODING_8859_2=   11,
0075     /** ISO-8859-3 */
0076     XML_CHAR_ENCODING_8859_3=   12,
0077     /** ISO-8859-4 */
0078     XML_CHAR_ENCODING_8859_4=   13,
0079     /** ISO-8859-5 */
0080     XML_CHAR_ENCODING_8859_5=   14,
0081     /** ISO-8859-6 */
0082     XML_CHAR_ENCODING_8859_6=   15,
0083     /** ISO-8859-7 */
0084     XML_CHAR_ENCODING_8859_7=   16,
0085     /** ISO-8859-8 */
0086     XML_CHAR_ENCODING_8859_8=   17,
0087     /** ISO-8859-9 */
0088     XML_CHAR_ENCODING_8859_9=   18,
0089     /** ISO-2022-JP */
0090     XML_CHAR_ENCODING_2022_JP=  19,
0091     /** Shift_JIS */
0092     XML_CHAR_ENCODING_SHIFT_JIS=20,
0093     /** EUC-JP */
0094     XML_CHAR_ENCODING_EUC_JP=   21,
0095     /** pure ASCII */
0096     XML_CHAR_ENCODING_ASCII=    22,
0097     /** UTF-16 native, available since 2.14 */
0098     XML_CHAR_ENCODING_UTF16=    23,
0099     /** HTML (output only), available since 2.14 */
0100     XML_CHAR_ENCODING_HTML= 24,
0101     /** ISO-8859-10, available since 2.14 */
0102     XML_CHAR_ENCODING_8859_10=  25,
0103     /** ISO-8859-11, available since 2.14 */
0104     XML_CHAR_ENCODING_8859_11=  26,
0105     /** ISO-8859-13, available since 2.14 */
0106     XML_CHAR_ENCODING_8859_13=  27,
0107     /** ISO-8859-14, available since 2.14 */
0108     XML_CHAR_ENCODING_8859_14=  28,
0109     /** ISO-8859-15, available since 2.14 */
0110     XML_CHAR_ENCODING_8859_15=  29,
0111     /** ISO-8859-16, available since 2.14 */
0112     XML_CHAR_ENCODING_8859_16=  30,
0113     /** windows-1252, available since 2.15 */
0114     XML_CHAR_ENCODING_WINDOWS_1252 = 31
0115 } xmlCharEncoding;
0116
0117 /**
0118  * Encoding conversion flags
0119  */
0120 typedef enum {
0121     /** Create converter for input (conversion to UTF-8) */
0122     XML_ENC_INPUT = (1 << 0),
0123     /** Create converter for output (conversion from UTF-8) */
0124     XML_ENC_OUTPUT = (1 << 1),
0125     /** Use HTML5 mappings */
0126     XML_ENC_HTML = (1 << 2)
0127 } xmlCharEncFlags;
0128
0129 /**
0130  * Convert characters to UTF-8.
0131  *
0132  * On success, the value of `inlen` after return is the number of
0133  * bytes consumed and `outlen` is the number of bytes produced.
0134  *
0135  * @param out  a pointer to an array of bytes to store the UTF-8 result
0136  * @param outlen  the length of `out`
0137  * @param in  a pointer to an array of chars in the original encoding
0138  * @param inlen  the length of `in`
0139  * @returns the number of bytes written or an xmlCharEncError code.
0140  */
0141 typedef int (*xmlCharEncodingInputFunc)(unsigned char *out, int *outlen,
0142                                         const unsigned char *in, int *inlen);
0143
0144
0145 /**
0146  * Convert characters from UTF-8.
0147  *
0148  * On success, the value of `inlen` after return is the number of
0149  * bytes consumed and `outlen` is the number of bytes produced.
0150  *
0151  * @param out  a pointer to an array of bytes to store the result
0152  * @param outlen  the length of `out`
0153  * @param in  a pointer to an array of UTF-8 chars
0154  * @param inlen  the length of `in`
0155  * @returns the number of bytes written or an xmlCharEncError code.
0156  */
0157 typedef int (*xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen,
0158                                          const unsigned char *in, int *inlen);
0159
0160
0161 /**
0162  * Convert between character encodings.
0163  *
0164  * The value of `inlen` after return is the number of bytes consumed
0165  * and `outlen` is the number of bytes produced.
0166  *
0167  * If the converter can consume partial multi-byte sequences, the
0168  * `flush` flag can be used to detect truncated sequences at EOF.
0169  * Otherwise, the flag can be ignored.
0170  *
0171  * @param vctxt  conversion context
0172  * @param out  a pointer to an array of bytes to store the result
0173  * @param outlen  the length of `out`
0174  * @param in  a pointer to an array of input bytes
0175  * @param inlen  the length of `in`
0176  * @param flush  end of input
0177  * @returns an xmlCharEncError code.
0178  */
0179 typedef xmlCharEncError
0180 (*xmlCharEncConvFunc)(void *vctxt, unsigned char *out, int *outlen,
0181                       const unsigned char *in, int *inlen, int flush);
0182
0183 /**
0184  * Free a conversion context.
0185  *
0186  * @param vctxt  conversion context
0187  */
0188 typedef void
0189 (*xmlCharEncConvCtxtDtor)(void *vctxt);
0190
0191 /** Character encoding converter */
0192 typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler;
0193 typedef xmlCharEncodingHandler *xmlCharEncodingHandlerPtr;
0194 /**
0195  * A character encoding conversion handler for non UTF-8 encodings.
0196  *
0197  * This structure will be made private.
0198  */
0199 struct _xmlCharEncodingHandler {
0200     char *name XML_DEPRECATED_MEMBER;
0201     union {
0202         xmlCharEncConvFunc func;
0203         xmlCharEncodingInputFunc legacyFunc;
0204     } input XML_DEPRECATED_MEMBER;
0205     union {
0206         xmlCharEncConvFunc func;
0207         xmlCharEncodingOutputFunc legacyFunc;
0208     } output XML_DEPRECATED_MEMBER;
0209     void *inputCtxt XML_DEPRECATED_MEMBER;
0210     void *outputCtxt XML_DEPRECATED_MEMBER;
0211     xmlCharEncConvCtxtDtor ctxtDtor XML_DEPRECATED_MEMBER;
0212     int flags XML_DEPRECATED_MEMBER;
0213 };
0214
0215 /**
0216  * If this function returns XML_ERR_OK, it must fill the `out`
0217  * pointer with an encoding handler. The handler can be obtained
0218  * from #xmlCharEncNewCustomHandler.
0219  *
0220  * `flags` can contain XML_ENC_INPUT, XML_ENC_OUTPUT or both.
0221  *
0222  * @param vctxt  user data
0223  * @param name  encoding name
0224  * @param flags  bit mask of flags
0225  * @param out  pointer to resulting handler
0226  * @returns an xmlParserErrors code.
0227  */
0228 typedef xmlParserErrors
0229 (*xmlCharEncConvImpl)(void *vctxt, const char *name, xmlCharEncFlags flags,
0230                       xmlCharEncodingHandler **out);
0231
0232 /*
0233  * Interfaces for encoding handlers.
0234  */
0235 XML_DEPRECATED
0236 XMLPUBFUN void
0237     xmlInitCharEncodingHandlers (void);
0238 XML_DEPRECATED
0239 XMLPUBFUN void
0240     xmlCleanupCharEncodingHandlers  (void);
0241 XML_DEPRECATED
0242 XMLPUBFUN void
0243     xmlRegisterCharEncodingHandler  (xmlCharEncodingHandler *handler);
0244 XMLPUBFUN xmlParserErrors
0245     xmlLookupCharEncodingHandler    (xmlCharEncoding enc,
0246                      xmlCharEncodingHandler **out);
0247 XMLPUBFUN xmlParserErrors
0248     xmlOpenCharEncodingHandler  (const char *name,
0249                      int output,
0250                      xmlCharEncodingHandler **out);
0251 XMLPUBFUN xmlParserErrors
0252     xmlCreateCharEncodingHandler    (const char *name,
0253                      xmlCharEncFlags flags,
0254                      xmlCharEncConvImpl impl,
0255                      void *implCtxt,
0256                      xmlCharEncodingHandler **out);
0257 XMLPUBFUN xmlCharEncodingHandler *
0258     xmlGetCharEncodingHandler   (xmlCharEncoding enc);
0259 XMLPUBFUN xmlCharEncodingHandler *
0260     xmlFindCharEncodingHandler  (const char *name);
0261 XML_DEPRECATED
0262 XMLPUBFUN xmlCharEncodingHandler *
0263     xmlNewCharEncodingHandler   (const char *name,
0264                      xmlCharEncodingInputFunc input,
0265                      xmlCharEncodingOutputFunc output);
0266 XMLPUBFUN xmlParserErrors
0267     xmlCharEncNewCustomHandler  (const char *name,
0268                      xmlCharEncConvFunc input,
0269                      xmlCharEncConvFunc output,
0270                      xmlCharEncConvCtxtDtor ctxtDtor,
0271                      void *inputCtxt,
0272                      void *outputCtxt,
0273                      xmlCharEncodingHandler **out);
0274
0275 /*
0276  * Interfaces for encoding names and aliases.
0277  */
0278 XML_DEPRECATED
0279 XMLPUBFUN int
0280     xmlAddEncodingAlias     (const char *name,
0281                      const char *alias);
0282 XML_DEPRECATED
0283 XMLPUBFUN int
0284     xmlDelEncodingAlias     (const char *alias);
0285 XML_DEPRECATED
0286 XMLPUBFUN const char *
0287     xmlGetEncodingAlias     (const char *alias);
0288 XML_DEPRECATED
0289 XMLPUBFUN void
0290     xmlCleanupEncodingAliases   (void);
0291 XMLPUBFUN xmlCharEncoding
0292     xmlParseCharEncoding        (const char *name);
0293 XMLPUBFUN const char *
0294     xmlGetCharEncodingName      (xmlCharEncoding enc);
0295
0296 /*
0297  * Interfaces directly used by the parsers.
0298  */
0299 XMLPUBFUN xmlCharEncoding
0300     xmlDetectCharEncoding       (const unsigned char *in,
0301                      int len);
0302
0303 struct _xmlBuffer;
0304 XMLPUBFUN int
0305     xmlCharEncOutFunc       (xmlCharEncodingHandler *handler,
0306                      struct _xmlBuffer *out,
0307                      struct _xmlBuffer *in);
0308
0309 XMLPUBFUN int
0310     xmlCharEncInFunc        (xmlCharEncodingHandler *handler,
0311                      struct _xmlBuffer *out,
0312                      struct _xmlBuffer *in);
0313 XML_DEPRECATED
0314 XMLPUBFUN int
0315     xmlCharEncFirstLine     (xmlCharEncodingHandler *handler,
0316                      struct _xmlBuffer *out,
0317                      struct _xmlBuffer *in);
0318 XMLPUBFUN int
0319     xmlCharEncCloseFunc     (xmlCharEncodingHandler *handler);
0320
0321 /*
0322  * Export a few useful functions
0323  */
0324 #ifdef LIBXML_OUTPUT_ENABLED
0325 XMLPUBFUN int
0326     xmlUTF8ToIsolat1        (unsigned char *out,
0327                      int *outlen,
0328                      const unsigned char *in,
0329                      int *inlen);
0330 #endif /* LIBXML_OUTPUT_ENABLED */
0331 XMLPUBFUN int
0332     xmlIsolat1ToUTF8        (unsigned char *out,
0333                      int *outlen,
0334                      const unsigned char *in,
0335                      int *inlen);
0336 #ifdef __cplusplus
0337 }
0338 #endif
0339
0340 #endif /* __XML_CHAR_ENCODING_H__ */