KCodecs

kcodecs.h
1 /*
2  SPDX-FileCopyrightText: 2000-2001 Dawit Alemayehu <[email protected]>
3  SPDX-FileCopyrightText: 2001 Rik Hemsley (rikkus) <[email protected]>
4  SPDX-FileCopyrightText: 2001-2002 Marc Mutz <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 
8  The quoted-printable codec as described in RFC 2045, section 6.7. is by
9  Rik Hemsley (C) 2001.
10 */
11 
12 #ifndef KCODECS_H
13 #define KCODECS_H
14 
15 #include <kcodecs_export.h>
16 
17 #include <QString>
18 
19 #include <memory>
20 
21 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 79)
22 // KBase64 methods were moved to KCodecs for kdelibs 3.1
23 #define KBase64 KCodecs
24 #else
25 #define KBase64 KBase64_is_deprecated_use_KCodecs
26 #endif
27 
28 template<typename T, typename U>
29 class QHash;
30 
31 class QByteArray;
32 class QIODevice;
33 
34 /**
35  * A wrapper class for the most commonly used encoding and
36  * decoding algorithms. Currently there is support for encoding
37  * and decoding input using base64, uu and the quoted-printable
38  * specifications.
39  *
40  * \b Usage:
41  *
42  * \code
43  * QByteArray input = "Aladdin:open sesame";
44  * QByteArray result = KCodecs::base64Encode(input);
45  * cout << "Result: " << result.data() << endl;
46  * \endcode
47  *
48  * <pre>
49  * Output should be
50  * Result: QWxhZGRpbjpvcGVuIHNlc2FtZQ==
51  * </pre>
52  *
53  * The above example makes use of the convenience functions
54  * (ones that accept/return null-terminated strings) to encode/decode
55  * a string. If what you need is to encode or decode binary data, then
56  * it is highly recommended that you use the functions that take an input
57  * and output QByteArray as arguments. These functions are specifically
58  * tailored for encoding and decoding binary data.
59  *
60  * @short A collection of commonly used encoding and decoding algorithms.
61  * @author Dawit Alemayehu <[email protected]>
62  * @author Rik Hemsley <[email protected]>
63  */
64 namespace KCodecs
65 {
66 /**
67  * Encodes the given data using the quoted-printable algorithm.
68  *
69  * @param in data to be encoded.
70  * @param useCRLF if true the input data is expected to have
71  * CRLF line breaks and the output will have CRLF line
72  * breaks, too.
73  * @return quoted-printable encoded string.
74  */
75 KCODECS_EXPORT QByteArray quotedPrintableEncode(const QByteArray &in, bool useCRLF = true);
76 
77 /**
78  * Encodes the given data using the quoted-printable algorithm.
79  *
80  * Use this function if you want the result of the encoding
81  * to be placed in another array which cuts down the number
82  * of copy operation that have to be performed in the process.
83  * This is also the preferred method for encoding binary data.
84  *
85  * NOTE: the output array is first reset and then resized
86  * appropriately before use, hence, all data stored in the
87  * output array will be lost.
88  *
89  * @param in data to be encoded.
90  * @param out encoded data.
91  * @param useCRLF if true the input data is expected to have
92  * CRLF line breaks and the output will have CRLF line
93  * breaks, too.
94  */
95 KCODECS_EXPORT void quotedPrintableEncode(const QByteArray &in, QByteArray &out, bool useCRLF);
96 
97 /**
98  * Decodes a quoted-printable encoded data.
99  *
100  * Accepts data with CRLF or standard unix line breaks.
101  *
102  * @param in data to be decoded.
103  * @return decoded string.
104  * @since 5.5
105  */
106 KCODECS_EXPORT QByteArray quotedPrintableDecode(const QByteArray &in);
107 
108 /**
109  * Decodes a quoted-printable encoded data.
110  *
111  * Accepts data with CRLF or standard unix line breaks.
112  * Use this function if you want the result of the decoding
113  * to be placed in another array which cuts down the number
114  * of copy operation that have to be performed in the process.
115  * This is also the preferred method for decoding an encoded
116  * binary data.
117  *
118  * NOTE: the output array is first reset and then resized
119  * appropriately before use, hence, all data stored in the
120  * output array will be lost.
121  *
122  * @param in data to be decoded.
123  * @param out decoded data.
124  */
125 KCODECS_EXPORT void quotedPrintableDecode(const QByteArray &in, QByteArray &out);
126 
127 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 56)
128 /**
129  * Encodes the given data using the uuencode algorithm.
130  *
131  * The output is split into lines starting with the number of
132  * encoded octets in the line and ending with a newline. No
133  * line is longer than 45 octets (60 characters), excluding the
134  * line terminator.
135  *
136  * @param in data to be uuencoded
137  * @return uuencoded string.
138  * @deprecated Not implemented, always returns an empty bytearray.
139  */
140 KCODECS_EXPORT
141 KCODECS_DEPRECATED_VERSION(5, 56, "Not implemented")
142 QByteArray uuencode(const QByteArray &in);
143 #endif
144 
145 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 56)
146 /**
147  * Encodes the given data using the uuencode algorithm.
148  *
149  * Use this function if you want the result of the encoding
150  * to be placed in another array and cut down the number of
151  * copy operation that have to be performed in the process.
152  * This is the preferred method for encoding binary data.
153  *
154  * NOTE: the output array is first reset and then resized
155  * appropriately before use, hence, all data stored in the
156  * output array will be lost.
157  *
158  * @param in data to be uuencoded.
159  * @param out an empty byte array
160  * @deprecated Not implemented, always set @p out to an empty bytearray.
161  */
162 KCODECS_EXPORT
163 KCODECS_DEPRECATED_VERSION(5, 56, "Not implemented")
164 void uuencode(const QByteArray &in, QByteArray &out);
165 #endif
166 
167 /**
168  * Decodes the given data using the uudecode algorithm.
169  *
170  * Any 'begin' and 'end' lines like those generated by
171  * the utilities in unix and unix-like OS will be
172  * automatically ignored.
173  *
174  * @param in data to be decoded.
175  * @return decoded string.
176  */
177 KCODECS_EXPORT QByteArray uudecode(const QByteArray &in);
178 
179 /**
180  * Decodes the given data using the uudecode algorithm.
181  *
182  * Use this function if you want the result of the decoding
183  * to be placed in another array which cuts down the number
184  * of copy operation that have to be performed in the process.
185  * This is the preferred method for decoding binary data.
186  *
187  * Any 'begin' and 'end' lines like those generated by
188  * the utilities in unix and unix-like OS will be
189  * automatically ignored.
190  *
191  * NOTE: the output array is first reset and then resized
192  * appropriately before use, hence, all data stored in the
193  * output array will be lost.
194  *
195  * @param in data to be decoded.
196  * @param out uudecoded data.
197  */
198 KCODECS_EXPORT void uudecode(const QByteArray &in, QByteArray &out);
199 
200 /**
201  * Encodes the given data using the base64 algorithm.
202  *
203  * The boolean argument determines if the encoded data is
204  * going to be restricted to 76 characters or less per line
205  * as specified by RFC 2045. If @p insertLFs is true, then
206  * there will be 76 characters or less per line.
207  *
208  * @param in data to be encoded.
209  * @param insertLFs limit the number of characters per line.
210  *
211  * @return base64 encoded string.
212  * @since 5.5
213  */
214 KCODECS_EXPORT QByteArray base64Encode(const QByteArray &in);
215 
216 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 5)
217 /**
218  * @copydoc
219  * KCodecs::base64Encode(QByteArray)
220  * @deprecated Since 5.5, use KCodecs::base64Encode(QByteArray) instead.
221  */
222 KCODECS_EXPORT
223 KCODECS_DEPRECATED_VERSION(5, 5, "Use QByteArray base64Encode(const QByteArray &)")
224 QByteArray base64Encode(const QByteArray &in, bool insertLFs);
225 #endif
226 
227 /**
228  * Encodes the given data using the base64 algorithm.
229  *
230  * Use this function if you want the result of the encoding
231  * to be placed in another array which cuts down the number
232  * of copy operation that have to be performed in the process.
233  * This is also the preferred method for encoding binary data.
234  *
235  * The boolean argument determines if the encoded data is going
236  * to be restricted to 76 characters or less per line as specified
237  * by RFC 2045. If @p insertLFs is true, then there will be 76
238  * characters or less per line.
239  *
240  * NOTE: the output array is first reset and then resized
241  * appropriately before use, hence, all data stored in the
242  * output array will be lost.
243  *
244  * @param in data to be encoded.
245  * @param out encoded data.
246  * @param insertLFs limit the number of characters per line.
247  */
248 KCODECS_EXPORT void base64Encode(const QByteArray &in, QByteArray &out, bool insertLFs = false);
249 
250 /**
251  * Decodes the given data that was encoded using the
252  * base64 algorithm.
253  *
254  * @param in data to be decoded.
255  * @return decoded string.
256  */
257 KCODECS_EXPORT QByteArray base64Decode(const QByteArray &in);
258 
259 /**
260  * Decodes the given data that was encoded with the base64
261  * algorithm.
262  *
263  * Use this function if you want the result of the decoding
264  * to be placed in another array which cuts down the number
265  * of copy operation that have to be performed in the process.
266  * This is also the preferred method for decoding an encoded
267  * binary data.
268  *
269  * NOTE: the output array is first reset and then resized
270  * appropriately before use, hence, all data stored in the
271  * output array will be lost.
272  *
273  * @param in data to be decoded.
274  * @param out decoded data.
275  */
276 KCODECS_EXPORT void base64Decode(const QByteArray &in, QByteArray &out);
277 
278 /**
279  * Decodes string @p text according to RFC2047,
280  * i.e., the construct =?charset?[qb]?encoded?=
281  *
282  * @param text source string
283  * @returns the decoded string
284  */
285 KCODECS_EXPORT QString decodeRFC2047String(const QString &text);
286 
287 /**
288  * Charset options for RFC2047 encoder
289  * @since 5.5
290  */
292  NoOption = 0, /// No special option
293  ForceDefaultCharset = 1, /// Force use of the default charset
294 };
295 
296 /**
297  * Decodes string @p src according to RFC2047, i.e. the construct
298  * =?charset?[qb]?encoded?=
299  *
300  * @param src source string.
301  * @param usedCS the name of any detected charset or, in case of multiple
302  * different ones, "UTF-8" as that of a super charset is
303  * returned here
304  * @param defaultCS the charset to use in case the detected
305  * one isn't known to us.
306  * @param option options for the encoder
307  *
308  * @return the decoded string.
309  * @since 5.5
310  */
311 KCODECS_EXPORT QString decodeRFC2047String(const QByteArray &src,
312  QByteArray *usedCS,
313  const QByteArray &defaultCS = QByteArray(),
314  CharsetOption option = NoOption);
315 
316 /**
317  * Encodes string @p src according to RFC2047 using charset @p charset.
318  *
319  * This function also makes commas, quotes and other characters part of the encoded name, for example
320  * the string "Jöhn Döe" <[email protected]"> would be encoded as <encoded word for "Jöhn Döe"> <[email protected]>,
321  * i.e. the opening and closing quote mark would be part of the encoded word.
322  * Therefore don't use this function for input strings that contain semantically meaningful characters,
323  * like the quoting marks in this example.
324  *
325  * @param src source string.
326  * @param charset charset to use. If it can't encode the string, UTF-8 will be used instead.
327  * @return the encoded string.
328  * @since 5.5
329  */
330 KCODECS_EXPORT QByteArray encodeRFC2047String(const QString &src, const QByteArray &charset);
331 
332 /**
333  * Decodes the given data that was encoded using the
334  * base45 codec.
335  *
336  * @param in data to be decoded.
337  * @return decoded string.
338  * @since 5.84
339  * @see https://datatracker.ietf.org/doc/draft-faltstrom-base45/
340  */
341 KCODECS_EXPORT QByteArray base45Decode(const QByteArray &in);
342 
343 class Encoder;
344 class EncoderPrivate;
345 class Decoder;
346 class DecoderPrivate;
347 
348 /**
349  @class KCodecs::Codec kcodecs.h KCodecs
350 
351  @glossary @anchor MIME @anchor mime @b MIME:
352  <b>Multipurpose Internet Mail Extensions</b> or @acronym MIME is an
353  Internet Standard that extends the format of e-mail to support text in
354  character sets other than US-ASCII, non-text attachments, multi-part message
355  bodies, and header information in non-ASCII character sets. Virtually all
356  human-written Internet e-mail and a fairly large proportion of automated
357  e-mail is transmitted via @acronym SMTP in MIME format. Internet e-mail is
358  so closely associated with the SMTP and MIME standards that it is sometimes
359  called SMTP/MIME e-mail. The content types defined by MIME standards are
360  also of growing importance outside of e-mail, such as in communication
361  protocols like @acronym HTTP for the World Wide Web. MIME is also a
362  fundamental component of communication protocols such as HTTP, which
363  requires that data be transmitted in the context of e-mail-like messages,
364  even though the data may not actually be e-mail.
365 
366  @glossary @anchor codec @anchor codecs @anchor Codec @anchor Codecs @b codec:
367  a program capable of performing encoding and decoding on a digital data
368  stream. Codecs encode data for storage or encryption and decode it for
369  viewing or editing.
370 
371  @glossary @anchor CRLF @b CRLF: a "Carriage Return (0x0D)" followed by a
372  "Line Feed (0x0A)", two ASCII control characters used to represent a
373  newline on some operating systems, notably DOS and Microsoft Windows.
374 
375  @glossary @anchor LF @b LF: a "Line Feed (0x0A)" ASCII control character used
376  to represent a newline on some operating systems, notably Unix, Unix-like,
377  and Linux.
378 
379  @brief An abstract base class of @ref codecs for common mail transfer encodings.
380 
381  Provides an abstract base class of @ref codecs like base64 and quoted-printable.
382  Implemented as a singleton.
383 
384  @authors Marc Mutz <[email protected]>
385  @since 5.5
386 */
387 class KCODECS_EXPORT Codec
388 {
389 public:
390  enum NewlineType {
391  NewlineLF,
392  NewlineCRLF,
393  };
394 
395  /**
396  Returns a codec associated with the specified @p name.
397 
398  @param name points to a character string containing a valid codec name.
399  */
400  static Codec *codecForName(const char *name);
401 
402  /**
403  Returns a codec associated with the specified @p name.
404 
405  @param name is a QByteArray containing a valid codec name.
406  */
407  static Codec *codecForName(const QByteArray &name);
408 
409  /**
410  Computes the maximum size, in characters, needed for the encoding.
411 
412  @param insize is the number of input characters to be encoded.
413  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
414 
415  @return the maximum number of characters in the encoding.
416  */
417  virtual int maxEncodedSizeFor(int insize, NewlineType newline = NewlineLF) const = 0;
418 
419  /**
420  Computes the maximum size, in characters, needed for the deccoding.
421 
422  @param insize is the number of input characters to be decoded.
423  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
424 
425  @return the maximum number of characters in the decoding.
426  */
427  virtual int maxDecodedSizeFor(int insize, NewlineType newline = NewlineLF) const = 0;
428 
429  /**
430  Creates the encoder for the codec.
431 
432  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
433 
434  @return a pointer to an instance of the codec's encoder.
435  */
436  virtual Encoder *makeEncoder(NewlineType newline = NewlineLF) const = 0;
437 
438  /**
439  Creates the decoder for the codec.
440 
441  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
442 
443  @return a pointer to an instance of the codec's decoder.
444  */
445  virtual Decoder *makeDecoder(NewlineType newline = NewlineLF) const = 0;
446 
447  /**
448  Convenience wrapper that can be used for small chunks of data
449  when you can provide a large enough buffer. The default
450  implementation creates an Encoder and uses it.
451 
452  Encodes a chunk of bytes starting at @p scursor and extending to
453  @p send into the buffer described by @p dcursor and @p dend.
454 
455  This function doesn't support chaining of blocks. The returned
456  block cannot be added to, but you don't need to finalize it, too.
457 
458  Example usage (@p in contains the input data):
459  <pre>
460  KCodecs::Codec *codec = KCodecs::Codec::codecForName("base64");
461  if (!codec) {
462  qFatal() << "no base64 codec found!?";
463  }
464  QByteArray out(in.size() * 1.4); // crude maximal size of b64 encoding
465  QByteArray::Iterator iit = in.begin();
466  QByteArray::Iterator oit = out.begin();
467  if (!codec->encode(iit, in.end(), oit, out.end())) {
468  qDebug() << "output buffer too small";
469  return;
470  }
471  qDebug() << "Size of encoded data:" << oit - out.begin();
472  </pre>
473 
474  @param scursor is a pointer to the start of the input buffer.
475  @param send is a pointer to the end of the input buffer.
476  @param dcursor is a pointer to the start of the output buffer.
477  @param dend is a pointer to the end of the output buffer.
478  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
479 
480  @return false if the encoded data didn't fit into the output buffer;
481  true otherwise.
482  */
483  virtual bool encode(const char *&scursor, const char *const send, char *&dcursor, const char *const dend, NewlineType newline = NewlineLF) const;
484 
485  /**
486  Convenience wrapper that can be used for small chunks of data
487  when you can provide a large enough buffer. The default
488  implementation creates a Decoder and uses it.
489 
490  Decodes a chunk of bytes starting at @p scursor and extending to
491  @p send into the buffer described by @p dcursor and @p dend.
492 
493  This function doesn't support chaining of blocks. The returned
494  block cannot be added to, but you don't need to finalize it, too.
495 
496  Example usage (@p in contains the input data):
497  <pre>
498  KCodecs::Codec *codec = KCodecs::Codec::codecForName("base64");
499  if (!codec) {
500  qFatal() << "no base64 codec found!?";
501  }
502  QByteArray out(in.size()); // good guess for any encoding...
503  QByteArray::Iterator iit = in.begin();
504  QByteArray::Iterator oit = out.begin();
505  if (!codec->decode(iit, in.end(), oit, out.end())) {
506  qDebug() << "output buffer too small";
507  return;
508  }
509  qDebug() << "Size of decoded data:" << oit - out.begin();
510  </pre>
511 
512  @param scursor is a pointer to the start of the input buffer.
513  @param send is a pointer to the end of the input buffer.
514  @param dcursor is a pointer to the start of the output buffer.
515  @param dend is a pointer to the end of the output buffer.
516  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
517 
518  @return false if the decoded data didn't fit into the output buffer;
519  true otherwise.
520  */
521  virtual bool decode(const char *&scursor, const char *const send, char *&dcursor, const char *const dend, NewlineType newline = NewlineLF) const;
522 
523  /**
524  Even more convenient, but also a bit slower and more memory
525  intensive, since it allocates storage for the worst case and then
526  shrinks the result QByteArray to the actual size again.
527 
528  For use with small @p src.
529 
530  @param src is a QByteArray containing the data to encode.
531  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
532  */
533  virtual QByteArray encode(const QByteArray &src, NewlineType newline = NewlineLF) const;
534 
535  /**
536  Even more convenient, but also a bit slower and more memory
537  intensive, since it allocates storage for the worst case and then
538  shrinks the result QByteArray to the actual size again.
539 
540  For use with small @p src.
541 
542  @param src is a QByteArray containing the data to decode.
543  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
544  */
545  virtual QByteArray decode(const QByteArray &src, NewlineType newline = NewlineLF) const;
546 
547  /**
548  Returns the name of the encoding. Guaranteed to be lowercase.
549  */
550  virtual const char *name() const = 0;
551 
552  /**
553  Destroys the codec.
554  */
555  virtual ~Codec()
556  {
557  }
558 
559 protected:
560  /**
561  Constructs the codec.
562  */
564  {
565  }
566 };
567 
568 /**
569  @class KCodecs::Decoder kcodecs.h KCodecs
570 
571  @brief Stateful CTE decoder class
572 
573  Stateful decoder class, modelled after QTextDecoder.
574 
575  @section Overview
576 
577  KCodecs decoders are designed to be able to process encoded data in
578  chunks of arbitrary size and to work with output buffers of also
579  arbitrary size. They maintain any state necessary to go on where
580  the previous call left off.
581 
582  The class consists of only two methods of interest: see decode,
583  which decodes an input block and finalize, which flushes any
584  remaining data to the output stream.
585 
586  Typically, you will create a decoder instance, call decode as
587  often as necessary, then call finalize (most often a single
588  call suffices, but it might be that during that call the output
589  buffer is filled, so you should be prepared to call finalize
590  as often as necessary, ie. until it returns @p true).
591 
592  @section Return Values
593 
594  Both methods return @p true to indicate that they've finished their
595  job. For decode, a return value of @p true means that the
596  current input block has been finished (@p false most often means
597  that the output buffer is full, but that isn't required
598  behavior. The decode call is free to return at arbitrary
599  times during processing).
600 
601  For finalize, a return value of @p true means that all data
602  implicitly or explicitly stored in the decoder instance has been
603  flushed to the output buffer. A @p false return value should be
604  interpreted as "check if the output buffer is full and call me
605  again", just as with decode.
606 
607  @section Usage Pattern
608 
609  Since the decoder maintains state, you can only use it once. After
610  a sequence of input blocks has been processed, you finalize
611  the output and then delete the decoder instance. If you want to
612  process another input block sequence, you create a new instance.
613 
614  Typical usage (@p in contains the (base64-encoded) input data),
615  taking into account all the conventions detailed above:
616 
617  <pre>
618  KCodecs::Codec *codec = KCodecs::Codec::codecForName("base64");
619  if (!codec) {
620  qFatal() << "No codec found for base64!";
621  }
622  KCodecs::Decoder *dec = codec->makeDecoder();
623  Q_ASSERT(dec); // should not happen
624  QByteArray out(256); // small buffer is enough ;-)
625  QByteArray::Iterator iit = in.begin();
626  QByteArray::Iterator oit = out.begin();
627  // decode the chunk
628  while (!dec->decode(iit, in.end(), oit, out.end()))
629  if (oit == out.end()) { // output buffer full, process contents
630  do_something_with(out);
631  oit = out.begin();
632  }
633  // repeat while loop for each input block
634  // ...
635  // finish (flush remaining data from decoder):
636  while (!dec->finish(oit, out.end()))
637  if (oit == out.end()) { // output buffer full, process contents
638  do_something_with(out);
639  oit = out.begin();
640  }
641  // now process last chunk:
642  out.resize(oit - out.begin());
643  do_something_with(out);
644  // _delete_ the decoder, but not the codec:
645  delete dec;
646  </pre>
647 
648  @since 5.5
649 */
650 class KCODECS_EXPORT Decoder
651 {
652 protected:
653  friend class Codec;
654  friend class DecoderPrivate;
655 
656  /**
657  Protected constructor. Use KCodecs::Codec::makeDecoder to create an
658  instance.
659 
660  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
661  */
662  Decoder(Codec::NewlineType newline = Codec::NewlineLF);
663 
664 public:
665  /**
666  Destroys the decoder.
667  */
668  virtual ~Decoder();
669 
670  /**
671  Decodes a chunk of data, maintaining state information between
672  calls. See class decumentation for calling conventions.
673 
674  @param scursor is a pointer to the start of the input buffer.
675  @param send is a pointer to the end of the input buffer.
676  @param dcursor is a pointer to the start of the output buffer.
677  @param dend is a pointer to the end of the output buffer.
678  */
679  virtual bool decode(const char *&scursor, const char *const send, char *&dcursor, const char *const dend) = 0;
680 
681  /**
682  Call this method to finalize the output stream. Writes all
683  remaining data and resets the decoder. See KCodecs::Codec for
684  calling conventions.
685 
686  @param dcursor is a pointer to the start of the output buffer.
687  @param dend is a pointer to the end of the output buffer.
688  */
689  virtual bool finish(char *&dcursor, const char *const dend) = 0;
690 
691 protected:
692  //@cond PRIVATE
693  std::unique_ptr<DecoderPrivate> const d;
694  //@endcond
695 };
696 
697 /**
698  @class KCodecs::Encoder kcodecs.h KCodecs
699 
700  @brief Stateful encoder class.
701 
702  Stateful encoder class, modeled after QTextEncoder.
703 
704  @since 5.5
705 */
706 class KCODECS_EXPORT Encoder
707 {
708 protected:
709  friend class Codec;
710  friend class EncoderPrivate;
711 
712  /**
713  Protected constructor. Use KCodecs::Codec::makeEncoder if you want one.
714 
715  @param newline whether make new lines using @ref CRLF, or @ref LF (default is @ref LF).
716  */
717  explicit Encoder(Codec::NewlineType newline = Codec::NewlineLF);
718 
719 public:
720  /**
721  Destroys the encoder.
722  */
723  virtual ~Encoder();
724 
725  /**
726  Encodes a chunk of data, maintaining state information between
727  calls. See KCodecs::Codec for calling conventions.
728 
729  @param scursor is a pointer to the start of the input buffer.
730  @param send is a pointer to the end of the input buffer.
731  @param dcursor is a pointer to the start of the output buffer.
732  @param dend is a pointer to the end of the output buffer.
733  */
734  virtual bool encode(const char *&scursor, const char *const send, char *&dcursor, const char *const dend) = 0;
735 
736  /**
737  Call this method to finalize the output stream. Writes all remaining
738  data and resets the encoder. See KCodecs::Codec for calling conventions.
739 
740  @param dcursor is a pointer to the start of the output buffer.
741  @param dend is a pointer to the end of the output buffer.
742  */
743  virtual bool finish(char *&dcursor, const char *const dend) = 0;
744 
745 protected:
746  /**
747  The maximum number of characters permitted in the output buffer.
748  */
749  enum {
750  maxBufferedChars = 8, /**< Eight */
751  };
752 
753  /**
754  Writes character @p ch to the output stream or the output buffer,
755  depending on whether or not the output stream has space left.
756 
757  @param ch is the character to write.
758  @param dcursor is a pointer to the start of the output buffer.
759  @param dend is a pointer to the end of the output buffer.
760 
761  @return true if written to the output stream; else false if buffered.
762  */
763  bool write(char ch, char *&dcursor, const char *const dend);
764 
765  /**
766  Writes characters from the output buffer to the output stream.
767  Implementations of encode and finish should call this
768  at the very beginning and for each iteration of the while loop.
769 
770  @param dcursor is a pointer to the start of the output buffer.
771  @param dend is a pointer to the end of the output buffer.
772 
773  @return true if all chars could be written, false otherwise
774  */
775  bool flushOutputBuffer(char *&dcursor, const char *const dend);
776 
777  /**
778  Convenience function. Outputs @ref LF or @ref CRLF, based on the
779  state of mWithCRLF.
780 
781  @param dcursor is a pointer to the start of the output buffer.
782  @param dend is a pointer to the end of the output buffer.
783  */
784  bool writeCRLF(char *&dcursor, const char *const dend);
785 
786 protected:
787  //@cond PRIVATE
788  std::unique_ptr<EncoderPrivate> const d;
789  //@endcond
790 };
791 
792 } // namespace KCodecs
793 
794 #endif // KCODECS_H
KIMAP2_EXPORT QTextCodec * codecForName(const QString &name)
Stateful encoder class.
Definition: kcodecs.h:706
Stateful CTE decoder class.
Definition: kcodecs.h:650
KCODECS_EXPORT QString decodeRFC2047String(const QString &text)
Decodes string text according to RFC2047, i.e., the construct =?charset?[qb]?encoded?...
Definition: kcodecs.cpp:374
@ ForceDefaultCharset
No special option.
Definition: kcodecs.h:293
KCODECS_EXPORT QByteArray uudecode(const QByteArray &in)
Decodes the given data using the uudecode algorithm.
Definition: kcodecs.cpp:163
virtual ~Codec()
Destroys the codec.
Definition: kcodecs.h:555
KCODECS_EXPORT QByteArray base45Decode(const QByteArray &in)
Decodes the given data that was encoded using the base45 codec.
CharsetOption
Charset options for RFC2047 encoder.
Definition: kcodecs.h:291
Codec()
Constructs the codec.
Definition: kcodecs.h:563
KCODECS_EXPORT QByteArray base64Encode(const QByteArray &in)
Encodes the given data using the base64 algorithm.
Definition: kcodecs.cpp:117
KCODECS_EXPORT QByteArray base64Decode(const QByteArray &in)
Decodes the given data that was encoded using the base64 algorithm.
Definition: kcodecs.cpp:137
KCODECS_EXPORT QByteArray quotedPrintableEncode(const QByteArray &in, bool useCRLF=true)
Encodes the given data using the quoted-printable algorithm.
Definition: kcodecs.cpp:95
KCODECS_EXPORT QByteArray uuencode(const QByteArray &in)
Encodes the given data using the uuencode algorithm.
Definition: kcodecs.cpp:149
A wrapper class for the most commonly used encoding and decoding algorithms.
Definition: kcharsets.h:26
An abstract base class of codecs for common mail transfer encodings.
Definition: kcodecs.h:387
QByteArray encodeRFC2047String(const QString &src, const QByteArray &charset)
Encodes string src according to RFC2047 using charset charset.
Definition: kcodecs.cpp:441
KCODECS_EXPORT QByteArray quotedPrintableDecode(const QByteArray &in)
Decodes a quoted-printable encoded data.
Definition: kcodecs.cpp:106
Definition: kcodecs.h:29
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 04:10:34 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.