QCA

qca_textfilter.h
Go to the documentation of this file.
1 /*
2  * qca_textfilter.h - Qt Cryptographic Architecture
3  * Copyright (C) 2003-2005 Justin Karneges <[email protected]>
4  * Copyright (C) 2004,2005 Brad Hards <[email protected]>
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  */
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
Direction
Direction settings for symmetric algorithms.
Definition: qca_core.h:140
QCA - the Qt Cryptographic Architecture.
Definition: qca_basic.h:41
@ Encode
Operate in the "forward" direction; for example, encrypting.
Definition: qca_core.h:142
Direction _dir
Internal state variable for the Direction that the filter operates in.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:50:08 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.