<refentry id="gmime-gmime-charset">
<refmeta>
<refentrytitle role="top_of_page" id="gmime-gmime-charset.top_of_page">gmime-charset</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  GMIME Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gmime-charset</refname>
<refpurpose>Charset helper functions</refpurpose>
</refnamediv>

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

<synopsis>                    <link linkend="GMimeCharset">GMimeCharset</link>;
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-charset-map-init">g_mime_charset_map_init</link>             (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-charset-map-shutdown">g_mime_charset_map_shutdown</link>         (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-locale-charset">g_mime_locale_charset</link>               (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-locale-language">g_mime_locale_language</link>              (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-language">g_mime_charset_language</link>             (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-canon-name">g_mime_charset_canon_name</link>           (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-iconv-name">g_mime_charset_iconv_name</link>           (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-name">g_mime_charset_name</link>                 (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-locale-name">g_mime_charset_locale_name</link>          (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-iso-to-windows">g_mime_charset_iso_to_windows</link>       (<parameter>const <link linkend="char"><type>char</type></link> *isocharset</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-charset-init">g_mime_charset_init</link>                 (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *charset</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-charset-step">g_mime_charset_step</link>                 (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *charset</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *inbuf</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> inlen</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-best-name">g_mime_charset_best_name</link>            (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *charset</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="g-mime-charset-best">g_mime_charset_best</link>                 (<parameter>const <link linkend="char"><type>char</type></link> *inbuf</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> inlen</parameter>);
<link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            <link linkend="g-mime-charset-can-encode">g_mime_charset_can_encode</link>           (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *mask</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> len</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="g-mime-set-user-charsets">g_mime_set_user_charsets</link>            (<parameter>const <link linkend="char"><type>char</type></link> **charsets</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> **       <link linkend="g-mime-user-charsets">g_mime_user_charsets</link>                (<parameter><type>void</type></parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="gmime-gmime-charset.description" role="desc">
<title role="desc.title">Description</title>
<para>
Charset utility functions.
</para>
</refsect1>
<refsect1 id="gmime-gmime-charset.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GMimeCharset" role="struct">
<title>GMimeCharset</title>
<indexterm zone="GMimeCharset"><primary>GMimeCharset</primary></indexterm>
<programlisting>typedef struct {
	unsigned int mask;
	unsigned int level;
} GMimeCharset;
</programlisting>
<para>
State used by <link linkend="g-mime-charset-best"><function>g_mime_charset_best()</function></link> and <link linkend="g-mime-charset-best-name"><function>g_mime_charset_best_name()</function></link>.
</para><variablelist role="struct">
<varlistentry><term>unsigned&#160;<link linkend="int"><type>int</type></link>&#160;<structfield id="GMimeCharset.mask">mask</structfield>;</term>
<listitem><simpara>charset mask
</simpara></listitem>
</varlistentry>
<varlistentry><term>unsigned&#160;<link linkend="int"><type>int</type></link>&#160;<structfield id="GMimeCharset.level">level</structfield>;</term>
<listitem><simpara>charset level
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-map-init" role="function">
<title>g_mime_charset_map_init ()</title>
<indexterm zone="g-mime-charset-map-init"><primary>g_mime_charset_map_init</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_charset_map_init             (<parameter><type>void</type></parameter>);</programlisting>
<para>
Initializes the locale charset variable for later calls to
<link linkend="g-mime-locale-charset"><function>g_mime_locale_charset()</function></link>. Only really needs to be called for non-
iso-8859-1 locales.
</para>
<para>
Note: <link linkend="g-mime-init"><function>g_mime_init()</function></link> calls this routine for you.
</para></refsect2>
<refsect2 id="g-mime-charset-map-shutdown" role="function">
<title>g_mime_charset_map_shutdown ()</title>
<indexterm zone="g-mime-charset-map-shutdown"><primary>g_mime_charset_map_shutdown</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_charset_map_shutdown         (<parameter><type>void</type></parameter>);</programlisting>
<para>
Frees internal lookup tables created in <link linkend="g-mime-charset-map-init"><function>g_mime_charset_map_init()</function></link>.
</para></refsect2>
<refsect2 id="g-mime-locale-charset" role="function">
<title>g_mime_locale_charset ()</title>
<indexterm zone="g-mime-locale-charset"><primary>g_mime_locale_charset</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_locale_charset               (<parameter><type>void</type></parameter>);</programlisting>
<para>
Gets the user's locale charset (or iso-8859-1 by default).
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user's locale charset (or iso-8859-1 by default).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-locale-language" role="function">
<title>g_mime_locale_language ()</title>
<indexterm zone="g-mime-locale-language"><primary>g_mime_locale_language</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_locale_language              (<parameter><type>void</type></parameter>);</programlisting>
<para>
Gets the user's locale language code (or <link linkend="NULL:CAPS"><literal>NULL</literal></link> by default).
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user's locale language code (or <link linkend="NULL:CAPS"><literal>NULL</literal></link> by default).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-language" role="function">
<title>g_mime_charset_language ()</title>
<indexterm zone="g-mime-charset-language"><primary>g_mime_charset_language</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_language             (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);</programlisting>
<para>
Attempts to find a specific language code that is specific to
<parameter>charset</parameter>. Currently only handles CJK and Russian/Ukranian
charset->lang mapping. Everything else will return <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a language code that is specific to <parameter>charset</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> on
fail.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-canon-name" role="function">
<title>g_mime_charset_canon_name ()</title>
<indexterm zone="g-mime-charset-canon-name"><primary>g_mime_charset_canon_name</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_canon_name           (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);</programlisting>
<para>
Attempts to find a canonical charset name for <parameter>charset</parameter>.
</para>
<para>
Note: Will normally return the same value as
<link linkend="g-mime-charset-iconv-name"><function>g_mime_charset_iconv_name()</function></link> unless the system iconv does not use
the canonical ISO charset names (such as using ISO8859-1 rather
than the canonical form ISO-8859-1).
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a canonical charset name for <parameter>charset</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-iconv-name" role="function">
<title>g_mime_charset_iconv_name ()</title>
<indexterm zone="g-mime-charset-iconv-name"><primary>g_mime_charset_iconv_name</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_iconv_name           (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);</programlisting>
<para>
Attempts to find an iconv-friendly charset name for <parameter>charset</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> an iconv-friendly charset name for <parameter>charset</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-name" role="function" condition="deprecated:">
<title>g_mime_charset_name ()</title>
<indexterm zone="g-mime-charset-name" role="deprecated"><primary>g_mime_charset_name</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_name                 (<parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>);</programlisting>
<warning><para><literal>g_mime_charset_name</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Attempts to find an iconv-friendly charset name for <parameter>charset</parameter>.
</para>
<para>
Note: This function is deprecated. Use <link linkend="g-mime-charset-iconv-name"><function>g_mime_charset_iconv_name()</function></link>
instead.
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset name
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> an iconv-friendly charset name for <parameter>charset</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-locale-name" role="function" condition="deprecated:">
<title>g_mime_charset_locale_name ()</title>
<indexterm zone="g-mime-charset-locale-name" role="deprecated"><primary>g_mime_charset_locale_name</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_locale_name          (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>g_mime_charset_locale_name</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Gets the user's locale charset (or iso-8859-1 by default).
</para>
<para>
Note: This function is deprecated. Use <link linkend="g-mime-locale-charset"><function>g_mime_locale_charset()</function></link>
instead.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user's locale charset (or iso-8859-1 by default).
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-iso-to-windows" role="function">
<title>g_mime_charset_iso_to_windows ()</title>
<indexterm zone="g-mime-charset-iso-to-windows"><primary>g_mime_charset_iso_to_windows</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_iso_to_windows       (<parameter>const <link linkend="char"><type>char</type></link> *isocharset</parameter>);</programlisting>
<para>
Maps the ISO-8859-# charset to the equivalent Windows-CP125#
charset.
</para><variablelist role="params">
<varlistentry><term><parameter>isocharset</parameter>&#160;:</term>
<listitem><simpara>ISO-8859-# charset
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> equivalent Windows charset.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-init" role="function">
<title>g_mime_charset_init ()</title>
<indexterm zone="g-mime-charset-init"><primary>g_mime_charset_init</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_charset_init                 (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *charset</parameter>);</programlisting>
<para>
Initializes a charset mask structure.
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset mask
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-step" role="function">
<title>g_mime_charset_step ()</title>
<indexterm zone="g-mime-charset-step"><primary>g_mime_charset_step</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_charset_step                 (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *charset</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *inbuf</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> inlen</parameter>);</programlisting>
<para>
Steps through the input buffer 1 unicode character (glyph) at a
time (ie, not necessarily 1 byte at a time). Bitwise 'and' our
<parameter>charset->mask</parameter> with the mask for each glyph. This has the effect of
limiting what charsets our <parameter>charset->mask</parameter> can match.
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset structure
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>inbuf</parameter>&#160;:</term>
<listitem><simpara>input text buffer (must be in UTF-8)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>inlen</parameter>&#160;:</term>
<listitem><simpara>input buffer length
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-best-name" role="function">
<title>g_mime_charset_best_name ()</title>
<indexterm zone="g-mime-charset-best-name"><primary>g_mime_charset_best_name</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_best_name            (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *charset</parameter>);</programlisting>
<para>
Gets the best charset name based on the charset mask <parameter>charset</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>charset mask
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a pointer to a string containing the best charset name that
can represent the charset mask <parameter>charset</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-best" role="function">
<title>g_mime_charset_best ()</title>
<indexterm zone="g-mime-charset-best"><primary>g_mime_charset_best</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        g_mime_charset_best                 (<parameter>const <link linkend="char"><type>char</type></link> *inbuf</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> inlen</parameter>);</programlisting>
<para>
Computes the best charset to use to encode this text buffer.
</para><variablelist role="params">
<varlistentry><term><parameter>inbuf</parameter>&#160;:</term>
<listitem><simpara>a UTF-8 text buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>inlen</parameter>&#160;:</term>
<listitem><simpara>input buffer length
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the charset name best suited for the input text or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
it is US-ASCII safe.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-charset-can-encode" role="function">
<title>g_mime_charset_can_encode ()</title>
<indexterm zone="g-mime-charset-can-encode"><primary>g_mime_charset_can_encode</primary></indexterm>
<programlisting><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            g_mime_charset_can_encode           (<parameter><link linkend="GMimeCharset"><type>GMimeCharset</type></link> *mask</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *charset</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *text</parameter>,
                                                         <parameter><link linkend="size-t"><type>size_t</type></link> len</parameter>);</programlisting>
<para>
Check to see if the UTF-8 <parameter>text</parameter> will fit safely within <parameter>charset</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>mask</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GMimeCharset"><type>GMimeCharset</type></link> mask
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>charset</parameter>&#160;:</term>
<listitem><simpara>a charset
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara>utf-8 text to check
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara>length of <parameter>text</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if it is safe to encode <parameter>text</parameter> into <parameter>charset</parameter> or <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>
otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-set-user-charsets" role="function">
<title>g_mime_set_user_charsets ()</title>
<indexterm zone="g-mime-set-user-charsets"><primary>g_mime_set_user_charsets</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                g_mime_set_user_charsets            (<parameter>const <link linkend="char"><type>char</type></link> **charsets</parameter>);</programlisting>
<para>
Set a list of charsets for GMime to use as a hint for encoding and
decoding headers. The charset list should be in order of preference
(e.g. most preferred first, least preferred last).
</para><variablelist role="params">
<varlistentry><term><parameter>charsets</parameter>&#160;:</term>
<listitem><simpara>an array of user-preferred charsets
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-mime-user-charsets" role="function">
<title>g_mime_user_charsets ()</title>
<indexterm zone="g-mime-user-charsets"><primary>g_mime_user_charsets</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> **       g_mime_user_charsets                (<parameter><type>void</type></parameter>);</programlisting>
<para>
Get the list of user-preferred charsets set with
<link linkend="g-mime-set-user-charsets"><function>g_mime_set_user_charsets()</function></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> an array of user-set charsets or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if none set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>

</refentry>
