VirtualBox

source: vbox/trunk/include/iprt/base64.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.4 KB
Line 
1/** @file
2 * IPRT - Base64, MIME content transfer encoding.
3 */
4
5/*
6 * Copyright (C) 2009-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_base64_h
37#define IPRT_INCLUDED_base64_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/types.h>
43
44RT_C_DECLS_BEGIN
45
46/** @defgroup grp_rt_base64 RTBase64 - Base64, MIME content transfer encoding.
47 * @ingroup grp_rt
48 * @{
49 */
50
51/** @def RTBASE64_EOL_SIZE
52 * The size of the end-of-line marker. */
53#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
54# define RTBASE64_EOL_SIZE (sizeof("\r\n") - 1)
55#else
56# define RTBASE64_EOL_SIZE (sizeof("\n") - 1)
57#endif
58
59
60/** @name Flags for RTBase64EncodeEx() and RTBase64EncodedLengthEx().
61 * @{ */
62/** Insert line breaks into encoded string.
63 * The size of the end-of-line marker is that that of the host platform.
64 */
65#define RTBASE64_FLAGS_EOL_NATIVE UINT32_C(0) /**< Use native newlines. */
66#define RTBASE64_FLAGS_NO_LINE_BREAKS UINT32_C(1) /**< No newlines. */
67#define RTBASE64_FLAGS_EOL_LF UINT32_C(2) /**< Use UNIX-style newlines. */
68#define RTBASE64_FLAGS_EOL_CRLF UINT32_C(3) /**< Use DOS-style newlines. */
69#define RTBASE64_FLAGS_EOL_STYLE_MASK UINT32_C(3) /**< End-of-line style mask. */
70/** @} */
71
72
73/**
74 * Calculates the decoded data size for a Base64 encoded string.
75 *
76 * @returns The length in bytes. -1 if the encoding is bad.
77 *
78 * @param pszString The Base64 encoded string.
79 * @param ppszEnd If not NULL, this will point to the first char
80 * following the Base64 encoded text block. If
81 * NULL the entire string is assumed to be Base64.
82 */
83RTDECL(ssize_t) RTBase64DecodedSize(const char *pszString, char **ppszEnd);
84
85/**
86 * Calculates the decoded data size for a Base64 encoded UTF-16 string.
87 *
88 * @returns The length in bytes. -1 if the encoding is bad.
89 *
90 * @param pwszString The Base64 encoded UTF-16 string.
91 * @param ppwszEnd If not NULL, this will point to the first char
92 * following the Base64 encoded text block. If
93 * NULL the entire string is assumed to be Base64.
94 */
95RTDECL(ssize_t) RTBase64DecodedUtf16Size(PCRTUTF16 pwszString, PRTUTF16 *ppwszEnd);
96
97/**
98 * Calculates the decoded data size for a Base64 encoded string.
99 *
100 * @returns The length in bytes. -1 if the encoding is bad.
101 *
102 * @param pszString The Base64 encoded string.
103 * @param cchStringMax The max length to decode, use RTSTR_MAX if the
104 * length of @a pszString is not known and it is
105 * really zero terminated.
106 * @param ppszEnd If not NULL, this will point to the first char
107 * following the Base64 encoded text block. If
108 * NULL the entire string is assumed to be Base64.
109 */
110RTDECL(ssize_t) RTBase64DecodedSizeEx(const char *pszString, size_t cchStringMax, char **ppszEnd);
111
112/**
113 * Calculates the decoded data size for a Base64 encoded UTF-16 string.
114 *
115 * @returns The length in bytes. -1 if the encoding is bad.
116 *
117 * @param pwszString The Base64 encoded UTF-16 string.
118 * @param cwcStringMax The max length to decode in RTUTF16 units, use
119 * RTSTR_MAX if the length of @a pwszString is not
120 * known and it is really zero terminated.
121 * @param ppwszEnd If not NULL, this will point to the first char
122 * following the Base64 encoded text block. If
123 * NULL the entire string is assumed to be Base64.
124 */
125RTDECL(ssize_t) RTBase64DecodedUtf16SizeEx(PCRTUTF16 pwszString, size_t cwcStringMax, PRTUTF16 *ppwszEnd);
126
127/**
128 * Decodes a Base64 encoded string into the buffer supplied by the caller.
129 *
130 * @returns IPRT status code.
131 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
132 * be set, nor will ppszEnd.
133 * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
134 *
135 * @param pszString The Base64 string. Whether the entire string or
136 * just the start of the string is in Base64 depends
137 * on whether ppszEnd is specified or not.
138 * @param pvData Where to store the decoded data.
139 * @param cbData The size of the output buffer that pvData points to.
140 * @param pcbActual Where to store the actual number of bytes returned.
141 * Optional.
142 * @param ppszEnd Indicates that the string may contain other stuff
143 * after the Base64 encoded data when not NULL. Will
144 * be set to point to the first char that's not part of
145 * the encoding. If NULL the entire string must be part
146 * of the Base64 encoded data.
147 */
148RTDECL(int) RTBase64Decode(const char *pszString, void *pvData, size_t cbData, size_t *pcbActual, char **ppszEnd);
149
150/**
151 * Decodes a Base64 encoded UTF-16 string into the buffer supplied by the
152 * caller.
153 *
154 * @returns IPRT status code.
155 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
156 * be set, nor will ppszEnd.
157 * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
158 *
159 * @param pwszString The Base64 UTF-16 string. Whether the entire string
160 * or just the start of the string is in Base64 depends
161 * on whether ppwszEnd is specified or not.
162 * @param pvData Where to store the decoded data.
163 * @param cbData The size of the output buffer that pvData points to.
164 * @param pcbActual Where to store the actual number of bytes returned.
165 * Optional.
166 * @param ppwszEnd Indicates that the string may contain other stuff
167 * after the Base64 encoded data when not NULL. Will
168 * be set to point to the first char that's not part of
169 * the encoding. If NULL the entire string must be part
170 * of the Base64 encoded data.
171 */
172RTDECL(int) RTBase64DecodeUtf16(PCRTUTF16 pwszString, void *pvData, size_t cbData, size_t *pcbActual, PRTUTF16 *ppwszEnd);
173
174/**
175 * Decodes a Base64 encoded string into the buffer supplied by the caller.
176 *
177 * @returns IPRT status code.
178 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
179 * be set, nor will ppszEnd.
180 * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
181 *
182 * @param pszString The Base64 string. Whether the entire string or
183 * just the start of the string is in Base64 depends
184 * on whether ppszEnd is specified or not.
185 * @param cchStringMax The max length to decode, use RTSTR_MAX if the
186 * length of @a pszString is not known and it is
187 * really zero terminated.
188 * @param pvData Where to store the decoded data.
189 * @param cbData The size of the output buffer that pvData points to.
190 * @param pcbActual Where to store the actual number of bytes returned.
191 * Optional.
192 * @param ppszEnd Indicates that the string may contain other stuff
193 * after the Base64 encoded data when not NULL. Will
194 * be set to point to the first char that's not part of
195 * the encoding. If NULL the entire string must be part
196 * of the Base64 encoded data.
197 */
198RTDECL(int) RTBase64DecodeEx(const char *pszString, size_t cchStringMax, void *pvData, size_t cbData,
199 size_t *pcbActual, char **ppszEnd);
200
201/**
202 * Decodes a Base64 encoded UTF-16 string into the buffer supplied by the
203 * caller.
204 *
205 * @returns IPRT status code.
206 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
207 * be set, nor will ppszEnd.
208 * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
209 *
210 * @param pwszString The Base64 UTF-16 string. Whether the entire string
211 * or just the start of the string is in Base64 depends
212 * on whether ppszEnd is specified or not.
213 * @param cwcStringMax The max length to decode in RTUTF16 units, use
214 * RTSTR_MAX if the length of @a pwszString is not
215 * known and it is really zero terminated.
216 * @param pvData Where to store the decoded data.
217 * @param cbData The size of the output buffer that pvData points to.
218 * @param pcbActual Where to store the actual number of bytes returned.
219 * Optional.
220 * @param ppwszEnd Indicates that the string may contain other stuff
221 * after the Base64 encoded data when not NULL. Will
222 * be set to point to the first char that's not part of
223 * the encoding. If NULL the entire string must be part
224 * of the Base64 encoded data.
225 */
226RTDECL(int) RTBase64DecodeUtf16Ex(PCRTUTF16 pwszString, size_t cwcStringMax, void *pvData, size_t cbData,
227 size_t *pcbActual, PRTUTF16 *ppwszEnd);
228
229
230/**
231 * Calculates the length of the Base64 encoding of a given number of bytes of
232 * data produced by RTBase64Encode().
233 *
234 * @returns The Base64 string length, excluding the terminator.
235 * @param cbData The number of bytes to encode.
236 */
237RTDECL(size_t) RTBase64EncodedLength(size_t cbData);
238
239/**
240 * Calculates the UTF-16 length of the Base64 encoding of a given number of
241 * bytes of data produced by RTBase64EncodeUtf16().
242 *
243 * @returns The Base64 UTF-16 string length (in RTUTF16 units), excluding the
244 * terminator.
245 * @param cbData The number of bytes to encode.
246 */
247RTDECL(size_t) RTBase64EncodedUtf16Length(size_t cbData);
248
249/**
250 * Calculates the length of the Base64 encoding of a given number of bytes of
251 * data produced by RTBase64EncodeEx() with the same @a fFlags.
252 *
253 * @returns The Base64 string length, excluding the terminator.
254 * @param cbData The number of bytes to encode.
255 * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
256 */
257RTDECL(size_t) RTBase64EncodedLengthEx(size_t cbData, uint32_t fFlags);
258
259/**
260 * Calculates the UTF-16 length of the Base64 encoding of a given number of
261 * bytes of data produced by RTBase64EncodeUtf16Ex() with the same @a fFlags.
262 *
263 * @returns The Base64 UTF-16 string length (in RTUTF16 units), excluding the
264 * terminator.
265 * @param cbData The number of bytes to encode.
266 * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
267 */
268RTDECL(size_t) RTBase64EncodedUtf16LengthEx(size_t cbData, uint32_t fFlags);
269
270/**
271 * Encodes the specifed data into a Base64 string, the caller supplies the
272 * output buffer.
273 *
274 * This is equivalent to calling RTBase64EncodeEx() with no flags.
275 *
276 * @returns IRPT status code.
277 * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
278 * may contain an invalid Base64 string.
279 *
280 * @param pvData The data to encode.
281 * @param cbData The number of bytes to encode.
282 * @param pszBuf Where to put the Base64 string.
283 * @param cbBuf The size of the output buffer, including the terminator.
284 * @param pcchActual The actual number of characters returned.
285 */
286RTDECL(int) RTBase64Encode(const void *pvData, size_t cbData, char *pszBuf, size_t cbBuf, size_t *pcchActual);
287
288/**
289 * Encodes the specifed data into a Base64 UTF-16 string, the caller supplies
290 * the output buffer.
291 *
292 * This is equivalent to calling RTBase64EncodeUtf16Ex() with no flags.
293 *
294 * @returns IRPT status code.
295 * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
296 * may contain an invalid Base64 string.
297 *
298 * @param pvData The data to encode.
299 * @param cbData The number of bytes to encode.
300 * @param pwszBuf Where to put the Base64 UTF-16 string.
301 * @param cwcBuf The size of the output buffer in RTUTF16 units,
302 * including the terminator.
303 * @param pcwcActual The actual number of characters returned (excluding the
304 * terminator). Optional.
305 */
306RTDECL(int) RTBase64EncodeUtf16(const void *pvData, size_t cbData, PRTUTF16 pwszBuf, size_t cwcBuf, size_t *pcwcActual);
307
308/**
309 * Encodes the specifed data into a Base64 string, the caller supplies the
310 * output buffer.
311 *
312 * @returns IRPT status code.
313 * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
314 * may contain an invalid Base64 string.
315 *
316 * @param pvData The data to encode.
317 * @param cbData The number of bytes to encode.
318 * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
319 * @param pszBuf Where to put the Base64 string.
320 * @param cbBuf The size of the output buffer, including the terminator.
321 * @param pcchActual The actual number of characters returned (excluding the
322 * terminator). Optional.
323 */
324RTDECL(int) RTBase64EncodeEx(const void *pvData, size_t cbData, uint32_t fFlags,
325 char *pszBuf, size_t cbBuf, size_t *pcchActual);
326
327/**
328 * Encodes the specifed data into a Base64 UTF-16 string, the caller supplies
329 * the output buffer.
330 *
331 * @returns IRPT status code.
332 * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
333 * may contain an invalid Base64 string.
334 *
335 * @param pvData The data to encode.
336 * @param cbData The number of bytes to encode.
337 * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
338 * @param pwszBuf Where to put the Base64 UTF-16 string.
339 * @param cwcBuf The size of the output buffer in RTUTF16 units,
340 * including the terminator.
341 * @param pcwcActual The actual number of characters returned (excluding the
342 * terminator). Optional.
343 */
344RTDECL(int) RTBase64EncodeUtf16Ex(const void *pvData, size_t cbData, uint32_t fFlags,
345 PRTUTF16 pwszBuf, size_t cwcBuf, size_t *pcwcActual);
346
347
348/** @} */
349
350RT_C_DECLS_END
351
352#endif /* !IPRT_INCLUDED_base64_h */
353
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette