<refentry id="gmime-gmime-iconv">
<refmeta>
<refentrytitle role="top_of_page" id="gmime-gmime-iconv.top_of_page">gmime-iconv</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  GMIME Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gmime-iconv</refname>
<refpurpose>Low-level routines for converting text from one charset to another</refpurpose>
</refnamediv>

<refsynopsisdiv id="gmime-gmime-iconv.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis><link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-iconv-init">g_mime_iconv_init</link>                   (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-iconv-shutdown">g_mime_iconv_shutdown</link>               (<parameter><type>void</type></parameter>);
<link linkend="iconv-t"><returnvalue>iconv_t</returnvalue></link>             <link linkend="g-mime-iconv-open">g_mime_iconv_open</link>                   (<parameter>const <link linkend="char"><type>char</type></link> *to</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *from</parameter>);
#define             <link linkend="g-mime-iconv">g_mime_iconv</link>                        (cd,
                                                         inbuf,
                                                         inleft,
                                                         outbuf,
                                                         outleft)
<link linkend="int"><returnvalue>int</returnvalue></link>                 <link linkend="g-mime-iconv-close">g_mime_iconv_close</link>                  (<parameter><link linkend="iconv-t"><type>iconv_t</type></link> cd</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="gmime-gmime-iconv.description" role="desc">
<title role="desc.title">Description</title>
<para>
These functions are wrappers around the system iconv(3)
routines. The purpose of these wrappers are two-fold:
</para>
<para>
1. Cache iconv_t descriptors for you in order to optimize
opening/closing many descriptors frequently
</para>
<para>
and
</para>
<para>
2. To use the appropriate system charset alias for the MIME charset
names given as arguments.
</para>
</refsect1>
<refsect1 id="gmime-gmime-iconv.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-mime-iconv-init" role="function">
<title>g_mime_iconv_init ()</title>
<indexterm zone="g-mime-iconv-init"><primary>g_mime_iconv_init</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_iconv_init                   (<parameter><type>void</type></parameter>);</programlisting>
<para>
Initialize GMime's iconv cache. This *MUST* be called before any
gmime-iconv interfaces will work correctly.
</para>
<para>
Note: this function is called for you by <link linkend="g-mime-init"><function>g_mime_init()</function></link>.
</para></refsect2>
<refsect2 id="g-mime-iconv-shutdown" role="function">
<title>g_mime_iconv_shutdown ()</title>
<indexterm zone="g-mime-iconv-shutdown"><primary>g_mime_iconv_shutdown</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_iconv_shutdown               (<parameter><type>void</type></parameter>);</programlisting>
<para>
Frees internal iconv caches created in <link linkend="g-mime-iconv-init"><function>g_mime_iconv_init()</function></link>.
</para>
<para>
Note: this function is called for you by <link linkend="g-mime-shutdown"><function>g_mime_shutdown()</function></link>.
</para></refsect2>
<refsect2 id="g-mime-iconv-open" role="function">
<title>g_mime_iconv_open ()</title>
<indexterm zone="g-mime-iconv-open"><primary>g_mime_iconv_open</primary></indexterm>
<programlisting><link linkend="iconv-t"><returnvalue>iconv_t</returnvalue></link>             g_mime_iconv_open                   (<parameter>const <link linkend="char"><type>char</type></link> *to</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *from</parameter>);</programlisting>
<para>
Allocates a coversion descriptor suitable for converting byte
sequences from charset <parameter>from</parameter> to charset <parameter>to</parameter>. The resulting
descriptor can be used with <link linkend="iconv"><function>iconv()</function></link> (or the <link linkend="g-mime-iconv"><function>g_mime_iconv()</function></link> wrapper) any
number of times until closed using <link linkend="g-mime-iconv-close"><function>g_mime_iconv_close()</function></link>.
</para>
<para>
See the manual page for iconv_open(3) for further details.
</para><variablelist role="params">
<varlistentry><term><parameter>to</parameter>&#160;:</term>
<listitem><simpara>charset to convert to
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>from</parameter>&#160;:</term>
<listitem><simpara>charset to convert from
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new conversion descriptor for use with <link linkend="g-mime-iconv"><function>g_mime_iconv()</function></link> on
success or (iconv_t) <link linkend="1:CAPS"><literal>-1</literal></link> on fail as well as setting an appropriate
errno value.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-iconv" role="macro">
<title>g_mime_iconv()</title>
<indexterm zone="g-mime-iconv"><primary>g_mime_iconv</primary></indexterm>
<programlisting>#define             g_mime_iconv(cd,inbuf,inleft,outbuf,outleft)</programlisting>
<para>
The argument <parameter>cd</parameter> must be a conversion descriptor created using the
function <link linkend="g-mime-iconv-open"><type>g_mime_iconv_open</type></link>.
</para>
<para>
The main case is when <parameter>inbuf</parameter> is not <link linkend="NULL:CAPS"><literal>NULL</literal></link> and *inbuf is not
<link linkend="NULL:CAPS"><literal>NULL</literal></link>. In this case, the <link linkend="g-mime-iconv"><type>g_mime_iconv</type></link> function converts the
multibyte sequence starting at *inbuf to a multibyte sequence
starting at *outbuf. At most *inleft bytes, starting at *inbuf,
will be read. At most *outleft bytes, starting at *outbuf, will
be written.
</para>
<para>
The <link linkend="g-mime-iconv"><type>g_mime_iconv</type></link> function converts one multibyte character at a
time, and for each character conversion it increments *inbuf and
decrements *inleft by the number of converted input bytes, it
increments *outbuf and decrements *outleft by the number of
converted output bytes, and it updates the conversion state
contained in <parameter>cd</parameter>. The conversion can stop for four reasons:
</para>
<para>
1. An invalid multibyte sequence is encountered in the input. In
this case it sets errno to <link linkend="EILSEQ:CAPS"><literal>EILSEQ</literal></link> and returns (size_t)(-1).
*inbuf is left pointing to the beginning of the invalid multibyte
sequence.
</para>
<para>
2. The input byte sequence has been entirely converted, i.e.
*inleft has gone down to <link linkend="0:CAPS"><literal>0</literal></link>. In this case <link linkend="g-mime-iconv"><type>g_mime_iconv</type></link> returns
the number of non-reversible conversions performed during this
call.
</para>
<para>
3. An incomplete multibyte sequence is encountered in the input,
and the input byte sequence terminates after it. In this case it
sets errno to <link linkend="EINVAL:CAPS"><literal>EINVAL</literal></link> and returns (size_t)(-1). *inbuf is left
pointing to the beginning of the incomplete multibyte sequence.
</para>
<para>
4. The output buffer has no more room for the next converted
character. In this case it sets errno to <link linkend="E2BIG:CAPS"><literal>E2BIG</literal></link> and returns
(size_t)(-1).
</para>
<para>
A different case is when <parameter>inbuf</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> or *inbuf is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, but
<parameter>outbuf</parameter> is not <link linkend="NULL:CAPS"><literal>NULL</literal></link> and *outbuf is not <link linkend="NULL:CAPS"><literal>NULL</literal></link>. In this case, the
<link linkend="g-mime-iconv"><type>g_mime_iconv</type></link> function attempts to set <parameter>cd</parameter>'s conversion state to
the initial state and store a corresponding shift sequence at
*outbuf.  At most *outleft bytes, starting at *outbuf, will be
written.  If the output buffer has no more room for this reset
sequence, it sets errno to <link linkend="E2BIG:CAPS"><literal>E2BIG</literal></link> and returns (size_t)(-1).
Otherwise it increments *outbuf and decrements *outleft by the
number of bytes written.
</para>
<para>
A third case is when <parameter>inbuf</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> or *inbuf is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, and
<parameter>outbuf</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link> or *outbuf is <link linkend="NULL:CAPS"><literal>NULL</literal></link>. In this case, the
<link linkend="g-mime-iconv"><type>g_mime_iconv</type></link> function sets <parameter>cd</parameter>'s conversion state to the initial
state.
</para><variablelist role="params">
<varlistentry><term><parameter>cd</parameter>&#160;:</term>
<listitem><simpara>iconv_t conversion descriptor
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>inbuf</parameter>&#160;:</term>
<listitem><simpara>input buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>inleft</parameter>&#160;:</term>
<listitem><simpara>number of bytes left in <parameter>inbuf</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>outbuf</parameter>&#160;:</term>
<listitem><simpara>output buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>outleft</parameter>&#160;:</term>
<listitem><simpara>number of bytes left in <parameter>outbuf</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of characters converted in a nonreversible way
during this call; reversible conversions are not counted. In case
of error, it sets errno and returns (size_t)(-1).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-iconv-close" role="function">
<title>g_mime_iconv_close ()</title>
<indexterm zone="g-mime-iconv-close"><primary>g_mime_iconv_close</primary></indexterm>
<programlisting><link linkend="int"><returnvalue>int</returnvalue></link>                 g_mime_iconv_close                  (<parameter><link linkend="iconv-t"><type>iconv_t</type></link> cd</parameter>);</programlisting>
<para>
Closes the iconv descriptor <parameter>cd</parameter>.
</para>
<para>
See the manual page for iconv_close(3) for further details.
</para><variablelist role="params">
<varlistentry><term><parameter>cd</parameter>&#160;:</term>
<listitem><simpara>iconv conversion descriptor
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="0:CAPS"><literal>0</literal></link> on success or <link linkend="1:CAPS"><literal>-1</literal></link> on fail as well as setting an
appropriate errno value.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>

</refentry>
