This header file contains the b64 C++-API types and functions. There are no associated implementation files; in other words, the b64 C++-API is header only.

The b64/C++ is dependent on several components from the STLSoft libraries (also 100% header-only) so you will need to have them available on your include path when using this header.

#include <b64/b64.h>
#include <stlsoft/stlsoft.h>
#include <stlsoft/memory/auto_buffer.hpp>
#include <stlsoft/shims/access/string.hpp>
#include <stdexcept>


Namespaces
namespace	cpp
Classes
class	coding_exception
	Exception thrown during encoding/decoding. More...
Typedefs
typedef std::string	string_t
	The string type for the b64 namespace.
typedef std::vector < ::stlsoft::byte_t >	blob_t
	The blob type for the b64 namespace.
Functions
string_t	encode (void const src, size_t srcSize, unsigned flags, int lineLen=0, B64_RC rc=NULL)
	Encodes the given block of memory into base-64.
string_t	encode (void const *src, size_t srcSize)
	Encodes the given block of memory into base-64.
template<typename T, size_t N>
string_t	encode (T(&ar)[N])
	Encodes the given array into base-64.
string_t	encode (blob_t const &blob)
	Encodes the given blob into base-64.
string_t	encode (blob_t const &blob, unsigned flags, int lineLen=0, B64_RC *rc=NULL)
	Encodes the given blob into base-64.
blob_t	decode (char const src, size_t srcLen, unsigned flags, char const badChar=NULL, B64_RC rc=NULL)
	Decodes the given base-64 block into binary.
blob_t	decode (char const *src, size_t srcLen)
	Decodes the given base-64 block into binary.
template<class S>
blob_t	decode (S const &str)
	Function template that decodes an instance of an arbitrary string type from base-64 into binary.
blob_t	decode (string_t const &str, unsigned flags=0)
	Decodes the given string from base-64 into binary.
blob_t	decode (string_t const &str, unsigned flags, char const *badChar, B64_RC rc=NULL)
	Decodes the given string from base-64 into binary.

Typedef Documentation

typedef std::vector< ::stlsoft::byte_t> blob_t

The blob type for the b64 namespace.

Note:: This defaults to std::vector< ::stlsoft::byte_t>. It is possible to override this, using preprocessor symbol definitions. To do this, you must define the symbol B64_USE_CUSTOM_VECTOR to instruct the compiler that the b64 library is to use a custom string type. In that case you must also define the B64_CUSTOM_VECTOR_INCLUDE and B64_CUSTOM_BLOB_TYPE and symbols.

B64_CUSTOM_VECTOR_INCLUDE specifies the <> or "" surrounded include file name, e.g.

#define B64_CUSTOM_VECTOR_INCLUDE <stlsoft/pod_vector.hpp>

B64_CUSTOM_BLOB_TYPE specifies the string type, e.g.

#define B64_CUSTOM_BLOB_TYPE stlsoft::pod_vector<unsigned char>

Note:: For Open Watcom compilation, this type is actually the class class b64::watcom_vector_for_b64, a class adaptor for the WCValVector<unsigned char> specialisation. The definition of this class can be found in b64/b64.hpp.

Examples:: example.cpp.1.cpp, and example.cpp.2.cpp.

typedef std::string string_t

The string type for the b64 namespace.

Note:: This defaults to std::string. It is possible to override this, using preprocessor symbol definitions. To do this, you must define the symbol B64_USE_CUSTOM_STRING to instruct the compiler that the b64 library is to use a custom string type. In that case you must also define the B64_CUSTOM_STRING_INCLUDE and B64_CUSTOM_STRING_TYPE and symbols.

B64_CUSTOM_STRING_INCLUDE specifies the <> or "" surrounded include file name, e.g.

#define B64_CUSTOM_STRING_INCLUDE <stlsoft/simple_string.hpp>

B64_CUSTOM_STRING_TYPE specifies the string type, e.g.

#define B64_CUSTOM_STRING_TYPE stlsoft::basic_simple_string<char>

Note:: For Open Watcom compilation, this type is actually the class class b64::watcom_string_for_b64, a class adaptor for the Open Watcom String class. The definition of this class can be found in b64/b64.hpp.

Examples:: example.cpp.1.cpp, and example.cpp.2.cpp.

Function Documentation

blob_t decode	(	string_t const &	str,
		unsigned	flags,
		char const **	badChar,
		B64_RC *	rc = `NULL`
	)			`[inline]`

Decodes the given string from base-64 into binary.

Parameters:

	str	The string whose contents are to be decoded
	flags	A combination of the B64_FLAGS enumeration, that moderate the behaviour of the function.
	rc	The return code representing the status of the operation. May be NULL.
	badChar	If the flags parameter does not contain B64_F_STOP_ON_NOTHING, this parameter specifies the address of a pointer that will be set to point to the character in the sequence that stops the parsing, as dictated by the flags parameter. May be NULL.

Returns:: The binary form of the block, as a blob_t

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

	std::bad_alloc	If insufficient memory is available to complete the operation
	b64::coding_exception	If a bad character is encountered in the encoded block (as moderated by the flags parameter; see B64_FLAGS)

blob_t decode	(	string_t const &	str,
		unsigned	flags = `0`
	)			`[inline]`

Decodes the given string from base-64 into binary.

Parameters:

	str	The string whose contents are to be decoded
	flags	A combination of the B64_FLAGS enumeration, that moderate the behaviour of the function.

Returns:: The binary form of the block, as a blob_t

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

	std::bad_alloc	If insufficient memory is available to complete the operation
	b64::coding_exception	If a bad character is encountered in the encoded block (as moderated by the flags parameter; see B64_FLAGS)

blob_t decode ( S const & str ) [inline]

Function template that decodes an instance of an arbitrary string type from base-64 into binary.

Parameters:

str

The string whose contents are to be decoded

Returns:: The binary form of the block, as a blob_t

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

blob_t decode	(	char const *	src,
		size_t	srcLen
	)			`[inline]`

Decodes the given base-64 block into binary.

Parameters:

	src	Pointer to the block to be decoded
	srcLen	Number of characters in the block to be decoded

Returns:: The binary form of the block, as a blob_t

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

blob_t decode	(	char const *	src,
		size_t	srcLen,
		unsigned	flags,
		char const **	badChar = `NULL`,
		B64_RC *	rc = `NULL`
	)			`[inline]`

Decodes the given base-64 block into binary.

Parameters:

	src	Pointer to the block to be decoded
	srcLen	Number of characters in the block to be decoded
	flags	A combination of the B64_FLAGS enumeration, that moderate the behaviour of the function.
	rc	The return code representing the status of the operation. May be NULL.
	badChar	If the flags parameter does not contain B64_F_STOP_ON_NOTHING, this parameter specifies the address of a pointer that will be set to point to the character in the sequence that stops the parsing, as dictated by the flags parameter. May be NULL.

Returns:: The binary form of the block, as a blob_t

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

	std::bad_alloc	If insufficient memory is available to complete the operation
	b64::coding_exception	If a bad character is encountered in the encoded block (as moderated by the flags parameter; see B64_FLAGS)

Examples:: example.cpp.1.cpp, and example.cpp.2.cpp.

string_t encode	(	blob_t const &	blob,
		unsigned	flags,
		int	lineLen = `0`,
		B64_RC *	rc = `NULL`
	)			`[inline]`

Encodes the given blob into base-64.

Parameters:

	blob	The blob whose contents are to be encoded
	flags	A combination of the B64_FLAGS enumeration, that moderate the behaviour of the function
	lineLen	If the flags parameter contains B64_F_LINE_LEN_USE_PARAM, then this parameter represents the length of the lines into which the encoded form is split, with a hard line break ('\r\n'). If this value is 0, then the line is not split. If it is <0, then the RFC-1113 recommended line length of 64 is used
	rc	The return code representing the status of the operation. May be NULL.

Returns:: The string form of the block

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

string_t encode ( blob_t const & blob ) [inline]

Encodes the given blob into base-64.

Parameters:

blob

The blob whose contents are to be encoded

Returns:: The string form of the block

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

string_t encode ( T & ar[N] ) [inline]

Encodes the given array into base-64.

Parameters:

The array whose contents are to be encoded

Returns:: The string form of the block

Note:

This function is only defined for compilers that are able to discriminate between pointers and arrays. See Chapter 14 of Imperfect C++ for details about this facility, and consult your STLSoft header files to find out to which compilers this applies.

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

string_t encode	(	void const *	src,
		size_t	srcSize
	)			`[inline]`

Encodes the given block of memory into base-64.

This function takes a pointer to a memory block to be encoded, and a number of bytes to be encoded, and carries out a base-64 encoding on it, returning the results in an instance of the string type string_t . See the example from the main page

Parameters:

	src	Pointer to the block to be encoded
	srcSize	Number of bytes in the block to be encoded

Returns:: The string form of the block

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

string_t encode	(	void const *	src,
		size_t	srcSize,
		unsigned	flags,
		int	lineLen = `0`,
		B64_RC *	rc = `NULL`
	)			`[inline]`

Encodes the given block of memory into base-64.

Parameters:

	src	Pointer to the block to be encoded
	srcSize	Number of bytes in the block to be encoded
	flags	A combination of the B64_FLAGS enumeration, that moderate the behaviour of the function
	lineLen	If the flags parameter contains B64_F_LINE_LEN_USE_PARAM, then this parameter represents the length of the lines into which the encoded form is split, with a hard line break ('\r\n'). If this value is 0, then the line is not split. If it is <0, then the RFC-1113 recommended line length of 64 is used
	rc	The return code representing the status of the operation. May be NULL.

Returns:: The string form of the block

Note:

There is no error return. If insufficient memory can be allocated, an instance of std::bad_alloc will be thrown

Threading: The function is fully re-entrant, assuming that the heap for the system is re-entrant.

Exceptions: Provides the strong guarantee, assuming that the constructor for the string type (string_t) does so.

Exceptions:

std::bad_alloc

If insufficient memory is available to complete the operation

Examples:: example.cpp.1.cpp, and example.cpp.2.cpp.

b64/b64.hpp File Reference

Detailed Description

Namespaces

Classes

Typedefs

Functions

Typedef Documentation

Function Documentation