headers/libs/iconv/iconv.h

   1 /* Copyright (C) 1999-2003, 2005-2006 Free Software Foundation, Inc.
   2    This file is part of the GNU LIBICONV Library.
   3
   4    The GNU LIBICONV Library is free software; you can redistribute it
   5    and/or modify it under the terms of the GNU Library General Public
   6    License as published by the Free Software Foundation; either version 2
   7    of the License, or (at your option) any later version.
   8
   9    The GNU LIBICONV Library is distributed in the hope that it will be
  10    useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    Library General Public License for more details.
  13
  14    You should have received a copy of the GNU Library General Public
  15    License along with the GNU LIBICONV Library; see the file COPYING.LIB.
  16    If not, write to the Free Software Foundation, Inc., 51 Franklin Street,
  17    Fifth Floor, Boston, MA 02110-1301, USA.  */
  18
  19 /* When installed, this file is called "iconv.h". */
  20
  21 #ifndef _LIBICONV_H
  22 #define _LIBICONV_H
  23
  24 #define _LIBICONV_VERSION 0x010B    /* version number: (major<<8) + minor */
  25 extern int _libiconv_version;           /* Likewise */
  26
  27 /* Define iconv_t ourselves. */
  28 #undef iconv_t
  29 #define iconv_t libiconv_t
  30 typedef void* iconv_t;
  31
  32 /* Get size_t declaration.
  33    Get wchar_t declaration if it exists. */
  34 #include <stddef.h>
  35
  36 /* Get errno declaration and values. */
  37 #include <errno.h>
  38 /* Some systems, like SunOS 4, don't have EILSEQ. Some systems, like BSD/OS,
  39    have EILSEQ in a different header.  On these systems, define EILSEQ
  40    ourselves. */
  41 #ifndef EILSEQ
  42 #define EILSEQ
  43 #endif
  44
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50
  51 /* Allocates descriptor for code conversion from encoding `fromcode' to
  52    encoding `tocode'. */
  53 #ifndef LIBICONV_PLUG
  54 #define iconv_open libiconv_open
  55 #endif
  56 extern iconv_t iconv_open(const char* tocode, const char* fromcode);
  57
  58 /* Converts, using conversion descriptor `cd', at most `*inbytesleft' bytes
  59    starting at `*inbuf', writing at most `*outbytesleft' bytes starting at
  60    `*outbuf'.
  61    Decrements `*inbytesleft' and increments `*inbuf' by the same amount.
  62    Decrements `*outbytesleft' and increments `*outbuf' by the same amount. */
  63 #ifndef LIBICONV_PLUG
  64 #define iconv libiconv
  65 #endif
  66 extern size_t iconv(iconv_t cd,  char* * inbuf, size_t *inbytesleft,
  67                                         char* * outbuf, size_t *outbytesleft);
  68
  69 /* Frees resources allocated for conversion descriptor `cd'. */
  70 #ifndef LIBICONV_PLUG
  71 #define iconv_close libiconv_close
  72 #endif
  73 extern int iconv_close(iconv_t cd);
  74
  75
  76 #ifndef LIBICONV_PLUG
  77
  78 /* Nonstandard extensions. */
  79
  80 /* Control of attributes. */
  81 #define iconvctl libiconvctl
  82 extern int iconvctl(iconv_t cd, int request, void* argument);
  83
  84 /* Hook performed after every successful conversion of a Unicode character. */
  85 typedef void (*iconv_unicode_char_hook) (unsigned int uc, void* data);
  86 /* Hook performed after every successful conversion of a wide character. */
  87 typedef void (*iconv_wide_char_hook) (wchar_t wc, void* data);
  88 /* Set of hooks. */
  89 struct iconv_hooks {
  90   iconv_unicode_char_hook uc_hook;
  91   iconv_wide_char_hook wc_hook;
  92   void* data;
  93 };
  94
  95 /* Fallback function.  Invoked when a small number of bytes could not be
  96    converted to a Unicode character.  This function should process all
  97    bytes from inbuf and may produce replacement Unicode characters by calling
  98    the write_replacement callback repeatedly.  */
  99 typedef void (*iconv_unicode_mb_to_uc_fallback)
 100              (const char* inbuf, size_t inbufsize,
 101               void (*write_replacement) (const unsigned int *buf, size_t buflen,
 102                                          void* callback_arg),
 103               void* callback_arg,
 104               void* data);
 105 /* Fallback function.  Invoked when a Unicode character could not be converted
 106    to the target encoding.  This function should process the character and
 107    may produce replacement bytes (in the target encoding) by calling the
 108    write_replacement callback repeatedly.  */
 109 typedef void (*iconv_unicode_uc_to_mb_fallback)
 110              (unsigned int code,
 111               void (*write_replacement) (const char *buf, size_t buflen,
 112                                          void* callback_arg),
 113               void* callback_arg,
 114               void* data);
 115 #if HAVE_WCHAR_T
 116 /* Fallback function.  Invoked when a number of bytes could not be converted to
 117    a wide character.  This function should process all bytes from inbuf and may
 118    produce replacement wide characters by calling the write_replacement
 119    callback repeatedly.  */
 120 typedef void (*iconv_wchar_mb_to_wc_fallback)
 121              (const char* inbuf, size_t inbufsize,
 122               void (*write_replacement) (const wchar_t *buf, size_t buflen,
 123                                          void* callback_arg),
 124               void* callback_arg,
 125               void* data);
 126 /* Fallback function.  Invoked when a wide character could not be converted to
 127    the target encoding.  This function should process the character and may
 128    produce replacement bytes (in the target encoding) by calling the
 129    write_replacement callback repeatedly.  */
 130 typedef void (*iconv_wchar_wc_to_mb_fallback)
 131              (wchar_t code,
 132               void (*write_replacement) (const char *buf, size_t buflen,
 133                                          void* callback_arg),
 134               void* callback_arg,
 135               void* data);
 136 #else
 137 /* If the wchar_t type does not exist, these two fallback functions are never
 138    invoked.  Their argument list therefore does not matter.  */
 139 typedef void (*iconv_wchar_mb_to_wc_fallback) ();
 140 typedef void (*iconv_wchar_wc_to_mb_fallback) ();
 141 #endif
 142 /* Set of fallbacks. */
 143 struct iconv_fallbacks {
 144   iconv_unicode_mb_to_uc_fallback mb_to_uc_fallback;
 145   iconv_unicode_uc_to_mb_fallback uc_to_mb_fallback;
 146   iconv_wchar_mb_to_wc_fallback mb_to_wc_fallback;
 147   iconv_wchar_wc_to_mb_fallback wc_to_mb_fallback;
 148   void* data;
 149 };
 150
 151 /* Requests for iconvctl. */
 152 #define ICONV_TRIVIALP            0  /* int *argument */
 153 #define ICONV_GET_TRANSLITERATE   1  /* int *argument */
 154 #define ICONV_SET_TRANSLITERATE   2  /* const int *argument */
 155 #define ICONV_GET_DISCARD_ILSEQ   3  /* int *argument */
 156 #define ICONV_SET_DISCARD_ILSEQ   4  /* const int *argument */
 157 #define ICONV_SET_HOOKS           5  /* const struct iconv_hooks *argument */
 158 #define ICONV_SET_FALLBACKS       6  /* const struct iconv_fallbacks *argument */
 159
 160 /* Listing of locale independent encodings. */
 161 #define iconvlist libiconvlist
 162 extern void iconvlist(int (*do_one)(unsigned int namescount,
 163                                     const char * const * names,
 164                                     void* data),
 165                       void* data);
 166
 167 /* Canonicalize an encoding name.
 168    The result is either a canonical encoding name, or name itself. */
 169 extern const char * iconv_canonicalize(const char * name);
 170
 171 #endif
 172
 173
 174 #ifdef __cplusplus
 175 }
 176 #endif
 177
 178
 179 #endif /* _LIBICONV_H */