<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<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>

<refsect1 id="glib-Base64-Encoding.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-base64-encode-step">g_base64_encode_step</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-base64-encode-close">g_base64_encode_close</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-base64-encode">g_base64_encode</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-base64-decode-step">g_base64_decode_step</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guchar"><returnvalue>guchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-base64-decode">g_base64_decode</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guchar"><returnvalue>guchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-base64-decode-inplace">g_base64_decode_inplace</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Base64-Encoding.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
#include &lt;glib/gi18n.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Base64-Encoding.description" role="desc">
<title role="desc.title">Description</title>
<para>Base64 is an encoding that allows a sequence of arbitrary bytes to be
encoded 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.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-base64-encode-step" role="function" condition="since:2.12">
<title>g_base64_encode_step&#160;()</title>
<indexterm zone="g-base64-encode-step" role="2.12"><primary sortas="base64_encode_step">g_base64_encode_step</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_base64_encode_step (<parameter>const <link linkend="guchar"><type>guchar</type></link> *in</parameter>,
                      <parameter><link linkend="gsize"><type>gsize</type></link> len</parameter>,
                      <parameter><link linkend="gboolean"><type>gboolean</type></link> break_lines</parameter>,
                      <parameter><link linkend="gchar"><type>gchar</type></link> *out</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> *state</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> *save</parameter>);</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.
Note however that it breaks the lines with <literal>LF</literal> characters, not
<literal>CR LF</literal> sequences, so the result cannot be passed directly to SMTP
or certain other protocols.</para>
<refsect3 id="g-base64-encode-step.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>in</para></entry>
<entry role="parameter_description"><para>the binary data to encode. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=len][<acronym>element-type</acronym> guint8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the length of <parameter>in</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>break_lines</para></entry>
<entry role="parameter_description"><para>whether to break long lines</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>out</para></entry>
<entry role="parameter_description"><para>pointer to destination buffer. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>array</acronym>][<acronym>element-type</acronym> guint8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>state</para></entry>
<entry role="parameter_description"><para>Saved state between steps, initialize to 0. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>save</para></entry>
<entry role="parameter_description"><para>Saved state between steps, initialize to 0. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-base64-encode-step.returns" role="returns">
<title>Returns</title>
<para> The number of bytes of output that was written</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-base64-encode-close" role="function" condition="since:2.12">
<title>g_base64_encode_close&#160;()</title>
<indexterm zone="g-base64-encode-close" role="2.12"><primary sortas="base64_encode_close">g_base64_encode_close</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_base64_encode_close (<parameter><link linkend="gboolean"><type>gboolean</type></link> break_lines</parameter>,
                       <parameter><link linkend="gchar"><type>gchar</type></link> *out</parameter>,
                       <parameter><link linkend="gint"><type>gint</type></link> *state</parameter>,
                       <parameter><link linkend="gint"><type>gint</type></link> *save</parameter>);</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>The output buffer must be large enough to fit all the data that will
be written to it. It will need up to 4 bytes, or up to 5 bytes if
line-breaking is enabled.</para>
<para>The <parameter>out</parameter>
 array will not be automatically nul-terminated.</para>
<refsect3 id="g-base64-encode-close.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>break_lines</para></entry>
<entry role="parameter_description"><para>whether to break long lines</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>out</para></entry>
<entry role="parameter_description"><para>pointer to destination buffer. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>array</acronym>][<acronym>element-type</acronym> guint8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>state</para></entry>
<entry role="parameter_description"><para>Saved state from <link linkend="g-base64-encode-step"><function>g_base64_encode_step()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>save</para></entry>
<entry role="parameter_description"><para>Saved state from <link linkend="g-base64-encode-step"><function>g_base64_encode_step()</function></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-base64-encode-close.returns" role="returns">
<title>Returns</title>
<para> The number of bytes of output that was written</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-base64-encode" role="function" condition="since:2.12">
<title>g_base64_encode&#160;()</title>
<indexterm zone="g-base64-encode" role="2.12"><primary sortas="base64_encode">g_base64_encode</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_base64_encode (<parameter>const <link linkend="guchar"><type>guchar</type></link> *data</parameter>,
                 <parameter><link linkend="gsize"><type>gsize</type></link> len</parameter>);</programlisting>
<para>Encode a sequence of binary data into its Base-64 stringified
representation.</para>
<refsect3 id="g-base64-encode.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>the binary data to encode. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=len][<acronym>element-type</acronym> guint8][<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the length of <parameter>data</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-base64-encode.returns" role="returns">
<title>Returns</title>
<para>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>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-base64-decode-step" role="function" condition="since:2.12">
<title>g_base64_decode_step&#160;()</title>
<indexterm zone="g-base64-decode-step" role="2.12"><primary sortas="base64_decode_step">g_base64_decode_step</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_base64_decode_step (<parameter>const <link linkend="gchar"><type>gchar</type></link> *in</parameter>,
                      <parameter><link linkend="gsize"><type>gsize</type></link> len</parameter>,
                      <parameter><link linkend="guchar"><type>guchar</type></link> *out</parameter>,
                      <parameter><link linkend="gint"><type>gint</type></link> *state</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> *save</parameter>);</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><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-base64-decode-step.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>in</para></entry>
<entry role="parameter_description"><para>binary input data. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=len][<acronym>element-type</acronym> guint8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>max length of <parameter>in</parameter>
data to decode</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>out</para></entry>
<entry role="parameter_description"><para>output buffer. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out caller-allocates</acronym>][<acronym>array</acronym>][<acronym>element-type</acronym> guint8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>state</para></entry>
<entry role="parameter_description"><para>Saved state between steps, initialize to 0. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>save</para></entry>
<entry role="parameter_description"><para>Saved state between steps, initialize to 0. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-base64-decode-step.returns" role="returns">
<title>Returns</title>
<para> The number of bytes of output that was written</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-base64-decode" role="function" condition="since:2.12">
<title>g_base64_decode&#160;()</title>
<indexterm zone="g-base64-decode" role="2.12"><primary sortas="base64_decode">g_base64_decode</primary></indexterm>
<programlisting language="C"><link linkend="guchar"><returnvalue>guchar</returnvalue></link>&#160;*
g_base64_decode (<parameter>const <link linkend="gchar"><type>gchar</type></link> *text</parameter>,
                 <parameter><link linkend="gsize"><type>gsize</type></link> *out_len</parameter>);</programlisting>
<para>Decode a sequence of Base-64 encoded text into binary data.  Note
that the returned binary data is not necessarily zero-terminated,
so it should not be used as a character string.</para>
<refsect3 id="g-base64-decode.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>text</para></entry>
<entry role="parameter_description"><para>zero-terminated string with base64 text to decode. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>out_len</para></entry>
<entry role="parameter_description"><para>The length of the decoded data is written here. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-base64-decode.returns" role="returns">
<title>Returns</title>
<para>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>. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>array</acronym> length=out_len][<acronym>element-type</acronym> guint8]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.12">2.12</link></para></refsect2>
<refsect2 id="g-base64-decode-inplace" role="function" condition="since:2.20">
<title>g_base64_decode_inplace&#160;()</title>
<indexterm zone="g-base64-decode-inplace" role="2.20"><primary sortas="base64_decode_inplace">g_base64_decode_inplace</primary></indexterm>
<programlisting language="C"><link linkend="guchar"><returnvalue>guchar</returnvalue></link>&#160;*
g_base64_decode_inplace (<parameter><link linkend="gchar"><type>gchar</type></link> *text</parameter>,
                         <parameter><link linkend="gsize"><type>gsize</type></link> *out_len</parameter>);</programlisting>
<para>Decode a sequence of Base-64 encoded text into binary data
by overwriting the input data.</para>
<refsect3 id="g-base64-decode-inplace.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>text</para></entry>
<entry role="parameter_description"><para>zero-terminated
string with base64 text to decode. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>][<acronym>array</acronym> length=out_len][<acronym>element-type</acronym> guint8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>out_len</para></entry>
<entry role="parameter_description"><para>The length of the decoded data is written here. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>inout</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-base64-decode-inplace.returns" role="returns">
<title>Returns</title>
<para>The binary data that <parameter>text</parameter>
responds. This pointer
is the same as the input <parameter>text</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.20">2.20</link></para></refsect2>

</refsect1>

</refentry>
