Mercurial > libbase64
diff base64.h @ 19:436f5c3243bf
Add C implementation
While here, update years
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 24 Jan 2020 13:57:48 +0100 |
parents | |
children | 26eacf43ea9e |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/base64.h Fri Jan 24 13:57:48 2020 +0100 @@ -0,0 +1,165 @@ +/* + * base64.h -- base64 encoding and decoding + * + * Copyright (c) 2013-2020 David Demelier <markand@malikania.fr> + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#ifndef BASE64_H +#define BASE64_H + +/** + * \file base64.h + * \brief Base64 encoding and decoding. + * \author David Demelier <markand@malikania.fr> + * \version 2.0.0-dev + */ + +#include <stdbool.h> + +#if defined(__cplusplus) +extern "C" { +#endif + +/** + * \page Base64 Base64 + * \brief Base64 encoding and decoding. + * + * The C functions does not allocate memory by itself and therefore user must + * repeat the calls to the functions until all data has been processed. + * + * ## Encoding + * + * You can encode like this: + * + * ```c + * const char *data = "hello"; + * char tmpbuf[5]; + * + * // Note: data will be incremented, use a temporary variable if you need to + * // reuse it + * while (b64_encode_step(&data, tmpbuf)) + * printf("%s", tmpbuf); + * + * printf("\n"); + * ``` + * + * ## Decoding + * + * And you can decode like this: + * + * ``` + * const char *data = "aGVsbG8="; + * char tmpbuf[4]; + * + * // Note: data will be incremented, use a temporary variable if you need to + * // reuse it + * while (b64_decode_step(&data, tmpbuf)) + * printf("%s", tmpbuf); + * + * printf("\n"); + * + * if (errno != 0) + * perror("invalid sequence"); + * ``` + */ + +/** + * Check if the character is a %base64 character, A-Za-z0-9 and +/. + * + * \param ch the character to test + * \return true if valid + */ +bool +b64_isbase64(unsigned char ch); + +/** + * Check if the given character is a valid character in %base64 string, + * including '='. + * + * \param ch the character + * \return true if the character is valid + */ +bool +b64_isvalid(unsigned char ch); + +/** + * Get the %base64 character from the 6-bits value. + * + * \pre value must be valid (< 64) + * \param value the value + * \return the %base64 character for value + */ +unsigned char +b64_lookup(unsigned char value); + +/** + * Get the integer value from the %base64 character. + * + * \pre is_base64(ch) + * \param ch the %base64 character + * \return the integer value for the %base64 character ch + * ```` + * auto b64 = base64::rlookup('D') // 3 + * ```` + */ +unsigned char +b64_rlookup(unsigned char ch); + +/** + * Encode some piece of data into the given output. + * + * The pointer pch will be incremented after the last character that was + * treated for input, user is responsible to call this function until the whole + * string was encoded. + * + * The parameter output will be filled with four characters plus the nul + * terminator and must have enough room to store them. This function will + * append a nul terminator. + * + * \pre pch != NULL + * \pre output != NULL and must have at least five bytes available + * \param pch pointer to pointer to char to consume + * \param output output string + * \return true if the string was fully consumed + */ +bool +b64_encode_step(const char **pch, char *output); + +/** + * Encode some data into the given output. + * + * Similar to b64_encode_step, this function requires successive call until the + * input string has been consumed. + * + * The parameter output will be filled with at most three characters plus the + * nul terminator and must have enough room to store them. This function will + * append a nul terminator. + * + * In case of invalid sequence, errno is set and the function returns false. + * + * \pre pch != NULL + * \pre output != NULL and must have at least four bytes available + * \param pch pointer to pointer to char to consume + * \param output output string + * \return true if the string was fully consumed + */ +bool +b64_decode_step(const char **pch, char *output); + +#if defined(__cplusplus) +} +#endif + +#endif // !BASE64_H