<refentry id="glib-Base64-Encoding">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Base64-Encoding.top_of_page">Base64 Encoding</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Base64 Encoding</refname>
<refpurpose>encodes and decodes data in Base64 format</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Base64-Encoding.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

<link linkend="gsize">gsize</link>               <link linkend="g-base64-encode-step">g_base64_encode_step</link>                (const <link linkend="guchar">guchar</link> *in,
                                                         <link linkend="gsize">gsize</link> len,
                                                         <link linkend="gboolean">gboolean</link> break_lines,
                                                         <link linkend="gchar">gchar</link> *out,
                                                         <link linkend="gint">gint</link> *state,
                                                         <link linkend="gint">gint</link> *save);
<link linkend="gsize">gsize</link>               <link linkend="g-base64-encode-close">g_base64_encode_close</link>               (<link linkend="gboolean">gboolean</link> break_lines,
                                                         <link linkend="gchar">gchar</link> *out,
                                                         <link linkend="gint">gint</link> *state,
                                                         <link linkend="gint">gint</link> *save);
<link linkend="gchar">gchar</link>*              <link linkend="g-base64-encode">g_base64_encode</link>                     (const <link linkend="guchar">guchar</link> *data,
                                                         <link linkend="gsize">gsize</link> len);
<link linkend="gsize">gsize</link>               <link linkend="g-base64-decode-step">g_base64_decode_step</link>                (const <link linkend="gchar">gchar</link> *in,
                                                         <link linkend="gsize">gsize</link> len,
                                                         <link linkend="guchar">guchar</link> *out,
                                                         <link linkend="gint">gint</link> *state,
                                                         <link linkend="guint">guint</link> *save);
<link linkend="guchar">guchar</link> *            <link linkend="g-base64-decode">g_base64_decode</link>                     (const <link linkend="gchar">gchar</link> *text,
                                                         <link linkend="gsize">gsize</link> *out_len);
<link linkend="guchar">guchar</link> *            <link linkend="g-base64-decode-inplace">g_base64_decode_inplace</link>             (<link linkend="gchar">gchar</link> *text,
                                                         <link linkend="gsize">gsize</link> *out_len);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Base64-Encoding.description" role="desc">
<title role="desc.title">Description</title>
<para>
Base64 is an encoding that allows to encode a sequence of arbitrary
bytes as a sequence of printable ASCII characters. For the definition
of Base64, see <ulink url="http://www.ietf.org/rfc/rfc1421.txt">RFC
1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt">RFC
2045</ulink>. Base64 is most commonly used as a MIME transfer encoding
for email.
</para>
<para>
GLib supports incremental encoding using <link linkend="g-base64-encode-step"><function>g_base64_encode_step()</function></link> and
<link linkend="g-base64-encode-close"><function>g_base64_encode_close()</function></link>. Incremental decoding can be done with
<link linkend="g-base64-decode-step"><function>g_base64_decode_step()</function></link>. To encode or decode data in one go, use
<link linkend="g-base64-encode"><function>g_base64_encode()</function></link> or <link linkend="g-base64-decode"><function>g_base64_decode()</function></link>. To avoid memory allocation when
decoding, you can use <link linkend="g-base64-decode-inplace"><function>g_base64_decode_inplace()</function></link>.
</para>
<para>
Support for Base64 encoding has been added in GLib 2.12.
</para>
</refsect1>

<refsect1 id="glib-Base64-Encoding.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-base64-encode-step" role="function" condition="since:2.12">
<title>g_base64_encode_step ()</title>
<indexterm zone="g-base64-encode-step" role="2.12"><primary sortas="base64_encode_step">g_base64_encode_step</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_base64_encode_step                (const <link linkend="guchar">guchar</link> *in,
                                                         <link linkend="gsize">gsize</link> len,
                                                         <link linkend="gboolean">gboolean</link> break_lines,
                                                         <link linkend="gchar">gchar</link> *out,
                                                         <link linkend="gint">gint</link> *state,
                                                         <link linkend="gint">gint</link> *save);</programlisting>
<para>
Incrementally encode a sequence of binary data into its Base-64 stringified
representation. By calling this function multiple times you can convert 
data in chunks to avoid having to have the full encoded data in memory.
</para>
<para>
When all of the data has been converted you must call 
<link linkend="g-base64-encode-close"><function>g_base64_encode_close()</function></link> to flush the saved state.
</para>
<para>
The output buffer must be large enough to fit all the data that will
be written to it. Due to the way base64 encodes you will need
at least: (<parameter>len</parameter> / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
non-zero state). If you enable line-breaking you will need at least:
((<parameter>len</parameter> / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space.
</para>
<para>
<parameter>break_lines</parameter> is typically used when putting base64-encoded data in emails.
It breaks the lines at 72 columns instead of putting all of the text on 
the same line. This avoids problems with long lines in the email system.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>in</parameter>&#160;:</term>
<listitem><simpara> the binary data to encode
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara> the length of <parameter>in</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>break_lines</parameter>&#160;:</term>
<listitem><simpara> whether to break long lines
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out</parameter>&#160;:</term>
<listitem><simpara> pointer to destination buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>state</parameter>&#160;:</term>
<listitem><simpara> Saved state between steps, initialize to 0
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>save</parameter>&#160;:</term>
<listitem><simpara> Saved state between steps, initialize to 0
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The number of bytes of output that was written

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-base64-encode-close" role="function" condition="since:2.12">
<title>g_base64_encode_close ()</title>
<indexterm zone="g-base64-encode-close" role="2.12"><primary sortas="base64_encode_close">g_base64_encode_close</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_base64_encode_close               (<link linkend="gboolean">gboolean</link> break_lines,
                                                         <link linkend="gchar">gchar</link> *out,
                                                         <link linkend="gint">gint</link> *state,
                                                         <link linkend="gint">gint</link> *save);</programlisting>
<para>
Flush the status from a sequence of calls to <link linkend="g-base64-encode-step"><function>g_base64_encode_step()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>break_lines</parameter>&#160;:</term>
<listitem><simpara> whether to break long lines
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out</parameter>&#160;:</term>
<listitem><simpara> pointer to destination buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>state</parameter>&#160;:</term>
<listitem><simpara> Saved state from <link linkend="g-base64-encode-step"><function>g_base64_encode_step()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>save</parameter>&#160;:</term>
<listitem><simpara> Saved state from <link linkend="g-base64-encode-step"><function>g_base64_encode_step()</function></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The number of bytes of output that was written

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-base64-encode" role="function" condition="since:2.12">
<title>g_base64_encode ()</title>
<indexterm zone="g-base64-encode" role="2.12"><primary sortas="base64_encode">g_base64_encode</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_base64_encode                     (const <link linkend="guchar">guchar</link> *data,
                                                         <link linkend="gsize">gsize</link> len);</programlisting>
<para>
Encode a sequence of binary data into its Base-64 stringified
representation.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the binary data to encode
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara> the length of <parameter>data</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated, zero-terminated Base-64 encoded
              string representing <parameter>data</parameter>. The returned string must 
              be freed with <link linkend="g-free"><function>g_free()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-base64-decode-step" role="function" condition="since:2.12">
<title>g_base64_decode_step ()</title>
<indexterm zone="g-base64-decode-step" role="2.12"><primary sortas="base64_decode_step">g_base64_decode_step</primary></indexterm><programlisting><link linkend="gsize">gsize</link>               g_base64_decode_step                (const <link linkend="gchar">gchar</link> *in,
                                                         <link linkend="gsize">gsize</link> len,
                                                         <link linkend="guchar">guchar</link> *out,
                                                         <link linkend="gint">gint</link> *state,
                                                         <link linkend="guint">guint</link> *save);</programlisting>
<para>
Incrementally decode a sequence of binary data from its Base-64 stringified
representation. By calling this function multiple times you can convert 
data in chunks to avoid having to have the full encoded data in memory.
</para>
<para>
The output buffer must be large enough to fit all the data that will
be written to it. Since base64 encodes 3 bytes in 4 chars you need
at least: (<parameter>len</parameter> / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
state).</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>in</parameter>&#160;:</term>
<listitem><simpara> binary input data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara> max length of <parameter>in</parameter> data to decode
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out</parameter>&#160;:</term>
<listitem><simpara> output buffer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>state</parameter>&#160;:</term>
<listitem><simpara> Saved state between steps, initialize to 0
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>save</parameter>&#160;:</term>
<listitem><simpara> Saved state between steps, initialize to 0
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The number of bytes of output that was written

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-base64-decode" role="function" condition="since:2.12">
<title>g_base64_decode ()</title>
<indexterm zone="g-base64-decode" role="2.12"><primary sortas="base64_decode">g_base64_decode</primary></indexterm><programlisting><link linkend="guchar">guchar</link> *            g_base64_decode                     (const <link linkend="gchar">gchar</link> *text,
                                                         <link linkend="gsize">gsize</link> *out_len);</programlisting>
<para>
Decode a sequence of Base-64 encoded text into binary data</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara> zero-terminated string with base64 text to decode
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out_len</parameter>&#160;:</term>
<listitem><simpara> The length of the decoded data is written here
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated buffer containing the binary data
              that <parameter>text</parameter> represents. The returned buffer must
              be freed with <link linkend="g-free"><function>g_free()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.12</para></refsect2>
<refsect2 id="g-base64-decode-inplace" role="function" condition="since:2.20">
<title>g_base64_decode_inplace ()</title>
<indexterm zone="g-base64-decode-inplace" role="2.20"><primary sortas="base64_decode_inplace">g_base64_decode_inplace</primary></indexterm><programlisting><link linkend="guchar">guchar</link> *            g_base64_decode_inplace             (<link linkend="gchar">gchar</link> *text,
                                                         <link linkend="gsize">gsize</link> *out_len);</programlisting>
<para>
Decode a sequence of Base-64 encoded text into binary data
by overwriting the input data.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>text</parameter>&#160;:</term>
<listitem><simpara> zero-terminated string with base64 text to decode
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out_len</parameter>&#160;:</term>
<listitem><simpara> The length of the decoded data is written here
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The binary data that <parameter>text</parameter> responds. This pointer
              is the same as the input <parameter>text</parameter>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.20</para></refsect2>

</refsect1>




</refentry>
