Top |
Description
These functions are wrappers around the system iconv(3) routines. The purpose of this wrapper is to use the appropriate system charset alias for the MIME charset names given as arguments.
Functions
g_mime_iconv_open ()
iconv_t g_mime_iconv_open (const char *to
,const char *from
);
Allocates a coversion descriptor suitable for converting byte
sequences from charset from
to charset to
. The resulting
descriptor can be used with iconv()
(or the g_mime_iconv()
wrapper) any
number of times until closed using g_mime_iconv_close()
.
See the manual page for iconv_open(3) for further details.
[skip]
Returns
a new conversion descriptor for use with g_mime_iconv()
on
success or (iconv_t) -1
on fail as well as setting an appropriate
errno value.
g_mime_iconv()
#define g_mime_iconv(cd,inbuf,inleft,outbuf,outleft)
The argument cd
must be a conversion descriptor created using the
function g_mime_iconv_open.
The main case is when inbuf
is not NULL
and *inbuf is not
NULL
. In this case, the g_mime_iconv 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.
The g_mime_iconv 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 cd
. The conversion can stop for four reasons:
An invalid multibyte sequence is encountered in the input. In this case it sets errno to
EILSEQ
and returns (size_t)(-1). *inbuf is left pointing to the beginning of the invalid multibyte sequence.The input byte sequence has been entirely converted, i.e. *inleft has gone down to
0
. In this case g_mime_iconv returns the number of non-reversible conversions performed during this call.An incomplete multibyte sequence is encountered in the input, and the input byte sequence terminates after it. In this case it sets errno to
EINVAL
and returns (size_t)(-1). *inbuf is left pointing to the beginning of the incomplete multibyte sequence.The output buffer has no more room for the next converted character. In this case it sets errno to
E2BIG
and returns (size_t)(-1).
A different case is when inbuf
is NULL
or *inbuf is NULL
, but
outbuf
is not NULL
and *outbuf is not NULL
. In this case, the
g_mime_iconv function attempts to set cd
'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 E2BIG
and returns (size_t)(-1).
Otherwise it increments *outbuf and decrements *outleft by the
number of bytes written.
A third case is when inbuf
is NULL
or *inbuf is NULL
, and
outbuf
is NULL
or *outbuf is NULL
. In this case, the
g_mime_iconv function sets cd
's conversion state to the initial
state.
g_mime_iconv_close ()
int
g_mime_iconv_close (iconv_t cd
);
Closes the iconv descriptor cd
.
See the manual page for iconv_close(3) for further details.
[skip]