1/*
2 * qca_textfilter.h - Qt Cryptographic Architecture
3 * Copyright (C) 2003-2005 Justin Karneges <justin@affinix.com>
4 * Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 * 02110-1301 USA
20 *
21 */
22
23/**
24 \file qca_textfilter.h
25
26 Header file for text encoding/decoding classes
27
28 \note You should not use this header directly from an
29 application. You should just use <tt> \#include \<QtCrypto>
30 </tt> instead.
31*/
32
33#ifndef QCA_TEXTFILTER_H
34#define QCA_TEXTFILTER_H
35
36#include "qca_core.h"
37
38namespace QCA {
39
40/**
41 \class TextFilter qca_textfilter.h QtCrypto
42
43 Superclass for text based filtering algorithms
44
45 This differs from Filter in that it has the concept
46 of an algorithm that works in two directions, and
47 supports operations on QString arguments.
48
49 \ingroup UserAPI
50*/
51class QCA_EXPORT TextFilter : public Filter
52{
53public:
54 /**
55 Standard constructor
56
57 \param dir the Direction that this TextFilter
58 should use.
59 */
60 TextFilter(Direction dir);
61
62 /**
63 Reset the TextFilter
64
65 \param dir the Direction that this TextFilter
66 should use.
67 */
68 void setup(Direction dir);
69
70 /**
71 The direction the TextFilter is set up to use
72 */
73 Direction direction() const;
74
75 /**
76 Process an array in the "forward" direction,
77 returning an array
78
79 This method runs in the forward direction, so
80 for something like a Base64 encoding, it takes
81 the "native" array, and returns that array
82 encoded in base64.
83
84 \param a the array to encode
85 */
86 MemoryRegion encode(const MemoryRegion &a);
87
88 /**
89 Process an array in the "reverse" direction,
90 returning an array
91
92 This method runs in the reverse direction, so
93 for something like a Base64 encoding, it takes
94 a Base64 encoded array, and returns the "native"
95 representation.
96
97 \param a the array to decode
98 */
99 MemoryRegion decode(const MemoryRegion &a);
100
101 /**
102 Process an array in the "forward" direction,
103 returning a QString
104
105 This is equivalent to encode(), except
106 that it returns a QString, rather than a
107 byte array.
108
109 \param a the array to encode
110 */
111 QString arrayToString(const MemoryRegion &a);
112
113 /**
114 Process an string in the "reverse" direction,
115 returning a byte array
116
117 This is equivalent to decode(), except
118 that it takes a QString, rather than a
119 byte array.
120
121 \param s the array to decode
122 */
123 MemoryRegion stringToArray(const QString &s);
124
125 /**
126 Process a string in the "forward" direction,
127 returning a string
128
129 This is equivalent to encode(), except
130 that it takes and returns a QString, rather than
131 byte arrays.
132
133 \param s the string to encode
134 */
135 QString encodeString(const QString &s);
136
137 /**
138 Process a string in the "reverse" direction,
139 returning a string
140
141 This is equivalent to decode(), except
142 that it takes and returns a QString, rather than
143 byte arrays.
144
145 \param s the string to decode
146 */
147 QString decodeString(const QString &s);
148
149protected:
150 /**
151 Internal state variable for the Direction
152 that the filter operates in
153 */
154 Direction _dir;
155};
156
157/**
158 \class Hex qca_textfilter.h QtCrypto
159
160 Hexadecimal encoding / decoding
161
162 \ingroup UserAPI
163*/
164class QCA_EXPORT Hex : public TextFilter
165{
166public:
167 /**
168 Standard constructor
169
170 \param dir the Direction that should be used.
171
172 \note The direction can be changed using
173 the setup() call.
174 */
175 Hex(Direction dir = Encode);
176
177 /**
178 Reset the internal state.
179
180 This is useful to reuse an existing Hex object
181 */
182 void clear() override;
183
184 /**
185 Process more data, returning the corresponding
186 encoded or decoded (depending on the Direction
187 set in the constructor or setup() call) representation.
188
189 If you find yourself with code that only calls
190 this method once, you might be better off using
191 encode() or decode(). Similarly, if the data is
192 really a string, you might be better off using
193 arrayToString(), encodeString(), stringToArray()
194 or decodeString().
195
196 \param a the array containing data to process
197 */
198 MemoryRegion update(const MemoryRegion &a) override;
199
200 /**
201 Complete the algorithm
202
203 \return any remaining output. Because of the way
204 hexadecimal encoding works, this will return a
205 zero length array - any output will have been returned
206 from the update() call.
207 */
208 MemoryRegion final() override;
209
210 /**
211 Test if an update() or final() call succeeded.
212
213 \return true if the previous call succeeded
214 */
215 bool ok() const override;
216
217private:
218 Q_DISABLE_COPY(Hex)
219
220 uchar val;
221 bool partial;
222 bool _ok;
223};
224
225/**
226 \class Base64 qca_textfilter.h QtCrypto
227
228 %Base64 encoding / decoding
229
230 \ingroup UserAPI
231*/
232class QCA_EXPORT Base64 : public TextFilter
233{
234public:
235 /**
236 Standard constructor
237
238 \param dir the Direction that should be used.
239
240 \note The direction can be changed using
241 the setup() call.
242 */
243 Base64(Direction dir = Encode);
244
245 /**
246 Returns true if line breaks are enabled
247 */
248 bool lineBreaksEnabled() const;
249
250 /**
251 Returns the line break column
252 */
253 int lineBreaksColumn() const;
254
255 /**
256 Sets line break mode. If enabled, linebreaks will be
257 added to encoded output or accepted in encoded input.
258 If disabled, linebreaks in encoded input will cause
259 a failure to decode. The default is disabled.
260
261 \param b whether to enable line breaks (true) or disable line breaks (false)
262 */
263 void setLineBreaksEnabled(bool b);
264
265 /**
266 Sets the column that linebreaks should be inserted at
267 when encoding.
268
269 \param column the column number that line breaks should be inserted at.
270 */
271 void setLineBreaksColumn(int column);
272
273 /**
274 Reset the internal state. This is useful to
275 reuse an existing Base64 object
276 */
277 void clear() override;
278
279 /**
280 Process more data, returning the corresponding
281 encoded or decoded (depending on the Direction
282 set in the constructor or setup() call) representation.
283
284 If you find yourself with code that only calls
285 this method once, you might be better off using
286 encode() or decode(). Similarly, if the data is
287 really a string, you might be better off using
288 arrayToString(), encodeString(), stringToArray()
289 or decodeString().
290
291 \param a the array containing data to process
292 */
293 MemoryRegion update(const MemoryRegion &a) override;
294
295 /**
296 Complete the algorithm
297
298 \return any remaining output. Because of the way
299 Base64 encoding works, you will get either an
300 empty array, or an array containing one or two
301 "=" (equals, 0x3D) characters.
302 */
303 MemoryRegion final() override;
304
305 /**
306 Test if an update() or final() call succeeded.
307
308 \return true if the previous call succeeded
309 */
310 bool ok() const override;
311
312private:
313 Q_DISABLE_COPY(Base64)
314
315 QByteArray partial;
316 bool _ok;
317 int col;
318 bool _lb_enabled;
319 int _lb_column;
320
321 class Private;
322 Private *d;
323};
324
325}
326
327#endif
328

source code of qca/include/QtCrypto/qca_textfilter.h