3rdparty/libiconv/1.15/include/iconv.h.in

   1 /* Copyright (C) 1999-2003, 2005-2006, 2008-2011 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, see <http://www.gnu.org/licenses/>.  */
  17
  18 /* When installed, this file is called "iconv.h". */
  19
  20 #ifndef _LIBICONV_H
  21 #define _LIBICONV_H
  22
  23 #define _LIBICONV_VERSION 0x010F    /* version number: (major<<8) + minor */
  24 extern @DLL_VARIABLE@ int _libiconv_version; /* Likewise */
  25
  26 /* We would like to #include any system header file which could define
  27    iconv_t, 1. in order to eliminate the risk that the user gets compilation
  28    errors because some other system header file includes /usr/include/iconv.h
  29    which defines iconv_t or declares iconv after this file, 2. when compiling
  30    for LIBICONV_PLUG, we need the proper iconv_t type in order to produce
  31    binary compatible code.
  32    But gcc's #include_next is not portable. Thus, once libiconv's iconv.h
  33    has been installed in /usr/local/include, there is no way any more to
  34    include the original /usr/include/iconv.h. We simply have to get away
  35    without it.
  36    Ad 1. The risk that a system header file does
  37    #include "iconv.h"  or  #include_next "iconv.h"
  38    is small. They all do #include <iconv.h>.
  39    Ad 2. The iconv_t type is a pointer type in all cases I have seen. (It
  40    has to be a scalar type because (iconv_t)(-1) is a possible return value
  41    from iconv_open().) */
  42
  43 /* Define iconv_t ourselves. */
  44 #undef iconv_t
  45 #define iconv_t libiconv_t
  46 typedef void* iconv_t;
  47
  48 /* Get size_t declaration.
  49    Get wchar_t declaration if it exists. */
  50 #include <stddef.h>
  51
  52 /* Get errno declaration and values. */
  53 #include <errno.h>
  54 /* Some systems, like SunOS 4, don't have EILSEQ. Some systems, like BSD/OS,
  55    have EILSEQ in a different header.  On these systems, define EILSEQ
  56    ourselves. */
  57 #ifndef EILSEQ
  58 #define EILSEQ @EILSEQ@
  59 #endif
  60
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66
  67 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to
  68    encoding ‘tocode’. */
  69 #ifndef LIBICONV_PLUG
  70 #define iconv_open libiconv_open
  71 #endif
  72 extern iconv_t iconv_open (const char* tocode, const char* fromcode);
  73
  74 /* Converts, using conversion descriptor ‘cd’, at most ‘*inbytesleft’ bytes
  75    starting at ‘*inbuf’, writing at most ‘*outbytesleft’ bytes starting at
  76    ‘*outbuf’.
  77    Decrements ‘*inbytesleft’ and increments ‘*inbuf’ by the same amount.
  78    Decrements ‘*outbytesleft’ and increments ‘*outbuf’ by the same amount. */
  79 #ifndef LIBICONV_PLUG
  80 #define iconv libiconv
  81 #endif
  82 extern size_t iconv (iconv_t cd, @ICONV_CONST@ char* * inbuf, size_t *inbytesleft, char* * outbuf, size_t *outbytesleft);
  83
  84 /* Frees resources allocated for conversion descriptor ‘cd’. */
  85 #ifndef LIBICONV_PLUG
  86 #define iconv_close libiconv_close
  87 #endif
  88 extern int iconv_close (iconv_t cd);
  89
  90
  91 #ifdef __cplusplus
  92 }
  93 #endif
  94
  95
  96 #ifndef LIBICONV_PLUG
  97
  98 /* Nonstandard extensions. */
  99
 100 #if @USE_MBSTATE_T@
 101 #if @BROKEN_WCHAR_H@
 102 /* Tru64 with Desktop Toolkit C has a bug: <stdio.h> must be included before
 103    <wchar.h>.
 104    BSD/OS 4.0.1 has a bug: <stddef.h>, <stdio.h> and <time.h> must be
 105    included before <wchar.h>.  */
 106 #include <stddef.h>
 107 #include <stdio.h>
 108 #include <time.h>
 109 #endif
 110 #include <wchar.h>
 111 #endif
 112
 113 #ifdef __cplusplus
 114 extern "C" {
 115 #endif
 116
 117 /* A type that holds all memory needed by a conversion descriptor.
 118    A pointer to such an object can be used as an iconv_t. */
 119 typedef struct {
 120   void* dummy1[28];
 121 #if @USE_MBSTATE_T@
 122   mbstate_t dummy2;
 123 #endif
 124 } iconv_allocation_t;
 125
 126 /* Allocates descriptor for code conversion from encoding ‘fromcode’ to
 127    encoding ‘tocode’ into preallocated memory. Returns an error indicator
 128    (0 or -1 with errno set). */
 129 #define iconv_open_into libiconv_open_into
 130 extern int iconv_open_into (const char* tocode, const char* fromcode,
 131                             iconv_allocation_t* resultp);
 132
 133 /* Control of attributes. */
 134 #define iconvctl libiconvctl
 135 extern int iconvctl (iconv_t cd, int request, void* argument);
 136
 137 /* Hook performed after every successful conversion of a Unicode character. */
 138 typedef void (*iconv_unicode_char_hook) (unsigned int uc, void* data);
 139 /* Hook performed after every successful conversion of a wide character. */
 140 typedef void (*iconv_wide_char_hook) (wchar_t wc, void* data);
 141 /* Set of hooks. */
 142 struct iconv_hooks {
 143   iconv_unicode_char_hook uc_hook;
 144   iconv_wide_char_hook wc_hook;
 145   void* data;
 146 };
 147
 148 /* Fallback function.  Invoked when a small number of bytes could not be
 149    converted to a Unicode character.  This function should process all
 150    bytes from inbuf and may produce replacement Unicode characters by calling
 151    the write_replacement callback repeatedly.  */
 152 typedef void (*iconv_unicode_mb_to_uc_fallback)
 153              (const char* inbuf, size_t inbufsize,
 154               void (*write_replacement) (const unsigned int *buf, size_t buflen,
 155                                          void* callback_arg),
 156               void* callback_arg,
 157               void* data);
 158 /* Fallback function.  Invoked when a Unicode character could not be converted
 159    to the target encoding.  This function should process the character and
 160    may produce replacement bytes (in the target encoding) by calling the
 161    write_replacement callback repeatedly.  */
 162 typedef void (*iconv_unicode_uc_to_mb_fallback)
 163              (unsigned int code,
 164               void (*write_replacement) (const char *buf, size_t buflen,
 165                                          void* callback_arg),
 166               void* callback_arg,
 167               void* data);
 168 #if @HAVE_WCHAR_T@
 169 /* Fallback function.  Invoked when a number of bytes could not be converted to
 170    a wide character.  This function should process all bytes from inbuf and may
 171    produce replacement wide characters by calling the write_replacement
 172    callback repeatedly.  */
 173 typedef void (*iconv_wchar_mb_to_wc_fallback)
 174              (const char* inbuf, size_t inbufsize,
 175               void (*write_replacement) (const wchar_t *buf, size_t buflen,
 176                                          void* callback_arg),
 177               void* callback_arg,
 178               void* data);
 179 /* Fallback function.  Invoked when a wide character could not be converted to
 180    the target encoding.  This function should process the character and may
 181    produce replacement bytes (in the target encoding) by calling the
 182    write_replacement callback repeatedly.  */
 183 typedef void (*iconv_wchar_wc_to_mb_fallback)
 184              (wchar_t code,
 185               void (*write_replacement) (const char *buf, size_t buflen,
 186                                          void* callback_arg),
 187               void* callback_arg,
 188               void* data);
 189 #else
 190 /* If the wchar_t type does not exist, these two fallback functions are never
 191    invoked.  Their argument list therefore does not matter.  */
 192 typedef void (*iconv_wchar_mb_to_wc_fallback) ();
 193 typedef void (*iconv_wchar_wc_to_mb_fallback) ();
 194 #endif
 195 /* Set of fallbacks. */
 196 struct iconv_fallbacks {
 197   iconv_unicode_mb_to_uc_fallback mb_to_uc_fallback;
 198   iconv_unicode_uc_to_mb_fallback uc_to_mb_fallback;
 199   iconv_wchar_mb_to_wc_fallback mb_to_wc_fallback;
 200   iconv_wchar_wc_to_mb_fallback wc_to_mb_fallback;
 201   void* data;
 202 };
 203
 204 /* Requests for iconvctl. */
 205 #define ICONV_TRIVIALP            0  /* int *argument */
 206 #define ICONV_GET_TRANSLITERATE   1  /* int *argument */
 207 #define ICONV_SET_TRANSLITERATE   2  /* const int *argument */
 208 #define ICONV_GET_DISCARD_ILSEQ   3  /* int *argument */
 209 #define ICONV_SET_DISCARD_ILSEQ   4  /* const int *argument */
 210 #define ICONV_SET_HOOKS           5  /* const struct iconv_hooks *argument */
 211 #define ICONV_SET_FALLBACKS       6  /* const struct iconv_fallbacks *argument */
 212
 213 /* Listing of locale independent encodings. */
 214 #define iconvlist libiconvlist
 215 extern void iconvlist (int (*do_one) (unsigned int namescount,
 216                                       const char * const * names,
 217                                       void* data),
 218                        void* data);
 219
 220 /* Canonicalize an encoding name.
 221    The result is either a canonical encoding name, or name itself. */
 222 extern const char * iconv_canonicalize (const char * name);
 223
 224 /* Support for relocatable packages.  */
 225
 226 /* Sets the original and the current installation prefix of the package.
 227    Relocation simply replaces a pathname starting with the original prefix
 228    by the corresponding pathname with the current prefix instead.  Both
 229    prefixes should be directory names without trailing slash (i.e. use ""
 230    instead of "/").  */
 231 extern void libiconv_set_relocation_prefix (const char *orig_prefix,
 232                                             const char *curr_prefix);
 233
 234 #ifdef __cplusplus
 235 }
 236 #endif
 237
 238 #endif
 239
 240
 241 #endif /* _LIBICONV_H */