VirtualBox

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

Last change on this file since 76507 was 76507, checked in by vboxsync, 6 years ago

/include: scm --fix-header-guards. bugref:9344

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.9 KB
Line 
1/** @file
2 * IPRT - Base64, MIME content transfer encoding.
3 */
4
5/*
6 * Copyright (C) 2009-2017 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_base64_h
27#define ___iprt_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_NO_LINE_BREAKS RT_BIT_32(0)
56/** @} */
57
58
59/**
60 * Calculates the decoded data size for a Base64 encoded string.
61 *
62 * @returns The length in bytes. -1 if the encoding is bad.
63 *
64 * @param pszString The Base64 encoded string.
65 * @param ppszEnd If not NULL, this will point to the first char
66 * following the Base64 encoded text block. If
67 * NULL the entire string is assumed to be Base64.
68 */
69RTDECL(ssize_t) RTBase64DecodedSize(const char *pszString, char **ppszEnd);
70
71/**
72 * Calculates the decoded data size for a Base64 encoded string.
73 *
74 * @returns The length in bytes. -1 if the encoding is bad.
75 *
76 * @param pszString The Base64 encoded string.
77 * @param cchStringMax The max length to decode, use RTSTR_MAX if the
78 * length of @a pszString is not known and it is
79 * really zero terminated.
80 * @param ppszEnd If not NULL, this will point to the first char
81 * following the Base64 encoded text block. If
82 * NULL the entire string is assumed to be Base64.
83 */
84RTDECL(ssize_t) RTBase64DecodedSizeEx(const char *pszString, size_t cchStringMax, char **ppszEnd);
85
86/**
87 * Decodes a Base64 encoded string into the buffer supplied by the caller.
88 *
89 * @returns IPRT status code.
90 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
91 * be set, nor will ppszEnd.
92 * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
93 *
94 * @param pszString The Base64 string. Whether the entire string or
95 * just the start of the string is in Base64 depends
96 * on whether ppszEnd is specified or not.
97 * @param pvData Where to store the decoded data.
98 * @param cbData The size of the output buffer that pvData points to.
99 * @param pcbActual Where to store the actual number of bytes returned.
100 * Optional.
101 * @param ppszEnd Indicates that the string may contain other stuff
102 * after the Base64 encoded data when not NULL. Will
103 * be set to point to the first char that's not part of
104 * the encoding. If NULL the entire string must be part
105 * of the Base64 encoded data.
106 */
107RTDECL(int) RTBase64Decode(const char *pszString, void *pvData, size_t cbData, size_t *pcbActual, char **ppszEnd);
108
109/**
110 * Decodes a Base64 encoded string into the buffer supplied by the caller.
111 *
112 * @returns IPRT status code.
113 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
114 * be set, nor will ppszEnd.
115 * @retval VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
116 *
117 * @param pszString The Base64 string. Whether the entire string or
118 * just the start of the string is in Base64 depends
119 * on whether ppszEnd is specified or not.
120 * @param cchStringMax The max length to decode, use RTSTR_MAX if the
121 * length of @a pszString is not known and it is
122 * really zero terminated.
123 * @param pvData Where to store the decoded data.
124 * @param cbData The size of the output buffer that pvData points to.
125 * @param pcbActual Where to store the actual number of bytes returned.
126 * Optional.
127 * @param ppszEnd Indicates that the string may contain other stuff
128 * after the Base64 encoded data when not NULL. Will
129 * be set to point to the first char that's not part of
130 * the encoding. If NULL the entire string must be part
131 * of the Base64 encoded data.
132 */
133RTDECL(int) RTBase64DecodeEx(const char *pszString, size_t cchStringMax, void *pvData, size_t cbData,
134 size_t *pcbActual, char **ppszEnd);
135
136
137/**
138 * Calculates the length of the Base64 encoding of a given number of bytes of
139 * data produced by RTBase64Encode().
140 *
141 * @returns The Base64 string length.
142 * @param cbData The number of bytes to encode.
143 */
144RTDECL(size_t) RTBase64EncodedLength(size_t cbData);
145
146/**
147 * Calculates the length of the Base64 encoding of a given number of bytes of
148 * data produced by RTBase64EncodeEx() with the same @a fFlags.
149 *
150 * @returns The Base64 string length.
151 * @param cbData The number of bytes to encode.
152 * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
153 */
154RTDECL(size_t) RTBase64EncodedLengthEx(size_t cbData, uint32_t fFlags);
155
156/**
157 * Encodes the specifed data into a Base64 string, the caller supplies the
158 * output buffer.
159 *
160 * This is equivalent to calling RTBase64EncodeEx() with no flags.
161 *
162 * @returns IRPT status code.
163 * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
164 * may contain an invalid Base64 string.
165 *
166 * @param pvData The data to encode.
167 * @param cbData The number of bytes to encode.
168 * @param pszBuf Where to put the Base64 string.
169 * @param cbBuf The size of the output buffer, including the terminator.
170 * @param pcchActual The actual number of characters returned.
171 */
172RTDECL(int) RTBase64Encode(const void *pvData, size_t cbData, char *pszBuf, size_t cbBuf, size_t *pcchActual);
173
174/**
175 * Encodes the specifed data into a Base64 string, the caller supplies the
176 * output buffer.
177 *
178 * @returns IRPT status code.
179 * @retval VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
180 * may contain an invalid Base64 string.
181 *
182 * @param pvData The data to encode.
183 * @param cbData The number of bytes to encode.
184 * @param fFlags Flags, any combination of the RTBASE64_FLAGS \#defines.
185 * @param pszBuf Where to put the Base64 string.
186 * @param cbBuf The size of the output buffer, including the terminator.
187 * @param pcchActual The actual number of characters returned.
188 */
189RTDECL(int) RTBase64EncodeEx(const void *pvData, size_t cbData, uint32_t fFlags,
190 char *pszBuf, size_t cbBuf, size_t *pcchActual);
191
192/** @} */
193
194RT_C_DECLS_END
195
196#endif
197
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