NAME
Base64 —
A simple base64 encoder/decoder with
unpadded base64 support.
SYNOPSIS
#include
<Base64.h>
size_t
Base64EncodedSize(size_t);
size_t
Base64DecodedSize(const
char *,
size_t);
char *
Base64Encode(const
char *,
size_t);
char *
Base64Decode(const
char *,
size_t);
void
Base64Unpad(char
*, size_t);
int
Base64Pad(char
**, size_t);
DESCRIPTION
This is an efficient yet simple base64 encoding and decoding
library that supports regular base64, as well as the Matrix specification's
extension to base64, called "unpadded base64."
provides the ability to convert between the two, instead
of just implementing "unpadded base64."
Base64EncodedSize()
and
Base64DecodedSize()
compute the amount of characters needed to store an encoded or decoded
message, respectively. Both functions take the size of the message being
encoded or decoded, but Base64DecodedSize() also
takes a pointer to an encoded string, because a few bytes of the string need
to be read in order to compute the size.
Base64Encode()
and
Base64Decode()
do the actual work of encoding and decoding base64 data. They both take a
string and its length.
Base64Unpad()
and
Base64Pad()
are used to implement Matrix unpadded base64.
Base64Unpad() takes a valid base64 string and strips
off the trailing equal signs, as per the specification.
Base64Pad() does the opposite; it takes an unpadded
base64 input string, and pads it with equal signs as necessary, so that it
can be properly decoded with Base64Decode() if
necessary. However, the Matrix specification envisons unpadded base64 as
opaque; that is, once it's encoded, it never needs to be decoded. In
practice, a homeserver might need to decode an unpadded base64 string.
RETURN VALUES
Base64EncodedSize() and
Base64DecodedSize() simply return unsigned integers
representing a number of bytes generated from a simple computation.
Base64Encode() and
Base64Decode() return pointers to new strings,
allocated on the heap, or NULL if a heap allocation
fails. These pointers must be
free(3) -ed at some point when they are no longer needed.
Base64Unpad() modifies the passed string
in-place. It thus has no return value, because it cannot fail. If the passed
pointer is invalid, the behavior is undefined.
Base64Pad() returns a boolean value indicating
whether the pad operation was successful. In practice, this function will
only fail if a bigger string is necessary, but could not be automatically
allocated on the heap.