oRTP: b64.h File Reference

oRTP 5.1.0

Macros | Typedefs | Enumerations | Functions
b64.h File Reference

[C/C++] Header file for the b64 library. More...

`#include <stddef.h>`
`#include "ortp/port.h"`

## Macros
#define | B64_VER_B64_H_B64_MAJOR 1
#define | B64_VER_B64_H_B64_MINOR 5
#define | B64_VER_B64_H_B64_REVISION 4
#define | B64_VER_B64_H_B64_EDIT 28
#define | B64_VER_1_0_1 0x01000100
#define | B64_VER_1_0_2 0x01000200
#define | B64_VER_1_0_3 0x01000300
#define | B64_VER_1_1_1 0x01010100
#define | B64_VER_1_1_2 0x01010200
#define | B64_VER_1_1_3 0x01010300
#define | B64_VER_1_2_1 0x01020100
#define | B64_VER_1_2_2 0x01020200
#define | B64_VER_1_2_3 0x01020300
#define | B64_VER_1_2_4 0x01020400
#define | B64_VER_1_2_5 0x01020500
#define | B64_VER_1_2_6 0x01020600
#define | B64_VER_1_2_7 0x01020700
#define | B64_VER_1_3_1 0x010301ff
#define | B64_VER_1_3_2 0x010302ff
#define | B64_VER_1_3_3 0x010303ff
#define | B64_VER_1_3_4 0x010304ff
#define | B64_VER B64_VER_1_3_4
#define | B64_VER_MAJOR 1
#define | B64_VER_MINOR 3
#define | B64_VER_REVISION 4
#define | B64_NO_NAMESPACE

## Typedefs
typedef enum B64_RC | B64_RC
typedef enum B64_FLAGS | B64_FLAGS

## Enumerations
enum | B64_RC { B64_RC_OK = 0 , B64_RC_INSUFFICIENT_BUFFER = 1 , B64_RC_TRUNCATED_INPUT = 2 , B64_RC_DATA_ERROR = 3 , B64_max_RC_value }
| 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. More...
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. More...
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. More...
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. More...
char const * | b64_getErrorString (B64_RC code)
| Returns the textual description of the error. More...
size_t | b64_getErrorStringLength (B64_RC code)
| Returns the length of the textual description of the error. More...

## Detailed Description

[C/C++] Header file for the b64 library.

## Macro Definition Documentation

## ◆ B64_VER

#define B64_VER B64_VER_1_3_4

The current composite version number of b64

## ◆ B64_VER_MAJOR

#define B64_VER_MAJOR 1

The major version number of b64

## ◆ B64_VER_MINOR

#define B64_VER_MINOR 3

The minor version number of b64

## ◆ B64_VER_REVISION

#define B64_VER_REVISION 4

The revision version number of b64

## Enumeration Type Documentation

## ◆ B64_FLAGS

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().

## ◆ B64_RC

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.

## Function Documentation

## ◆ b64_decode()

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.

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()

## ◆ b64_decode2()

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.

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()

## ◆ b64_encode()

size_t 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()

## ◆ b64_encode2()

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.

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()

## ◆ b64_getErrorString()

char const * b64_getErrorString | ( | B64_RC | code | ) |

Returns the textual description of the error.

Parameters

  code | The error code

## ◆ b64_getErrorStringLength()

size_t b64_getErrorStringLength | ( | B64_RC | code | ) |

Returns the length of the textual description of the error.

See also
  b64_getErrorString()

Parameters

  code | The error code