File indexing completed on 2024-04-28 04:43:41
0001 /* 0002 * qca_textfilter.h - Qt Cryptographic Architecture 0003 * Copyright (C) 2003-2005 Justin Karneges <justin@affinix.com> 0004 * Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net> 0005 * 0006 * This library is free software; you can redistribute it and/or 0007 * modify it under the terms of the GNU Lesser General Public 0008 * License as published by the Free Software Foundation; either 0009 * version 2.1 of the License, or (at your option) any later version. 0010 * 0011 * This library is distributed in the hope that it will be useful, 0012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0014 * Lesser General Public License for more details. 0015 * 0016 * You should have received a copy of the GNU Lesser General Public 0017 * License along with this library; if not, write to the Free Software 0018 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 0019 * 02110-1301 USA 0020 * 0021 */ 0022 0023 /** 0024 \file qca_textfilter.h 0025 0026 Header file for text encoding/decoding classes 0027 0028 \note You should not use this header directly from an 0029 application. You should just use <tt> \#include \<QtCrypto> 0030 </tt> instead. 0031 */ 0032 0033 #ifndef QCA_TEXTFILTER_H 0034 #define QCA_TEXTFILTER_H 0035 0036 #include "qca_core.h" 0037 0038 namespace QCA { 0039 0040 /** 0041 \class TextFilter qca_textfilter.h QtCrypto 0042 0043 Superclass for text based filtering algorithms 0044 0045 This differs from Filter in that it has the concept 0046 of an algorithm that works in two directions, and 0047 supports operations on QString arguments. 0048 0049 \ingroup UserAPI 0050 */ 0051 class QCA_EXPORT TextFilter : public Filter 0052 { 0053 public: 0054 /** 0055 Standard constructor 0056 0057 \param dir the Direction that this TextFilter 0058 should use. 0059 */ 0060 TextFilter(Direction dir); 0061 0062 /** 0063 Reset the TextFilter 0064 0065 \param dir the Direction that this TextFilter 0066 should use. 0067 */ 0068 void setup(Direction dir); 0069 0070 /** 0071 The direction the TextFilter is set up to use 0072 */ 0073 Direction direction() const; 0074 0075 /** 0076 Process an array in the "forward" direction, 0077 returning an array 0078 0079 This method runs in the forward direction, so 0080 for something like a Base64 encoding, it takes 0081 the "native" array, and returns that array 0082 encoded in base64. 0083 0084 \param a the array to encode 0085 */ 0086 MemoryRegion encode(const MemoryRegion &a); 0087 0088 /** 0089 Process an array in the "reverse" direction, 0090 returning an array 0091 0092 This method runs in the reverse direction, so 0093 for something like a Base64 encoding, it takes 0094 a Base64 encoded array, and returns the "native" 0095 representation. 0096 0097 \param a the array to decode 0098 */ 0099 MemoryRegion decode(const MemoryRegion &a); 0100 0101 /** 0102 Process an array in the "forward" direction, 0103 returning a QString 0104 0105 This is equivalent to encode(), except 0106 that it returns a QString, rather than a 0107 byte array. 0108 0109 \param a the array to encode 0110 */ 0111 QString arrayToString(const MemoryRegion &a); 0112 0113 /** 0114 Process an string in the "reverse" direction, 0115 returning a byte array 0116 0117 This is equivalent to decode(), except 0118 that it takes a QString, rather than a 0119 byte array. 0120 0121 \param s the array to decode 0122 */ 0123 MemoryRegion stringToArray(const QString &s); 0124 0125 /** 0126 Process a string in the "forward" direction, 0127 returning a string 0128 0129 This is equivalent to encode(), except 0130 that it takes and returns a QString, rather than 0131 byte arrays. 0132 0133 \param s the string to encode 0134 */ 0135 QString encodeString(const QString &s); 0136 0137 /** 0138 Process a string in the "reverse" direction, 0139 returning a string 0140 0141 This is equivalent to decode(), except 0142 that it takes and returns a QString, rather than 0143 byte arrays. 0144 0145 \param s the string to decode 0146 */ 0147 QString decodeString(const QString &s); 0148 0149 protected: 0150 /** 0151 Internal state variable for the Direction 0152 that the filter operates in 0153 */ 0154 Direction _dir; 0155 }; 0156 0157 /** 0158 \class Hex qca_textfilter.h QtCrypto 0159 0160 Hexadecimal encoding / decoding 0161 0162 \ingroup UserAPI 0163 */ 0164 class QCA_EXPORT Hex : public TextFilter 0165 { 0166 public: 0167 /** 0168 Standard constructor 0169 0170 \param dir the Direction that should be used. 0171 0172 \note The direction can be changed using 0173 the setup() call. 0174 */ 0175 Hex(Direction dir = Encode); 0176 0177 /** 0178 Reset the internal state. 0179 0180 This is useful to reuse an existing Hex object 0181 */ 0182 void clear() override; 0183 0184 /** 0185 Process more data, returning the corresponding 0186 encoded or decoded (depending on the Direction 0187 set in the constructor or setup() call) representation. 0188 0189 If you find yourself with code that only calls 0190 this method once, you might be better off using 0191 encode() or decode(). Similarly, if the data is 0192 really a string, you might be better off using 0193 arrayToString(), encodeString(), stringToArray() 0194 or decodeString(). 0195 0196 \param a the array containing data to process 0197 */ 0198 MemoryRegion update(const MemoryRegion &a) override; 0199 0200 /** 0201 Complete the algorithm 0202 0203 \return any remaining output. Because of the way 0204 hexadecimal encoding works, this will return a 0205 zero length array - any output will have been returned 0206 from the update() call. 0207 */ 0208 MemoryRegion final() override; 0209 0210 /** 0211 Test if an update() or final() call succeeded. 0212 0213 \return true if the previous call succeeded 0214 */ 0215 bool ok() const override; 0216 0217 private: 0218 Q_DISABLE_COPY(Hex) 0219 0220 uchar val; 0221 bool partial; 0222 bool _ok; 0223 }; 0224 0225 /** 0226 \class Base64 qca_textfilter.h QtCrypto 0227 0228 %Base64 encoding / decoding 0229 0230 \ingroup UserAPI 0231 */ 0232 class QCA_EXPORT Base64 : public TextFilter 0233 { 0234 public: 0235 /** 0236 Standard constructor 0237 0238 \param dir the Direction that should be used. 0239 0240 \note The direction can be changed using 0241 the setup() call. 0242 */ 0243 Base64(Direction dir = Encode); 0244 0245 /** 0246 Returns true if line breaks are enabled 0247 */ 0248 bool lineBreaksEnabled() const; 0249 0250 /** 0251 Returns the line break column 0252 */ 0253 int lineBreaksColumn() const; 0254 0255 /** 0256 Sets line break mode. If enabled, linebreaks will be 0257 added to encoded output or accepted in encoded input. 0258 If disabled, linebreaks in encoded input will cause 0259 a failure to decode. The default is disabled. 0260 0261 \param b whether to enable line breaks (true) or disable line breaks (false) 0262 */ 0263 void setLineBreaksEnabled(bool b); 0264 0265 /** 0266 Sets the column that linebreaks should be inserted at 0267 when encoding. 0268 0269 \param column the column number that line breaks should be inserted at. 0270 */ 0271 void setLineBreaksColumn(int column); 0272 0273 /** 0274 Reset the internal state. This is useful to 0275 reuse an existing Base64 object 0276 */ 0277 void clear() override; 0278 0279 /** 0280 Process more data, returning the corresponding 0281 encoded or decoded (depending on the Direction 0282 set in the constructor or setup() call) representation. 0283 0284 If you find yourself with code that only calls 0285 this method once, you might be better off using 0286 encode() or decode(). Similarly, if the data is 0287 really a string, you might be better off using 0288 arrayToString(), encodeString(), stringToArray() 0289 or decodeString(). 0290 0291 \param a the array containing data to process 0292 */ 0293 MemoryRegion update(const MemoryRegion &a) override; 0294 0295 /** 0296 Complete the algorithm 0297 0298 \return any remaining output. Because of the way 0299 Base64 encoding works, you will get either an 0300 empty array, or an array containing one or two 0301 "=" (equals, 0x3D) characters. 0302 */ 0303 MemoryRegion final() override; 0304 0305 /** 0306 Test if an update() or final() call succeeded. 0307 0308 \return true if the previous call succeeded 0309 */ 0310 bool ok() const override; 0311 0312 private: 0313 Q_DISABLE_COPY(Base64) 0314 0315 QByteArray partial; 0316 bool _ok; 0317 int col; 0318 bool _lb_enabled; 0319 int _lb_column; 0320 0321 class Private; 0322 Private *d; 0323 }; 0324 0325 } 0326 0327 #endif