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 | |
38 | namespace 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 | */ |
51 | class QCA_EXPORT TextFilter : public Filter |
52 | { |
53 | public: |
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 | |
149 | protected: |
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 | */ |
164 | class QCA_EXPORT Hex : public TextFilter |
165 | { |
166 | public: |
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 | |
217 | private: |
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 | */ |
232 | class QCA_EXPORT Base64 : public TextFilter |
233 | { |
234 | public: |
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 | |
312 | private: |
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 | |