1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
/**************************************************************************
* *
* Regina - A Normal Surface Theory Calculator *
* Computational Engine *
* *
* Copyright (c) 1999-2011, Ben Burton *
* For further details contact Ben Burton (bab@debian.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; either version 2 of the *
* License, or (at your option) any later version. *
* *
* 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, write to the Free *
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, *
* MA 02110-1301, USA. *
* *
**************************************************************************/
/* end stub */
/*! \file utilities/base64.h
* \brief Routines for base64 encoding and decoding taken from
* the \a gnulib library.
*
* The \a gnulib base64 copyright notice is as follows:
*
* base64.h -- Encode binary data using printable characters.<br>
* Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.<br>
* Written by Simon Josefsson.
*
* 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; either version 2, or (at your option)
* any later version.
*
* 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, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef __BASE64_H
#ifndef __DOXYGEN
#define __BASE64_H
#endif
#include "regina-core.h"
namespace regina {
/**
* \weakgroup utilities
* @{
*/
/**
* Returns the number of base64 characters required to encode the given
* number of bytes. This is the number of characters used (excluding the
* null terminator) by the routine base64Encode(const char*, size_t, char**).
*
* \ifacespython Not present.
*
* @param bytes the number of raw input bytes.
* @return the corresponding number of base64 printable output characters.
*
* @author This routine was taken and modified from the \a gnulib
* library. The original was written by Simon Josefsson and licensed
* under the GPL version 2 or later. See the base64.h notes for details.
*/
inline REGINA_API size_t base64Length(size_t bytes) {
return (((bytes + 2) / 3) * 4);
}
/**
* Determines whether the given character is a base64 printable character as
* used by the base64 routines in Regina. The base64 printable characters
* are the letters (both upper-case and lower-case), digits, plus (+), and
* forward slash (/).
*
* Note that the equals sign (=) is padding, and is not considered by
* this routine to be a base64 printable character.
*
* \ifacespython Not present.
*
* @param ch any character.
* @return \c true if the given character is one of the base64 printable
* characters used in Regina, or \c false if it is not.
*
* @author This routine was taken and modified from the \a gnulib
* library. The original was written by Simon Josefsson and licensed
* under the GPL version 2 or later. See the base64.h notes for details.
*/
REGINA_API bool isBase64(char ch);
/**
* Encodes the given sequence of raw bytes in base64, and writes the
* results into a preallocated output buffer.
*
* The length of the output buffer is passed as the argument \a outlen.
* If the number of base64 characters required is less than \a outlen,
* a terminating \c null will be written to the end of the output sequence.
* If the number of base64 characters is \a outlen or greater, this
* routine will output as many base64 characters as possible, up to a
* maximum of \a outlen.
*
* The routine base64Length() can be used to precalculate precisely how
* many output characters will be required.
*
* \ifacespython Not present.
*
* @param in the sequence of input bytes; this does not need to be
* terminated in any special way.
* @param inlen the length of the input sequence.
* @param out the output buffer into which the resulting base64
* characters will be written.
* @param outlen the length of the output buffer.
*
* @author This routine was taken and modified from the \a gnulib
* library. The original was written by Simon Josefsson and licensed
* under the GPL version 2 or later. See the base64.h notes for details.
*/
REGINA_API void base64Encode(const char* in, size_t inlen, char* out,
size_t outlen);
/**
* Encodes the given sequence of raw bytes in base64, and passes back a
* newly allocated array containing the results. The \a out pointer will
* be set to this new array, which will be null-terminated. This array will
* be allocated using \c new[], and the caller is responsible for destroying
* it using \c delete[].
*
* If the output array is too large (in particular, the expected size
* will overflow a \c size_t), the \a out pointer will be set to \c null.
*
* \ifacespython Not present.
*
* @param in the sequence of input bytes; this does not need to be
* terminated in any special way.
* @param inlen the length of the input sequence.
* @param out the address of a pointer which will be set to the output
* array of base64 characters.
* @return the length of the output array, not counting the terminating null.
*
* @author This routine was taken and modified from the \a gnulib
* library. The original was written by Simon Josefsson and licensed
* under the GPL version 2 or later. See the base64.h notes for details.
*/
REGINA_API size_t base64Encode(const char* in, size_t inlen, char** out);
/**
* Decodes the given sequence of base64 characters, and writes the
* resulting raw bytes into a preallocated output buffer.
*
* The given base64 sequence should not contain any unexpected characters;
* even whitespace will cause the decoding procedure to abort.
*
* The length of the output buffer is passed as the argument \a outlen.
* If an unexpected or invalid character is found, or the output
* buffer is exhausted, this routine will write as many output bytes as
* it can and then return \c false. Otherwise (on success) it will return
* \c true. Either way, it will reset \a outlen to the total number of
* bytes that were written.
*
* The total number of output bytes is important to know, since the output
* array is not terminated in any special way.
*
* \ifacespython Not present.
*
* @param in the input sequence of base64 characters; this does not need
* to be terminated in any special way.
* @param inlen the length of the input sequence.
* @param out the output buffer into which the resulting raw bytes
* will be written.
* @param outlen must contain the length of the output buffer on entry, and
* on exit contains the number of output bytes that were successfully written.
* @return \c true if decoding was successful, or \c false if the output
* buffer was exhausted or an unexpected input character was found.
*
* @author This routine was taken and modified from the \a gnulib
* library. The original was written by Simon Josefsson and licensed
* under the GPL version 2 or later. See the base64.h notes for details.
*/
REGINA_API bool base64Decode(const char* in, size_t inlen, char* out,
size_t* outlen);
/**
* Decodes the given sequence of base64 characters, and passes back a
* newly allocated array containing the results. The \a out pointer
* will be set to this new array, and \a outlen will be set to the
* number of raw bytes in this output array. This array will be
* allocated using \c new[], and the caller is responsible for
* destroying it using \c delete[].
*
* The given base64 sequence should not contain any unexpected characters;
* even whitespace will cause the decoding procedure to abort.
*
* The length of the output buffer is passed as the argument \a outlen.
* If an unexpected or invalid character is found or the output
* buffer is exhausted, this routine will return \c false, set \a out
* to \c null, and leave \a outlen undefined. Otherwise (on success) it
* will return \c true and set \a outlen to the total number of output bytes.
*
* If the user is not interested in the length of the output array, a
* null pointer may be passed in the \a outlen argument. Note however
* that the output array is not terminated in any special way.
*
* \ifacespython Not present.
*
* @param in the input sequence of base64 characters; this does not need
* to be terminated in any special way.
* @param inlen the length of the input sequence.
* @param out the address of a pointer which will be set to the output
* array of raw bytes (or which will be set to \c null on failure).
* @param outlen the address of an integer which will be set to the
* length of the output array (or which will be left undefined on failure).
* @return \c true if decoding was successful, or \c false if an unexpected
* input character was found or some other error occurred.
*
* @author This routine was taken and modified from the \a gnulib
* library. The original was written by Simon Josefsson and licensed
* under the GPL version 2 or later. See the base64.h notes for details.
*/
REGINA_API bool base64Decode(const char* in, size_t inlen, char** out,
size_t* outlen);
/*@}*/
} // namespace regina
#endif
|
