newlib/libc/iconv/lib/conv.h

   1 /*
   2  * Copyright (c) 2003-2004, Artem B. Bityuckiy
   3  * Copyright (c) 1999,2000, Konstantin Chuguev. All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24  * SUCH DAMAGE.
  25  */
  26 #ifndef __ICONV_CONVERSION_H__
  27 #define __ICONV_CONVERSION_H__
  28
  29 #include <_ansi.h>
  30 #include <reent.h>
  31 #include <sys/types.h>
  32 #include <wchar.h>
  33
  34 /* Bits for 'flags' parameter of 'convert' call */
  35 #define ICONV_DONT_SAVE_BIT 1
  36 #define ICONV_FAIL_BIT      2
  37
  38 /*
  39  * iconv_conversion_handlers_t - keeps iconv conversion handlers.
  40  *
  41  * Keeps 6 interface function handlers:
  42  * open(), close(), convert(), get_mb_cur_max(), get_state(), set_state(),
  43  * get_mb_cur_max() and is_stateful(). Last 5 interface functions are needed to
  44  * support locale subsystem.
  45  *
  46  * ============================================================================
  47  */
  48 typedef struct
  49 {
  50   /*
  51    * open - open and initialize conversion.
  52    *
  53    * PARAMETERS:
  54    *   struct _reent *rptr - reent structure of current thread/process;
  55    *   const char *to     - output encoding's normalized name;
  56    *   const char *from   - input encoding's normalized name.
  57    *
  58    * DESCRIPTION:
  59    *   This function is called from iconv_open() to open conversion. Returns
  60    *   a pointer to conversion-specific data.
  61    *
  62    * RETURN:
  63    *   Pointer to conversion-specific data if success. In case of error
  64    *   returns NULL and sets current thread's/process's errno.
  65    */
  66   void *(*open) (struct _reent *rptr,
  67                           const char *to,
  68                           const char *from);
  69
  70   /*
  71    * close - close conversion.
  72    *
  73    * PARAMETRS:
  74    *   struct _reent *rptr - reent structure of current thread/process;
  75    *   void *data      - conversion-specific data.
  76    *
  77    * DESCRIPTION:
  78    *   This function is called from iconv_close() to close conversion.
  79    *
  80    * RETURN:
  81    *   When successful, returns (size_t)0. In case of error, sets current
  82    *   thread's/process's errno and returns (size_t)-1 (same as iconv_open()).
  83    */
  84   size_t (*close) (struct _reent *rptr,
  85                         void *data);
  86
  87   /* convert - perform encoding conversion.
  88    *
  89    * PARAMETERS:
  90    *   struct _reent *rptr - reent structure of current thread/process.
  91    *   void *data      - conversion-specific data;
  92    *   const unsigned char **inbuf - input data buffer;
  93    *   size_t *inbytesleft          - input buffer's length;
  94    *   unsigned char **outbuf       - output data buffer;
  95    *   size_t *outbytesleft         - output buffer free space;
  96    *   int flags                    - conversion options.
  97    *
  98    * DESCRIPTION:
  99    *   This function is called from iconv() to perform conversion and, if 'flags'
 100    *   is 0, behaves similarly to iconv(). 'inbuf', 'inbytesleft', 'outbuf' and
 101    *   'outbytesleft' are same as in case of iconv() function.
 102    *
 103    *   When flags & 1 isn't 0, 'outbuf' value is ignored and result isn't saved.
 104    *   Another conversion aspects aren't changed.
 105    *
 106    *   When flags & 2 isn't 0, function changes it's behavior in situations,
 107    *   when there is no character in "to" encoding that corresponds to valid
 108    *   character from "from" encoding. iconv() specification stands to perform
 109    *   implimentation-spacific default conversion. If flag & 2 isn't 0,
 110    *   function generates error.
 111    *
 112    * RETURN:
 113    *   Returns the number of characters converted in a non-reversible way.
 114    *   Reversible conversions are not counted. In case of error, sets current
 115    *   thread's/process's errno and returns (size_t)-1 (same as iconv()).
 116    */
 117   size_t (*convert) (struct _reent *rptr,
 118                            void *data,
 119                            const unsigned char **inbuf,
 120                            size_t *inbytesleft,
 121                            unsigned char **outbuf,
 122                            size_t *outbytesleft,
 123                            int flags);
 124
 125   /*
 126    * get_state - get current shift state.
 127    *
 128    * PARAMETERS:
 129    *   void *data   - conversion-specific data;
 130    *   mbstate_t *state - mbstate_t object where shift state will be written;
 131    *   int direction      - 0-"from", 1-"to".
 132    *
 133    * DESCRIPTION:
 134    *   Returns encoding's current shift sequence.
 135    *   If 'direction' is 0, "from" encoding is tested, else
 136    *   "to" encoding is tested.
 137    */
 138   void (*get_state) (void *data,
 139                            mbstate_t *state,
 140                            int direction);
 141
 142   /*
 143    * set_state - set shift state.
 144    *
 145    * PARAMETERS:
 146    *   void *data   - conversion-specific data;
 147    *   mbstate_t *state - mbstate_t object to which shift state will be set.
 148    *   int direction     - 0-"from", 1-"to".
 149    *
 150    * DESCRIPTION:
 151    *   Sets encoding's current shift state to 'state'. if 'state'
 152    *   object is zero-object - reset current shift state.
 153    *   If 'direction' is 0, "from" encoding is set, else
 154    *   "to" encoding is set.
 155    *   Returns 0 if '*state' object has right format, -1 else.
 156    */
 157   int (*set_state) (void *data,
 158                          mbstate_t *state,
 159                          int direction);
 160
 161   /*
 162    * get_mb_cur_max - get maximum character length in bytes.
 163    *
 164    * PARAMETERS:
 165    *   void *data     - conversion-specific data;
 166    *   int direction      - 0-"from", 1-"to".
 167    *
 168    * DESCRIPTION:
 169    *   Returns encoding's maximum character length.
 170    *   If 'direction' is 0, "from" encoding is tested, else
 171    *   "to" encoding is tested.
 172    */
 173   int (*get_mb_cur_max) (void *data,
 174                               int direction);
 175
 176   /*
 177    * is_stateful - is encoding stateful or stateless.
 178    *
 179    * PARAMETERS:
 180    *   void *data - conversion-specific data;
 181    *   int direction  - 0-"from", 1-"to".
 182    *
 183    * DESCRIPTION:
 184    *   Returns 0 if encoding is stateless and 1 if stateful.
 185    *   If 'direction' is 0, "from" encoding is tested, else
 186    *   "to" encoding is tested.
 187    */
 188   int (*is_stateful) (void *data,
 189                            int direction);
 190
 191 } iconv_conversion_handlers_t;
 192
 193
 194 /*
 195  * iconv_conversion_t - iconv conversion definition structure.
 196  *
 197  * ============================================================================
 198  */
 199 typedef struct
 200 {
 201   /* Iconv conversion handlers. */
 202   const iconv_conversion_handlers_t *handlers;
 203
 204   /*
 205    * Conversion-specific data (e.g., points to iconv_ucs_conversion_t
 206    * object if UCS-based conversion is used).
 207    */
 208   void *data;
 209 } iconv_conversion_t;
 210
 211
 212 /* UCS-based conversion handlers */
 213 extern const iconv_conversion_handlers_t
 214 _iconv_ucs_conversion_handlers;
 215
 216 /* Null conversion handlers */
 217 extern const iconv_conversion_handlers_t
 218 _iconv_null_conversion_handlers;
 219
 220 #endif /* !__ICONV_CONVERSION_H__ */
 221