VirtualBox

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

Last change on this file since 93176 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

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