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

B64_NAMESPACE Namespace Reference


Detailed Description

[C/C++] The b64 namespace, within which the core library types and functions reside in C++ compilation.

In C compilation, they all reside in the global namespace.



Classes

class  coding_exception
 Exception thrown during encoding/decoding. More...

Namespaces

namespace  cpp
 [C++ only] The b64::cpp namespace, within which the C++ types and functions used to reside; they now reside within the b64 namespace.

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.

Enumerations

enum  B64_RC {
  B64_RC_OK = 0,
  B64_RC_INSUFFICIENT_BUFFER = 1,
  B64_RC_TRUNCATED_INPUT = 2,
  B64_RC_DATA_ERROR = 3
}
 Return codes (from b64_encode2() / b64_decode2()). More...
enum  B64_FLAGS {
  B64_F_LINE_LEN_USE_PARAM = 0x0000,
  B64_F_LINE_LEN_INFINITE = 0x0001,
  B64_F_LINE_LEN_64 = 0x0002,
  B64_F_LINE_LEN_76 = 0x0003,
  B64_F_LINE_LEN_MASK = 0x000f,
  B64_F_STOP_ON_NOTHING = 0x0000,
  B64_F_STOP_ON_UNKNOWN_CHAR = 0x0100,
  B64_F_STOP_ON_UNEXPECTED_WS = 0x0200,
  B64_F_STOP_ON_BAD_CHAR = 0x0300
}
 Coding behaviour modification flags (for b64_encode2() / b64_decode2()). More...

Functions

size_t b64_encode (void const *src, size_t srcSize, char *dest, size_t destLen)
 Encodes a block of binary data into Base-64.
size_t b64_encode2 (void const *src, size_t srcSize, char *dest, size_t destLen, unsigned flags, int lineLen, B64_RC *rc)
 Encodes a block of binary data into Base-64.
size_t b64_decode (char const *src, size_t srcLen, void *dest, size_t destSize)
 Decodes a sequence of Base-64 into a block of binary data.
size_t b64_decode2 (char const *src, size_t srcLen, void *dest, size_t destSize, unsigned flags, char const **badChar, B64_RC *rc)
 Decodes a sequence of Base-64 into a block of binary data.
char const * b64_getErrorString (B64_RC code)
 Returns the textual description of the error.
size_t b64_getErrorStringLength (B64_RC code)
 Returns the length of the textual description of the error.
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.


Enumeration Type Documentation

enum B64_FLAGS

Coding behaviour modification flags (for b64_encode2() / b64_decode2()).

Enumerator:
B64_F_LINE_LEN_USE_PARAM  Uses the lineLen parameter to b64_encode2(). Ignored by b64_decode2().
B64_F_LINE_LEN_INFINITE  Ignores the lineLen parameter to b64_encode2(). Line length is infinite. Ignored by b64_decode2().
B64_F_LINE_LEN_64  Ignores the lineLen parameter to b64_encode2(). Line length is 64. Ignored by b64_decode2().
B64_F_LINE_LEN_76  Ignores the lineLen parameter to b64_encode2(). Line length is 76. Ignored by b64_decode2().
B64_F_LINE_LEN_MASK  Mask for testing line length flags to b64_encode2(). Ignored by b64_encode2().
B64_F_STOP_ON_NOTHING  Decoding ignores all invalid characters in the input data. Ignored by b64_encode2().
B64_F_STOP_ON_UNKNOWN_CHAR  Causes decoding to break if any non-Base-64 [a-zA-Z0-9=+/], non-whitespace character is encountered. Ignored by b64_encode2().
B64_F_STOP_ON_UNEXPECTED_WS  Causes decoding to break if any unexpected whitespace is encountered. Ignored by b64_encode2().
B64_F_STOP_ON_BAD_CHAR  Causes decoding to break if any non-Base-64 [a-zA-Z0-9=+/] character is encountered. Ignored by b64_encode2().

enum B64_RC

Return codes (from b64_encode2() / b64_decode2()).

Enumerator:
B64_RC_OK  Operation was successful.
B64_RC_INSUFFICIENT_BUFFER  The given translation buffer was not of sufficient size.
B64_RC_TRUNCATED_INPUT  The input did not represent a fully formed stream of octet couplings.
B64_RC_DATA_ERROR  Invalid data.
Examples:
example.c.2.c.


Function Documentation

size_t B64_NAMESPACE::b64_decode ( char const *  src,
size_t  srcLen,
void *  dest,
size_t  destSize 
)

Decodes a sequence of Base-64 into a block of binary data.

Parameters:
src Pointer to the Base-64 block to be decoded. May not be NULL, except when dest is NULL, in which case it is ignored. If dest is NULL, and src is not NULL, then the returned value is calculated exactly, otherwise a value is returned that is guaranteed to be large enough to hold the decoded block.
srcLen Length of block to be encoded. Must be an integral of 4, the Base-64 encoding quantum, otherwise the Base-64 block is assumed to be invalid
dest Pointer to the buffer into which the result is to be written. May be NULL, in which case the function returns the required length
destSize Length of the buffer into which the result is to be written. Must be at least as large as that indicated by the return value from b64_decode(src, srcSize, NULL, 0), even in the case where the encoded form contains a number of characters that will be ignored, resulting in a lower total length of converted form.
Returns:
0 if the size of the buffer was insufficient, or the length of the converted buffer was longer than destSize
Note:
The function returns the required length if dest is NULL. The returned size might be larger than the actual required size, but will never be smaller.

The behaviour of both b64_encode2() and b64_decode2() are undefined if the line length is not a multiple of 4.

Threading: The function is fully re-entrant.

See also:
b64::decode()
Examples:
example.c.1.c.

size_t B64_NAMESPACE::b64_decode2 ( char const *  src,
size_t  srcLen,
void *  dest,
size_t  destSize,
unsigned  flags,
char const **  badChar,
B64_RC *  rc 
)

Decodes a sequence of Base-64 into a block of binary data.

Parameters:
src Pointer to the Base-64 block to be decoded. May not be NULL, except when dest is NULL, in which case it is ignored. If dest is NULL, and src is not NULL, then the returned value is calculated exactly, otherwise a value is returned that is guaranteed to be large enough to hold the decoded block.
srcLen Length of block to be encoded. Must be an integral of 4, the Base-64 encoding quantum, otherwise the Base-64 block is assumed to be invalid
dest Pointer to the buffer into which the result is to be written. May be NULL, in which case the function returns the required length
destSize Length of the buffer into which the result is to be written. Must be at least as large as that indicated by the return value from b64_decode(src, srcSize, NULL, 0), even in the case where the encoded form contains a number of characters that will be ignored, resulting in a lower total length of converted form.
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 any character in the sequence that stops the parsing, as dictated by the flags parameter. May be NULL.
Returns:
0 if the size of the buffer was insufficient, or the length of the converted buffer was longer than destSize, or a bad character stopped parsing.
Note:
The function returns the required length if dest is NULL. The returned size might be larger than the actual required size, but will never be smaller.

The behaviour of both b64_encode2() and b64_decode2() are undefined if the line length is not a multiple of 4.

Threading: The function is fully re-entrant.

See also:
b64::decode()
Examples:
example.c.2.c.

size_t B64_NAMESPACE::b64_encode ( void const *  src,
size_t  srcSize,
char *  dest,
size_t  destLen 
)

Encodes a block of binary data into Base-64.

Parameters:
src Pointer to the block to be encoded. May not be NULL, except when dest is NULL, in which case it is ignored.
srcSize Length of block to be encoded
dest Pointer to the buffer into which the result is to be written. May be NULL, in which case the function returns the required length
destLen Length of the buffer into which the result is to be written. Must be at least as large as that indicated by the return value from b64_encode(NULL, srcSize, NULL, 0).
Returns:
0 if the size of the buffer was insufficient, or the length of the converted buffer was longer than destLen
Note:
The function returns the required length if dest is NULL

The function returns the required length if dest is NULL. The returned size might be larger than the actual required size, but will never be smaller.

Threading: The function is fully re-entrant.

See also:
b64::encode()
Examples:
example.c.1.c.

size_t B64_NAMESPACE::b64_encode2 ( void const *  src,
size_t  srcSize,
char *  dest,
size_t  destLen,
unsigned  flags,
int  lineLen,
B64_RC *  rc 
)

Encodes a block of binary data into Base-64.

Parameters:
src Pointer to the block to be encoded. May not be NULL, except when dest is NULL, in which case it is ignored.
srcSize Length of block to be encoded
dest Pointer to the buffer into which the result is to be written. May be NULL, in which case the function returns the required length
destLen Length of the buffer into which the result is to be written. Must be at least as large as that indicated by the return value from b64_encode2(NULL, srcSize, NULL, 0, flags, lineLen, rc).
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:
0 if the size of the buffer was insufficient, or the length of the converted buffer was longer than destLen
Note:
The function returns the required length if dest is NULL. The returned size might be larger than the actual required size, but will never be smaller.

Threading: The function is fully re-entrant.

See also:
b64::encode()
Examples:
example.c.2.c.

char const* B64_NAMESPACE::b64_getErrorString ( B64_RC  code  ) 

Returns the textual description of the error.

Parameters:
code The error code

size_t B64_NAMESPACE::b64_getErrorStringLength ( B64_RC  code  ) 

Returns the length of the textual description of the error.

See also:
b64_getErrorString()
Parameters:
code The error code

blob_t B64_NAMESPACE::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)
Examples:
example.cpp.1.cpp, and example.cpp.2.cpp.

blob_t B64_NAMESPACE::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 B64_NAMESPACE::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 B64_NAMESPACE::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 B64_NAMESPACE::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)

string_t B64_NAMESPACE::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
Examples:
example.cpp.1.cpp, and example.cpp.2.cpp.

string_t B64_NAMESPACE::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 B64_NAMESPACE::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 B64_NAMESPACE::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 B64_NAMESPACE::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


b64 Library documentation © Synesis Software Pty Ltd, 2004-2007