mdw@git.distorted.org.uk Git - sgt/charset/blob - charset.h

   1 /*
   2  * charset.h - header file for general character set conversion
   3  * routines.
   4  */
   5
   6 #ifndef charset_charset_h
   7 #define charset_charset_h
   8
   9 #include <stddef.h>
  10
  11 /*
  12  * Enumeration that lists all the multibyte or single-byte
  13  * character sets known to this library.
  14  */
  15 typedef enum {
  16     CS_NONE,                           /* used for reporting errors, etc */
  17     CS_ASCII,                          /* ordinary US-ASCII is worth having! */
  18     CS_ISO8859_1,
  19     CS_ISO8859_1_X11,                  /* X font encoding with VT100 glyphs */
  20     CS_ISO8859_2,
  21     CS_ISO8859_3,
  22     CS_ISO8859_4,
  23     CS_ISO8859_5,
  24     CS_ISO8859_6,
  25     CS_ISO8859_7,
  26     CS_ISO8859_8,
  27     CS_ISO8859_9,
  28     CS_ISO8859_10,
  29     CS_ISO8859_11,
  30     CS_ISO8859_13,
  31     CS_ISO8859_14,
  32     CS_ISO8859_15,
  33     CS_ISO8859_16,
  34     CS_CP437,
  35     CS_CP850,
  36     CS_CP1250,
  37     CS_CP1251,
  38     CS_CP1252,
  39     CS_CP1253,
  40     CS_CP1254,
  41     CS_CP1255,
  42     CS_CP1256,
  43     CS_CP1257,
  44     CS_CP1258,
  45     CS_KOI8_R,
  46     CS_KOI8_U,
  47     CS_KOI8_RU,
  48     CS_JISX0201,
  49     CS_MAC_ROMAN,
  50     CS_MAC_TURKISH,
  51     CS_MAC_CROATIAN,
  52     CS_MAC_ICELAND,
  53     CS_MAC_ROMANIAN,
  54     CS_MAC_GREEK,
  55     CS_MAC_CYRILLIC,
  56     CS_MAC_THAI,
  57     CS_MAC_CENTEURO,
  58     CS_MAC_SYMBOL,
  59     CS_MAC_DINGBATS,
  60     CS_MAC_ROMAN_OLD,
  61     CS_MAC_CROATIAN_OLD,
  62     CS_MAC_ICELAND_OLD,
  63     CS_MAC_ROMANIAN_OLD,
  64     CS_MAC_GREEK_OLD,
  65     CS_MAC_CYRILLIC_OLD,
  66     CS_MAC_UKRAINE,
  67     CS_MAC_VT100,
  68     CS_MAC_VT100_OLD,
  69     CS_VISCII,
  70     CS_HP_ROMAN8,
  71     CS_DEC_MCS,
  72     CS_UTF8,
  73     CS_UTF7,
  74     CS_UTF7_CONSERVATIVE,
  75     CS_UTF16,
  76     CS_UTF16BE,
  77     CS_UTF16LE,
  78     CS_EUC_JP,
  79     CS_EUC_CN,
  80     CS_EUC_KR,
  81     CS_ISO2022_JP,
  82     CS_ISO2022_KR,
  83     CS_BIG5,
  84     CS_SHIFT_JIS,
  85     CS_HZ,
  86     CS_CP949,
  87     CS_PDF,
  88     CS_CTEXT,
  89     CS_BS4730,
  90     CS_DEC_GRAPHICS,
  91     CS_ISO2022
  92 } charset_t;
  93
  94 typedef struct {
  95     unsigned long s0, s1;
  96 } charset_state;
  97
  98 /*
  99  * This macro is used to initialise a charset_state structure:
 100  *
 101  *   charset_state mystate = CHARSET_INIT_STATE;
 102  */
 103 #define CHARSET_INIT_STATE { 0L, 0L }  /* a suitable initialiser */
 104
 105 /*
 106  * This external variable contains the same data, but is provided
 107  * for easy structure-copy assignment:
 108  *
 109  *   mystate = charset_init_state;
 110  */
 111 extern const charset_state charset_init_state;
 112
 113 /*
 114  * Routine to convert a MB/SB character set to Unicode.
 115  *
 116  * This routine accepts some number of bytes, updates a state
 117  * variable, and outputs some number of Unicode characters. There
 118  * are no guarantees. You can't even guarantee that at most one
 119  * Unicode character will be output per byte you feed in; for
 120  * example, suppose you're reading UTF-8, you've seen E1 80, and
 121  * then you suddenly see FE. Now you need to output _two_ error
 122  * characters - one for the incomplete sequence E1 80, and one for
 123  * the completely invalid UTF-8 byte FE.
 124  *
 125  * Returns the number of wide characters output; will never output
 126  * more than the size of the buffer (as specified on input).
 127  * Advances the `input' pointer and decrements `inlen', to indicate
 128  * how far along the input string it got.
 129  *
 130  * The sequence of `errlen' wide characters pointed to by `errstr'
 131  * will be used to indicate a conversion error. If `errstr' is
 132  * NULL, `errlen' will be ignored, and the library will choose
 133  * something sensible to do on its own. For Unicode, this will be
 134  * U+FFFD (REPLACEMENT CHARACTER).
 135  */
 136
 137 int charset_to_unicode(const char **input, int *inlen,
 138                        wchar_t *output, int outlen,
 139                        int charset, charset_state *state,
 140                        const wchar_t *errstr, int errlen);
 141
 142 /*
 143  * Routine to convert Unicode to an MB/SB character set.
 144  *
 145  * This routine accepts some number of Unicode characters, updates
 146  * a state variable, and outputs some number of bytes.
 147  *
 148  * Returns the number of bytes output; will never output more than
 149  * the size of the buffer (as specified on input), and will never
 150  * output a partial MB character. Advances the `input' pointer and
 151  * decrements `inlen', to indicate how far along the input string
 152  * it got.
 153  *
 154  * If `error' is non-NULL and a character is found which cannot be
 155  * expressed in the output charset, conversion will terminate at
 156  * that character (so `input' points to the offending character)
 157  * and `*error' will be set to TRUE; if `error' is non-NULL and no
 158  * difficult characters are encountered, `*error' will be set to
 159  * FALSE. If `error' is NULL, difficult characters will simply be
 160  * ignored.
 161  *
 162  * If `input' is NULL, this routine will output the necessary bytes
 163  * to reset the encoding state in any way which might be required
 164  * at the end of an output piece of text.
 165  */
 166
 167 int charset_from_unicode(const wchar_t **input, int *inlen,
 168                          char *output, int outlen,
 169                          int charset, charset_state *state, int *error);
 170
 171 /*
 172  * Convert X11 encoding names to and from our charset identifiers.
 173  */
 174 const char *charset_to_xenc(int charset);
 175 int charset_from_xenc(const char *name);
 176
 177 /*
 178  * Convert MIME encoding names to and from our charset identifiers.
 179  */
 180 const char *charset_to_mimeenc(int charset);
 181 int charset_from_mimeenc(const char *name);
 182
 183 /*
 184  * Convert our own encoding names to and from our charset
 185  * identifiers.
 186  */
 187 const char *charset_to_localenc(int charset);
 188 int charset_from_localenc(const char *name);
 189 int charset_localenc_nth(int n);
 190
 191 /*
 192  * Convert Mac OS script/region/font to our charset identifiers.
 193  */
 194 int charset_from_macenc(int script, int region, int sysvers,
 195                         const char *fontname);
 196
 197 /*
 198  * Upgrade a charset identifier to a superset charset which is
 199  * often confused with it. For example, people whose MUAs report
 200  * their mail as ASCII or ISO8859-1 often in practice turn out to
 201  * be using CP1252 quote characters, so when parsing incoming mail
 202  * it is prudent to treat ASCII and ISO8859-1 as aliases for CP1252
 203  * - and since it's a superset of both, this will cause no
 204  * genuinely correct mail to be parsed wrongly.
 205  */
 206 int charset_upgrade(int charset);
 207
 208 /*
 209  * This function returns TRUE if the input charset is a vaguely
 210  * sensible superset of ASCII. That is, it returns FALSE for 7-bit
 211  * encoding formats such as HZ and UTF-7.
 212  */
 213 int charset_contains_ascii(int charset);
 214
 215 /*
 216  * This function tries to deduce the CS_* identifier of the charset
 217  * used in the current C locale. It falls back to CS_ASCII if it
 218  * can't figure it out at all, so it will always return a valid
 219  * charset.
 220  *
 221  * (Note that you should have already called setlocale(LC_CTYPE,
 222  * "") to guarantee that this function will do the right thing.)
 223  */
 224 int charset_from_locale(void);
 225
 226 #endif /* charset_charset_h */