Base64 Encoding: GLib Reference Manual

Base64 Encoding

Base64 Encoding — encodes and decodes data in Base64 format

Functions

gsize	g_base64_encode_step ()
gsize	g_base64_encode_close ()
gchar *	g_base64_encode ()
gsize	g_base64_decode_step ()
guchar *	g_base64_decode ()
guchar *	g_base64_decode_inplace ()

Includes

#include <glib.h>
#include <glib/gi18n.h>

Description

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 RFC 1421 or RFC 2045. Base64 is most commonly used as a MIME transfer encoding for email.

GLib supports incremental encoding using g_base64_encode_step() and g_base64_encode_close(). Incremental decoding can be done with g_base64_decode_step(). To encode or decode data in one go, use g_base64_encode() or g_base64_decode(). To avoid memory allocation when decoding, you can use g_base64_decode_inplace().

Support for Base64 encoding has been added in GLib 2.12.

Functions

g_base64_encode_step ()

gsize
g_base64_encode_step (const guchar *in,
                      gsize len,
                      gboolean break_lines,
                      gchar *out,
                      gint *state,
                      gint *save);

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.

When all of the data has been converted you must call g_base64_encode_close() to flush the saved state.

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: (len / 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: ((len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.

break_lines is typically used when putting base64-encoded data in emails. It breaks the lines at 76 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 LF characters, not CR LF sequences, so the result cannot be passed directly to SMTP or certain other protocols.

Parameters

in	the binary data to encode.	[array length=len][element-type guint8]
len	the length of `in`
break_lines	whether to break long lines
out	pointer to destination buffer.	[out][array][element-type guint8]
state	Saved state between steps, initialize to 0.	[inout]
save	Saved state between steps, initialize to 0.	[inout]

Returns

The number of bytes of output that was written

Since: 2.12

g_base64_encode_close ()

gsize
g_base64_encode_close (gboolean break_lines,
                       gchar *out,
                       gint *state,
                       gint *save);

Flush the status from a sequence of calls to g_base64_encode_step().

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.

The out array will not be automatically nul-terminated.

Parameters

break_lines	whether to break long lines
out	pointer to destination buffer.	[out][array][element-type guint8]
state	Saved state from `g_base64_encode_step()`.	[inout]
save	Saved state from `g_base64_encode_step()`.	[inout]

Returns

The number of bytes of output that was written

Since: 2.12

g_base64_encode ()

gchar *
g_base64_encode (const guchar *data,
                 gsize len);

Encode a sequence of binary data into its Base-64 stringified representation.

Parameters

data	the binary data to encode.	[array length=len][element-type guint8][nullable]
len	the length of `data`

Returns

a newly allocated, zero-terminated Base-64 encoded string representing data . The returned string must be freed with g_free().

[transfer full]

Since: 2.12

g_base64_decode_step ()

gsize
g_base64_decode_step (const gchar *in,
                      gsize len,
                      guchar *out,
                      gint *state,
                      guint *save);

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.

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: (len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero state).

[skip]

Parameters

in	binary input data.	[array length=len][element-type guint8]
len	max length of `in` data to decode
out	output buffer.	[out caller-allocates][array][element-type guint8]
state	Saved state between steps, initialize to 0.	[inout]
save	Saved state between steps, initialize to 0.	[inout]

Returns

The number of bytes of output that was written

Since: 2.12

g_base64_decode ()

guchar *
g_base64_decode (const gchar *text,
                 gsize *out_len);

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.

Parameters

text	zero-terminated string with base64 text to decode.	[not nullable]
out_len	The length of the decoded data is written here.	[out]

Returns

newly allocated buffer containing the binary data that text represents. The returned buffer must be freed with g_free().

[transfer full][array length=out_len][element-type guint8]

Since: 2.12

g_base64_decode_inplace ()

guchar *
g_base64_decode_inplace (gchar *text,
                         gsize *out_len);

Decode a sequence of Base-64 encoded text into binary data by overwriting the input data.

Parameters

text	zero-terminated string with base64 text to decode.	[inout][array length=out_len][element-type guint8]
out_len	The length of the decoded data is written here.	[inout]

Returns

The binary data that text responds. This pointer is the same as the input text .

[transfer none]

Since: 2.20