summaryrefslogtreecommitdiffstats
path: root/include/iprt/base64.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:17:27 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:17:27 +0000
commitf215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch)
tree6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /include/iprt/base64.h
parentInitial commit. (diff)
downloadvirtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.tar.xz
virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.zip
Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'include/iprt/base64.h')
-rw-r--r--include/iprt/base64.h353
1 files changed, 353 insertions, 0 deletions
diff --git a/include/iprt/base64.h b/include/iprt/base64.h
new file mode 100644
index 00000000..ce2cf35a
--- /dev/null
+++ b/include/iprt/base64.h
@@ -0,0 +1,353 @@
+/** @file
+ * IPRT - Base64, MIME content transfer encoding.
+ */
+
+/*
+ * Copyright (C) 2009-2023 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef IPRT_INCLUDED_base64_h
+#define IPRT_INCLUDED_base64_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <iprt/types.h>
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_rt_base64 RTBase64 - Base64, MIME content transfer encoding.
+ * @ingroup grp_rt
+ * @{
+ */
+
+/** @def RTBASE64_EOL_SIZE
+ * The size of the end-of-line marker. */
+#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
+# define RTBASE64_EOL_SIZE (sizeof("\r\n") - 1)
+#else
+# define RTBASE64_EOL_SIZE (sizeof("\n") - 1)
+#endif
+
+
+/** @name Flags for RTBase64EncodeEx() and RTBase64EncodedLengthEx().
+ * @{ */
+/** Insert line breaks into encoded string.
+ * The size of the end-of-line marker is that that of the host platform.
+ */
+#define RTBASE64_FLAGS_EOL_NATIVE UINT32_C(0) /**< Use native newlines. */
+#define RTBASE64_FLAGS_NO_LINE_BREAKS UINT32_C(1) /**< No newlines. */
+#define RTBASE64_FLAGS_EOL_LF UINT32_C(2) /**< Use UNIX-style newlines. */
+#define RTBASE64_FLAGS_EOL_CRLF UINT32_C(3) /**< Use DOS-style newlines. */
+#define RTBASE64_FLAGS_EOL_STYLE_MASK UINT32_C(3) /**< End-of-line style mask. */
+/** @} */
+
+
+/**
+ * Calculates the decoded data size for a Base64 encoded string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param pszString The Base64 encoded string.
+ * @param ppszEnd If not NULL, this will point to the first char
+ * following the Base64 encoded text block. If
+ * NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedSize(const char *pszString, char **ppszEnd);
+
+/**
+ * Calculates the decoded data size for a Base64 encoded UTF-16 string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param pwszString The Base64 encoded UTF-16 string.
+ * @param ppwszEnd If not NULL, this will point to the first char
+ * following the Base64 encoded text block. If
+ * NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedUtf16Size(PCRTUTF16 pwszString, PRTUTF16 *ppwszEnd);
+
+/**
+ * Calculates the decoded data size for a Base64 encoded string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param pszString The Base64 encoded string.
+ * @param cchStringMax The max length to decode, use RTSTR_MAX if the
+ * length of @a pszString is not known and it is
+ * really zero terminated.
+ * @param ppszEnd If not NULL, this will point to the first char
+ * following the Base64 encoded text block. If
+ * NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedSizeEx(const char *pszString, size_t cchStringMax, char **ppszEnd);
+
+/**
+ * Calculates the decoded data size for a Base64 encoded UTF-16 string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param pwszString The Base64 encoded UTF-16 string.
+ * @param cwcStringMax The max length to decode in RTUTF16 units, use
+ * RTSTR_MAX if the length of @a pwszString is not
+ * known and it is really zero terminated.
+ * @param ppwszEnd If not NULL, this will point to the first char
+ * following the Base64 encoded text block. If
+ * NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedUtf16SizeEx(PCRTUTF16 pwszString, size_t cwcStringMax, PRTUTF16 *ppwszEnd);
+
+/**
+ * Decodes a Base64 encoded string into the buffer supplied by the caller.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ * be set, nor will ppszEnd.
+ * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param pszString The Base64 string. Whether the entire string or
+ * just the start of the string is in Base64 depends
+ * on whether ppszEnd is specified or not.
+ * @param pvData Where to store the decoded data.
+ * @param cbData The size of the output buffer that pvData points to.
+ * @param pcbActual Where to store the actual number of bytes returned.
+ * Optional.
+ * @param ppszEnd Indicates that the string may contain other stuff
+ * after the Base64 encoded data when not NULL. Will
+ * be set to point to the first char that's not part of
+ * the encoding. If NULL the entire string must be part
+ * of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64Decode(const char *pszString, void *pvData, size_t cbData, size_t *pcbActual, char **ppszEnd);
+
+/**
+ * Decodes a Base64 encoded UTF-16 string into the buffer supplied by the
+ * caller.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ * be set, nor will ppszEnd.
+ * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param pwszString The Base64 UTF-16 string. Whether the entire string
+ * or just the start of the string is in Base64 depends
+ * on whether ppwszEnd is specified or not.
+ * @param pvData Where to store the decoded data.
+ * @param cbData The size of the output buffer that pvData points to.
+ * @param pcbActual Where to store the actual number of bytes returned.
+ * Optional.
+ * @param ppwszEnd Indicates that the string may contain other stuff
+ * after the Base64 encoded data when not NULL. Will
+ * be set to point to the first char that's not part of
+ * the encoding. If NULL the entire string must be part
+ * of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64DecodeUtf16(PCRTUTF16 pwszString, void *pvData, size_t cbData, size_t *pcbActual, PRTUTF16 *ppwszEnd);
+
+/**
+ * Decodes a Base64 encoded string into the buffer supplied by the caller.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ * be set, nor will ppszEnd.
+ * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param pszString The Base64 string. Whether the entire string or
+ * just the start of the string is in Base64 depends
+ * on whether ppszEnd is specified or not.
+ * @param cchStringMax The max length to decode, use RTSTR_MAX if the
+ * length of @a pszString is not known and it is
+ * really zero terminated.
+ * @param pvData Where to store the decoded data.
+ * @param cbData The size of the output buffer that pvData points to.
+ * @param pcbActual Where to store the actual number of bytes returned.
+ * Optional.
+ * @param ppszEnd Indicates that the string may contain other stuff
+ * after the Base64 encoded data when not NULL. Will
+ * be set to point to the first char that's not part of
+ * the encoding. If NULL the entire string must be part
+ * of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64DecodeEx(const char *pszString, size_t cchStringMax, void *pvData, size_t cbData,
+ size_t *pcbActual, char **ppszEnd);
+
+/**
+ * Decodes a Base64 encoded UTF-16 string into the buffer supplied by the
+ * caller.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ * be set, nor will ppszEnd.
+ * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param pwszString The Base64 UTF-16 string. Whether the entire string
+ * or just the start of the string is in Base64 depends
+ * on whether ppszEnd is specified or not.
+ * @param cwcStringMax The max length to decode in RTUTF16 units, use
+ * RTSTR_MAX if the length of @a pwszString is not
+ * known and it is really zero terminated.
+ * @param pvData Where to store the decoded data.
+ * @param cbData The size of the output buffer that pvData points to.
+ * @param pcbActual Where to store the actual number of bytes returned.
+ * Optional.
+ * @param ppwszEnd Indicates that the string may contain other stuff
+ * after the Base64 encoded data when not NULL. Will
+ * be set to point to the first char that's not part of
+ * the encoding. If NULL the entire string must be part
+ * of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64DecodeUtf16Ex(PCRTUTF16 pwszString, size_t cwcStringMax, void *pvData, size_t cbData,
+ size_t *pcbActual, PRTUTF16 *ppwszEnd);
+
+
+/**
+ * Calculates the length of the Base64 encoding of a given number of bytes of
+ * data produced by RTBase64Encode().
+ *
+ * @returns The Base64 string length, excluding the terminator.
+ * @param cbData The number of bytes to encode.
+ */
+RTDECL(size_t) RTBase64EncodedLength(size_t cbData);
+
+/**
+ * Calculates the UTF-16 length of the Base64 encoding of a given number of
+ * bytes of data produced by RTBase64EncodeUtf16().
+ *
+ * @returns The Base64 UTF-16 string length (in RTUTF16 units), excluding the
+ * terminator.
+ * @param cbData The number of bytes to encode.
+ */
+RTDECL(size_t) RTBase64EncodedUtf16Length(size_t cbData);
+
+/**
+ * Calculates the length of the Base64 encoding of a given number of bytes of
+ * data produced by RTBase64EncodeEx() with the same @a fFlags.
+ *
+ * @returns The Base64 string length, excluding the terminator.
+ * @param cbData The number of bytes to encode.
+ * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
+ */
+RTDECL(size_t) RTBase64EncodedLengthEx(size_t cbData, uint32_t fFlags);
+
+/**
+ * Calculates the UTF-16 length of the Base64 encoding of a given number of
+ * bytes of data produced by RTBase64EncodeUtf16Ex() with the same @a fFlags.
+ *
+ * @returns The Base64 UTF-16 string length (in RTUTF16 units), excluding the
+ * terminator.
+ * @param cbData The number of bytes to encode.
+ * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
+ */
+RTDECL(size_t) RTBase64EncodedUtf16LengthEx(size_t cbData, uint32_t fFlags);
+
+/**
+ * Encodes the specifed data into a Base64 string, the caller supplies the
+ * output buffer.
+ *
+ * This is equivalent to calling RTBase64EncodeEx() with no flags.
+ *
+ * @returns IRPT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ * may contain an invalid Base64 string.
+ *
+ * @param pvData The data to encode.
+ * @param cbData The number of bytes to encode.
+ * @param pszBuf Where to put the Base64 string.
+ * @param cbBuf The size of the output buffer, including the terminator.
+ * @param pcchActual The actual number of characters returned.
+ */
+RTDECL(int) RTBase64Encode(const void *pvData, size_t cbData, char *pszBuf, size_t cbBuf, size_t *pcchActual);
+
+/**
+ * Encodes the specifed data into a Base64 UTF-16 string, the caller supplies
+ * the output buffer.
+ *
+ * This is equivalent to calling RTBase64EncodeUtf16Ex() with no flags.
+ *
+ * @returns IRPT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ * may contain an invalid Base64 string.
+ *
+ * @param pvData The data to encode.
+ * @param cbData The number of bytes to encode.
+ * @param pwszBuf Where to put the Base64 UTF-16 string.
+ * @param cwcBuf The size of the output buffer in RTUTF16 units,
+ * including the terminator.
+ * @param pcwcActual The actual number of characters returned (excluding the
+ * terminator). Optional.
+ */
+RTDECL(int) RTBase64EncodeUtf16(const void *pvData, size_t cbData, PRTUTF16 pwszBuf, size_t cwcBuf, size_t *pcwcActual);
+
+/**
+ * Encodes the specifed data into a Base64 string, the caller supplies the
+ * output buffer.
+ *
+ * @returns IRPT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ * may contain an invalid Base64 string.
+ *
+ * @param pvData The data to encode.
+ * @param cbData The number of bytes to encode.
+ * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
+ * @param pszBuf Where to put the Base64 string.
+ * @param cbBuf The size of the output buffer, including the terminator.
+ * @param pcchActual The actual number of characters returned (excluding the
+ * terminator). Optional.
+ */
+RTDECL(int) RTBase64EncodeEx(const void *pvData, size_t cbData, uint32_t fFlags,
+ char *pszBuf, size_t cbBuf, size_t *pcchActual);
+
+/**
+ * Encodes the specifed data into a Base64 UTF-16 string, the caller supplies
+ * the output buffer.
+ *
+ * @returns IRPT status code.
+ * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ * may contain an invalid Base64 string.
+ *
+ * @param pvData The data to encode.
+ * @param cbData The number of bytes to encode.
+ * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
+ * @param pwszBuf Where to put the Base64 UTF-16 string.
+ * @param cwcBuf The size of the output buffer in RTUTF16 units,
+ * including the terminator.
+ * @param pcwcActual The actual number of characters returned (excluding the
+ * terminator). Optional.
+ */
+RTDECL(int) RTBase64EncodeUtf16Ex(const void *pvData, size_t cbData, uint32_t fFlags,
+ PRTUTF16 pwszBuf, size_t cwcBuf, size_t *pcwcActual);
+
+
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_base64_h */
+