gmime/gmime-iconv.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /*  GMime
   3  *  Copyright (C) 2000-2012 Jeffrey Stedfast
   4  *
   5  *  This library is free software; you can redistribute it and/or
   6  *  modify it under the terms of the GNU Lesser General Public License
   7  *  as published by the Free Software Foundation; either version 2.1
   8  *  of the License, or (at your option) any later version.
   9  *
  10  *  This library is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  *  Lesser General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Lesser General Public
  16  *  License along with this library; if not, write to the Free
  17  *  Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA
  18  *  02110-1301, USA.
  19  */
  20
  21
  22 #ifndef __GMIME_ICONV_H__
  23 #define __GMIME_ICONV_H__
  24
  25 #include <glib.h>
  26 #include <iconv.h>
  27
  28 G_BEGIN_DECLS
  29
  30 void g_mime_iconv_init (void);
  31 void g_mime_iconv_shutdown (void);
  32
  33 iconv_t g_mime_iconv_open (const char *to, const char *from);
  34
  35
  36 /**
  37  * g_mime_iconv:
  38  * @cd: iconv_t conversion descriptor
  39  * @inbuf: input buffer
  40  * @inleft: number of bytes left in @inbuf
  41  * @outbuf: output buffer
  42  * @outleft: number of bytes left in @outbuf
  43  *
  44  * The argument @cd must be a conversion descriptor created using the
  45  * function #g_mime_iconv_open.
  46  *
  47  * The main case is when @inbuf is not %NULL and *inbuf is not
  48  * %NULL. In this case, the #g_mime_iconv function converts the
  49  * multibyte sequence starting at *inbuf to a multibyte sequence
  50  * starting at *outbuf. At most *inleft bytes, starting at *inbuf,
  51  * will be read. At most *outleft bytes, starting at *outbuf, will
  52  * be written.
  53  *
  54  * The #g_mime_iconv function converts one multibyte character at a
  55  * time, and for each character conversion it increments *inbuf and
  56  * decrements *inleft by the number of converted input bytes, it
  57  * increments *outbuf and decrements *outleft by the number of
  58  * converted output bytes, and it updates the conversion state
  59  * contained in @cd. The conversion can stop for four reasons:
  60  *
  61  * 1. An invalid multibyte sequence is encountered in the input. In
  62  * this case it sets errno to %EILSEQ and returns (size_t)(-1).
  63  * *inbuf is left pointing to the beginning of the invalid multibyte
  64  * sequence.
  65  *
  66  * 2. The input byte sequence has been entirely converted, i.e.
  67  * *inleft has gone down to %0. In this case #g_mime_iconv returns
  68  * the number of non-reversible conversions performed during this
  69  * call.
  70  *
  71  * 3. An incomplete multibyte sequence is encountered in the input,
  72  * and the input byte sequence terminates after it. In this case it
  73  * sets errno to %EINVAL and returns (size_t)(-1). *inbuf is left
  74  * pointing to the beginning of the incomplete multibyte sequence.
  75  *
  76  * 4. The output buffer has no more room for the next converted
  77  * character. In this case it sets errno to %E2BIG and returns
  78  * (size_t)(-1).
  79  *
  80  * A different case is when @inbuf is %NULL or *inbuf is %NULL, but
  81  * @outbuf is not %NULL and *outbuf is not %NULL. In this case, the
  82  * #g_mime_iconv function attempts to set @cd's conversion state to
  83  * the initial state and store a corresponding shift sequence at
  84  * *outbuf.  At most *outleft bytes, starting at *outbuf, will be
  85  * written.  If the output buffer has no more room for this reset
  86  * sequence, it sets errno to %E2BIG and returns (size_t)(-1).
  87  * Otherwise it increments *outbuf and decrements *outleft by the
  88  * number of bytes written.
  89  *
  90  * A third case is when @inbuf is %NULL or *inbuf is %NULL, and
  91  * @outbuf is %NULL or *outbuf is %NULL. In this case, the
  92  * #g_mime_iconv function sets @cd's conversion state to the initial
  93  * state.
  94  *
  95  * Returns: the number of characters converted in a nonreversible way
  96  * during this call; reversible conversions are not counted. In case
  97  * of error, it sets errno and returns (size_t)(-1).
  98  **/
  99 #define g_mime_iconv(cd,inbuf,inleft,outbuf,outleft) iconv (cd, inbuf, inleft, outbuf, outleft)
 100
 101 int g_mime_iconv_close (iconv_t cd);
 102
 103 G_END_DECLS
 104
 105 #endif /* __GMIME_ICONV_H__ */