docs/reference/html/gmime-gmime-iconv.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>gmime-iconv</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GMime 2.6 Reference Manual">
   8 <link rel="up" href="core.html" title="Part III. GMime Core Reference">
   9 <link rel="prev" href="gmime-gmime-charset.html" title="gmime-charset">
  10 <link rel="next" href="gmime-gmime-iconv-utils.html" title="gmime-iconv-utils">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="gmime-gmime-charset.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GMime 2.6 Reference Manual</th>
  21 <td><a accesskey="n" href="gmime-gmime-iconv-utils.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#gmime-gmime-iconv.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#gmime-gmime-iconv.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="gmime-gmime-iconv"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="gmime-gmime-iconv.top_of_page"></a>gmime-iconv</span></h2>
  34 <p>gmime-iconv — Low-level routines for converting text from one charset to another</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="gmime-gmime-iconv.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis"><span class="returnvalue">void</span>                <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-init" title="g_mime_iconv_init ()">g_mime_iconv_init</a>                   (<em class="parameter"><code><span class="type">void</span></code></em>);
  41 <span class="returnvalue">void</span>                <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-shutdown" title="g_mime_iconv_shutdown ()">g_mime_iconv_shutdown</a>               (<em class="parameter"><code><span class="type">void</span></code></em>);
  42 <span class="returnvalue">iconv_t</span>             <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-open" title="g_mime_iconv_open ()">g_mime_iconv_open</a>                   (<em class="parameter"><code>const <span class="type">char</span> *to</code></em>,
  43                                                          <em class="parameter"><code>const <span class="type">char</span> *from</code></em>);
  44 #define             <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()">g_mime_iconv</a>                        (cd,
  45                                                          inbuf,
  46                                                          inleft,
  47                                                          outbuf,
  48                                                          outleft)
  49 <span class="returnvalue">int</span>                 <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-close" title="g_mime_iconv_close ()">g_mime_iconv_close</a>                  (<em class="parameter"><code><span class="type">iconv_t</span> cd</code></em>);
  50 </pre>
  51 </div>
  52 <div class="refsect1">
  53 <a name="gmime-gmime-iconv.description"></a><h2>Description</h2>
  54 <p>
  55 These functions are wrappers around the system iconv(3)
  56 routines. The purpose of these wrappers are two-fold:
  57 </p>
  58 <p>
  59 1. Cache iconv_t descriptors for you in order to optimize
  60 opening/closing many descriptors frequently
  61 </p>
  62 <p>
  63 and
  64 </p>
  65 <p>
  66 2. To use the appropriate system charset alias for the MIME charset
  67 names given as arguments.
  68 </p>
  69 </div>
  70 <div class="refsect1">
  71 <a name="gmime-gmime-iconv.details"></a><h2>Details</h2>
  72 <div class="refsect2">
  73 <a name="g-mime-iconv-init"></a><h3>g_mime_iconv_init ()</h3>
  74 <pre class="programlisting"><span class="returnvalue">void</span>                g_mime_iconv_init                   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
  75 <p>
  76 Initialize GMime's iconv cache. This *MUST* be called before any
  77 gmime-iconv interfaces will work correctly.
  78 </p>
  79 <p>
  80 Note: this function is called for you by <a class="link" href="gmime-gmime.html#g-mime-init" title="g_mime_init ()"><code class="function">g_mime_init()</code></a>.
  81 </p>
  82 </div>
  83 <hr>
  84 <div class="refsect2">
  85 <a name="g-mime-iconv-shutdown"></a><h3>g_mime_iconv_shutdown ()</h3>
  86 <pre class="programlisting"><span class="returnvalue">void</span>                g_mime_iconv_shutdown               (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
  87 <p>
  88 Frees internal iconv caches created in <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-init" title="g_mime_iconv_init ()"><code class="function">g_mime_iconv_init()</code></a>.
  89 </p>
  90 <p>
  91 Note: this function is called for you by <a class="link" href="gmime-gmime.html#g-mime-shutdown" title="g_mime_shutdown ()"><code class="function">g_mime_shutdown()</code></a>.
  92 </p>
  93 </div>
  94 <hr>
  95 <div class="refsect2">
  96 <a name="g-mime-iconv-open"></a><h3>g_mime_iconv_open ()</h3>
  97 <pre class="programlisting"><span class="returnvalue">iconv_t</span>             g_mime_iconv_open                   (<em class="parameter"><code>const <span class="type">char</span> *to</code></em>,
  98                                                          <em class="parameter"><code>const <span class="type">char</span> *from</code></em>);</pre>
  99 <p>
 100 Allocates a coversion descriptor suitable for converting byte
 101 sequences from charset <em class="parameter"><code>from</code></em> to charset <em class="parameter"><code>to</code></em>. The resulting
 102 descriptor can be used with <code class="function">iconv()</code> (or the <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><code class="function">g_mime_iconv()</code></a> wrapper) any
 103 number of times until closed using <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-close" title="g_mime_iconv_close ()"><code class="function">g_mime_iconv_close()</code></a>.
 104 </p>
 105 <p>
 106 See the manual page for iconv_open(3) for further details.
 107 </p>
 108 <div class="variablelist"><table border="0">
 109 <col align="left" valign="top">
 110 <tbody>
 111 <tr>
 112 <td><p><span class="term"><em class="parameter"><code>to</code></em> :</span></p></td>
 113 <td>charset to convert to</td>
 114 </tr>
 115 <tr>
 116 <td><p><span class="term"><em class="parameter"><code>from</code></em> :</span></p></td>
 117 <td>charset to convert from</td>
 118 </tr>
 119 <tr>
 120 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 121 <td>a new conversion descriptor for use with <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><code class="function">g_mime_iconv()</code></a> on
 122 success or (iconv_t) <code class="literal">-1</code> on fail as well as setting an appropriate
 123 errno value.</td>
 124 </tr>
 125 </tbody>
 126 </table></div>
 127 </div>
 128 <hr>
 129 <div class="refsect2">
 130 <a name="g-mime-iconv"></a><h3>g_mime_iconv()</h3>
 131 <pre class="programlisting">#define             g_mime_iconv(cd,inbuf,inleft,outbuf,outleft)</pre>
 132 <p>
 133 The argument <em class="parameter"><code>cd</code></em> must be a conversion descriptor created using the
 134 function <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv-open" title="g_mime_iconv_open ()"><span class="type">g_mime_iconv_open</span></a>.
 135 </p>
 136 <p>
 137 The main case is when <em class="parameter"><code>inbuf</code></em> is not <code class="literal">NULL</code> and *inbuf is not
 138 <code class="literal">NULL</code>. In this case, the <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function converts the
 139 multibyte sequence starting at *inbuf to a multibyte sequence
 140 starting at *outbuf. At most *inleft bytes, starting at *inbuf,
 141 will be read. At most *outleft bytes, starting at *outbuf, will
 142 be written.
 143 </p>
 144 <p>
 145 The <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function converts one multibyte character at a
 146 time, and for each character conversion it increments *inbuf and
 147 decrements *inleft by the number of converted input bytes, it
 148 increments *outbuf and decrements *outleft by the number of
 149 converted output bytes, and it updates the conversion state
 150 contained in <em class="parameter"><code>cd</code></em>. The conversion can stop for four reasons:
 151 </p>
 152 <p>
 153 1. An invalid multibyte sequence is encountered in the input. In
 154 this case it sets errno to <code class="literal">EILSEQ</code> and returns (size_t)(-1).
 155 *inbuf is left pointing to the beginning of the invalid multibyte
 156 sequence.
 157 </p>
 158 <p>
 159 2. The input byte sequence has been entirely converted, i.e.
 160 *inleft has gone down to <code class="literal">0</code>. In this case <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> returns
 161 the number of non-reversible conversions performed during this
 162 call.
 163 </p>
 164 <p>
 165 3. An incomplete multibyte sequence is encountered in the input,
 166 and the input byte sequence terminates after it. In this case it
 167 sets errno to <code class="literal">EINVAL</code> and returns (size_t)(-1). *inbuf is left
 168 pointing to the beginning of the incomplete multibyte sequence.
 169 </p>
 170 <p>
 171 4. The output buffer has no more room for the next converted
 172 character. In this case it sets errno to <code class="literal">E2BIG</code> and returns
 173 (size_t)(-1).
 174 </p>
 175 <p>
 176 A different case is when <em class="parameter"><code>inbuf</code></em> is <code class="literal">NULL</code> or *inbuf is <code class="literal">NULL</code>, but
 177 <em class="parameter"><code>outbuf</code></em> is not <code class="literal">NULL</code> and *outbuf is not <code class="literal">NULL</code>. In this case, the
 178 <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function attempts to set <em class="parameter"><code>cd</code></em>'s conversion state to
 179 the initial state and store a corresponding shift sequence at
 180 *outbuf.  At most *outleft bytes, starting at *outbuf, will be
 181 written.  If the output buffer has no more room for this reset
 182 sequence, it sets errno to <code class="literal">E2BIG</code> and returns (size_t)(-1).
 183 Otherwise it increments *outbuf and decrements *outleft by the
 184 number of bytes written.
 185 </p>
 186 <p>
 187 A third case is when <em class="parameter"><code>inbuf</code></em> is <code class="literal">NULL</code> or *inbuf is <code class="literal">NULL</code>, and
 188 <em class="parameter"><code>outbuf</code></em> is <code class="literal">NULL</code> or *outbuf is <code class="literal">NULL</code>. In this case, the
 189 <a class="link" href="gmime-gmime-iconv.html#g-mime-iconv" title="g_mime_iconv()"><span class="type">g_mime_iconv</span></a> function sets <em class="parameter"><code>cd</code></em>'s conversion state to the initial
 190 state.
 191 </p>
 192 <div class="variablelist"><table border="0">
 193 <col align="left" valign="top">
 194 <tbody>
 195 <tr>
 196 <td><p><span class="term"><em class="parameter"><code>cd</code></em> :</span></p></td>
 197 <td>iconv_t conversion descriptor</td>
 198 </tr>
 199 <tr>
 200 <td><p><span class="term"><em class="parameter"><code>inbuf</code></em> :</span></p></td>
 201 <td>input buffer</td>
 202 </tr>
 203 <tr>
 204 <td><p><span class="term"><em class="parameter"><code>inleft</code></em> :</span></p></td>
 205 <td>number of bytes left in <em class="parameter"><code>inbuf</code></em>
 206 </td>
 207 </tr>
 208 <tr>
 209 <td><p><span class="term"><em class="parameter"><code>outbuf</code></em> :</span></p></td>
 210 <td>output buffer</td>
 211 </tr>
 212 <tr>
 213 <td><p><span class="term"><em class="parameter"><code>outleft</code></em> :</span></p></td>
 214 <td>number of bytes left in <em class="parameter"><code>outbuf</code></em>
 215 </td>
 216 </tr>
 217 <tr>
 218 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 219 <td>the number of characters converted in a nonreversible way
 220 during this call; reversible conversions are not counted. In case
 221 of error, it sets errno and returns (size_t)(-1).</td>
 222 </tr>
 223 </tbody>
 224 </table></div>
 225 </div>
 226 <hr>
 227 <div class="refsect2">
 228 <a name="g-mime-iconv-close"></a><h3>g_mime_iconv_close ()</h3>
 229 <pre class="programlisting"><span class="returnvalue">int</span>                 g_mime_iconv_close                  (<em class="parameter"><code><span class="type">iconv_t</span> cd</code></em>);</pre>
 230 <p>
 231 Closes the iconv descriptor <em class="parameter"><code>cd</code></em>.
 232 </p>
 233 <p>
 234 See the manual page for iconv_close(3) for further details.
 235 </p>
 236 <div class="variablelist"><table border="0">
 237 <col align="left" valign="top">
 238 <tbody>
 239 <tr>
 240 <td><p><span class="term"><em class="parameter"><code>cd</code></em> :</span></p></td>
 241 <td>iconv conversion descriptor</td>
 242 </tr>
 243 <tr>
 244 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 245 <td>
 246 <code class="literal">0</code> on success or <code class="literal">-1</code> on fail as well as setting an
 247 appropriate errno value.</td>
 248 </tr>
 249 </tbody>
 250 </table></div>
 251 </div>
 252 </div>
 253 </div>
 254 <div class="footer">
 255 <hr>
 256           Generated by GTK-Doc V1.18</div>
 257 </body>
 258 </html>