NCBI C++ ToolKit
Macros | Enumerations | Functions
ncbi_base64.h File Reference
#include <connect/connect_export.h>
#include <stddef.h>
#include "ncbi_assert.h"
#include <connect/ncbi_base64.h>
+ Include dependency graph for ncbi_base64.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Go to the SVN repository for this file.

Macros

#define BASE64_Encode   CONNECT_BASE64_Encode
 
#define BASE64_Decode   CONNECT_BASE64_Decode
 
#define EBase64_Result   CONNECT_EBase64_Result
 
#define base64url_encode   CONNECT_base64url_encode
 
#define base64url_decode   CONNECT_base64url_decode
 
#define _ASSERT   assert
 

Enumerations

enum  CONNECT_EBase64_Result { eBase64_OK , eBase64_BufferTooSmall , eBase64_InvalidInput }
 Constants that define whether a base64 encoding or decoding operation was successful. More...
 

Functions

void CONNECT_BASE64_Encode (const void *src_buf, size_t src_size, size_t *src_read, void *dst_buf, size_t dst_size, size_t *dst_written, size_t *line_len)
 BASE64-encode up to "src_size" symbols(bytes) from buffer "src_buf". More...
 
int CONNECT_BASE64_Decode (const void *src_buf, size_t src_size, size_t *src_read, void *dst_buf, size_t dst_size, size_t *dst_written)
 BASE64-decode up to "src_size" symbols(bytes) from buffer "src_buf". More...
 
CONNECT_EBase64_Result CONNECT_base64url_encode (const void *src_buf, size_t src_size, void *dst_buf, size_t dst_size, size_t *output_len)
 Encode binary data using the base64url variant of the Base64 family of encodings. More...
 
CONNECT_EBase64_Result CONNECT_base64url_decode (const void *src_buf, size_t src_size, void *dst_buf, size_t dst_size, size_t *output_len)
 Decode the base64url-encoded src_buf and store the result in dst_buf, not '\0'-terminated. More...
 

Macro Definition Documentation

◆ _ASSERT

#define _ASSERT   assert

Definition at line 39 of file ncbi_base64.h.

◆ BASE64_Decode

#define BASE64_Decode   CONNECT_BASE64_Decode

Definition at line 42 of file ncbi_base64.h.

◆ BASE64_Encode

#define BASE64_Encode   CONNECT_BASE64_Encode

Definition at line 41 of file ncbi_base64.h.

◆ base64url_decode

#define base64url_decode   CONNECT_base64url_decode

Definition at line 45 of file ncbi_base64.h.

◆ base64url_encode

#define base64url_encode   CONNECT_base64url_encode

Definition at line 44 of file ncbi_base64.h.

◆ EBase64_Result

Definition at line 43 of file ncbi_base64.h.

Enumeration Type Documentation

◆ CONNECT_EBase64_Result

Constants that define whether a base64 encoding or decoding operation was successful.

Enumerator
eBase64_OK 

Transcoded successfully.

eBase64_BufferTooSmall 

The output buffer is too small.

eBase64_InvalidInput 

Input contains characters outside alphabet.

Definition at line 99 of file ncbi_base64.h.

Function Documentation

◆ CONNECT_BASE64_Decode()

int CONNECT_BASE64_Decode ( const void *  src_buf,
size_t  src_size,
size_t *  src_read,
void *  dst_buf,
size_t  dst_size,
size_t *  dst_written 
)

BASE64-decode up to "src_size" symbols(bytes) from buffer "src_buf".

Write the decoded data to buffer "dst_buf", but no more than "dst_size" bytes. Assign "*src_read" with the # of bytes successfully decoded from "src_buf". Assign "*dst_written" with the # of bytes written to buffer "dst_buf". Return FALSE (0) only if this call cannot decode anything at all. The destination buffer size, as a worst case, equal to the source size will accommodate the entire output. As a rule, each 4 bytes of source (line breaks ignored) get converted into 3 bytes of decoded output.

◆ CONNECT_BASE64_Encode()

void CONNECT_BASE64_Encode ( const void *  src_buf,
size_t  src_size,
size_t *  src_read,
void *  dst_buf,
size_t  dst_size,
size_t *  dst_written,
size_t *  line_len 
)

BASE64-encode up to "src_size" symbols(bytes) from buffer "src_buf".

Write the encoded data to buffer "dst_buf", but no more than "dst_size" bytes. Assign "*src_read" with the # of bytes successfully encoded from "src_buf". Assign "*dst_written" with the # of bytes written to buffer "dst_buf". Resulting lines will not exceed "*line_len" (or the standard default if "line_len" is NULL) bytes; *line_len == 0 disables the line breaks. To estimate required destination buffer size, you can take into account that BASE64 encoding converts every 3 bytes of source into 4 bytes of encoded output, not including the additional line breaks ('
').

◆ CONNECT_base64url_decode()

CONNECT_EBase64_Result CONNECT_base64url_decode ( const void *  src_buf,
size_t  src_size,
void *  dst_buf,
size_t  dst_size,
size_t *  output_len 
)

Decode the base64url-encoded src_buf and store the result in dst_buf, not '\0'-terminated.

This implementation reports the padding character ('=') as an error, so those symbols must be removed before calling this function. When called with a dst_size of zero, this function simply returns the required destination buffer size in output_len.

Large inputs can be processed incrementally by dividing the input into chunks and calling this function for each chunk. Important: When large inputs are incrementally decoded in this way, the source buffer size for all but the last chunk must be a multiple of 4 bytes.

For information about the base64url variant of the Base64 family of encodings, please refer to RFC 4648.

Parameters
src_buf[in] Base64url-encoded data to decode. Ignored if dst_size is zero.
src_size[in] The size of src_buf.
dst_buf[out] Output buffer. Ignored if dst_size is zero.
dst_size[in] The size of the output buffer or zero.
output_len[out] Variable for storing the length of the decoded string. If more space than dst_size bytes is required, dst_buf is not written and the function returns eBase64_BufferTooSmall. Can be NULL.
Returns
eBase64_OK if the input string has been successfully decoded; eBase64_BufferTooSmall if the input buffer is too small to store the decoded string; eBase64_InvalidInput if there's a character in src_buf that's not from the base64url alphabet (alphanumeric, underscore, and dash characters).

◆ CONNECT_base64url_encode()

CONNECT_EBase64_Result CONNECT_base64url_encode ( const void *  src_buf,
size_t  src_size,
void *  dst_buf,
size_t  dst_size,
size_t *  output_len 
)

Encode binary data using the base64url variant of the Base64 family of encodings.

The input data is read from src_buf and the result is stored in dst_buf. This implementation does not pad the output with '='; nor it terminates the output with '\0'. When called with a dst_size of zero, this function simply returns the required destination buffer size in output_len.

Large inputs can be processed incrementally by dividing the input into chunks and calling this function for each chunk. Important: When large inputs are incrementally encoded in this way, the source buffer size for all but the last chunk must be a multiple of 3 bytes.

For information about the base64url variant of the Base64 family of encodings, please refer to RFC 4648.

Parameters
src_buf[in] Data to encode. Ignored if dst_size is zero.
src_size[in] The size of the input data.
dst_buf[out] Output buffer. Ignored if dst_size is zero.
dst_size[in] The size of the output buffer or zero.
output_len[out] Variable for storing the length of the encoded string. If it turns out to be greater than dst_size, dst_buf is not written and the function returns eBase64_BufferTooSmall. Can be NULL.
Returns
eBase64_OK if the input string has been successfully encoded; eBase64_BufferTooSmall if the input buffer is too small to store the encoded string.
Modified on Tue May 21 11:00:20 2024 by modify_doxy.py rev. 669887