Synesis Software STLSoft - ... Robust, Lightweight, Cross-platform, Template Software ...

b64/b64.hpp File Reference


Detailed Description

[C++ only] Header file for the b64 C++-API

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>

Go to the source code of this file.

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:
ar 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.

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
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 Library documentation Synesis Software Pty Ltd, 2004-2007