KMime

kmime_headers.h
Go to the documentation of this file.
1 /* -*- c++ -*-
2  kmime_headers.h
3 
4  KMime, the KDE Internet mail/usenet news message library.
5  SPDX-FileCopyrightText: 2001-2002 the KMime authors.
6  See file AUTHORS for details
7  SPDX-FileCopyrightText: 2006 Volker Krause <[email protected]>
8 
9  SPDX-License-Identifier: LGPL-2.0-or-later
10 */
11 /**
12  @file
13  This file is part of the API for handling @ref MIME data and
14  defines the various header classes:
15  - header's base class defining the common interface
16  - generic base classes for different types of fields
17  - incompatible, Structured-based field classes
18  - compatible, Unstructured-based field classes
19 
20  @brief
21  Defines the various headers classes.
22 
23  @authors the KMime authors (see AUTHORS file),
24  Volker Krause <[email protected]>
25 */
26 
27 #pragma once
28 
29 #include "kmime_export.h"
30 #include "kmime_header_parsing.h"
31 
32 #include <QByteArray>
33 #include <QDateTime>
34 #include <QList>
35 #include <QMetaType>
36 #include <QString>
37 #include <QStringList>
38 
39 namespace KMime
40 {
41 
42 class Content;
43 
44 namespace Headers
45 {
46 
47 class BasePrivate;
48 
49 enum contentCategory {
50  CCsingle,
51  CCcontainer,
52  CCmixedPart,
53  CCalternativePart
54 };
55 
56 /**
57  Various possible values for the "Content-Transfer-Encoding" header.
58 */
60  CE7Bit, ///< 7bit
61  CE8Bit, ///< 8bit
62  CEquPr, ///< quoted-printable
63  CEbase64, ///< base64
64  CEuuenc, ///< uuencode
65  CEbinary ///< binary
66 };
67 
68 /**
69  Various possible values for the "Content-Disposition" header.
70 */
72  CDInvalid, ///< Default, invalid value
73  CDinline, ///< inline
74  CDattachment, ///< attachment
75  CDparallel ///< parallel (invalid, do not use)
76 };
77 
78 //@cond PRIVATE
79 // internal macro to generate default constructors
80 #define kmime_mk_trivial_ctor( subclass ) \
81  public: \
82  subclass(); \
83  ~subclass() override;
84 
85 #define kmime_mk_dptr_ctor( subclass ) \
86  protected: \
87  explicit subclass( subclass##Private *d );
88 
89 #define kmime_mk_trivial_ctor_with_name( subclass ) \
90  kmime_mk_trivial_ctor( subclass ) \
91  const char *type() const override; \
92  static const char *staticType();
93 //@endcond
94 
95 //
96 //
97 // HEADER'S BASE CLASS. DEFINES THE COMMON INTERFACE
98 //
99 //
100 
101 /** Baseclass of all header-classes. It represents a
102  header-field as described in RFC-822. */
103 class KMIME_EXPORT Base
104 {
105 public:
106  /**
107  A vector of headers.
108  */
110 
111  /**
112  Creates an empty header.
113  */
114  Base();
115 
116  /**
117  Destructor.
118  */
119  virtual ~Base();
120 
121  /**
122  Parses the given string. Take care of RFC2047-encoded strings.
123  @param s The encoded header data.
124  */
125  virtual void from7BitString(const char *s, size_t len);
126  virtual void from7BitString(const QByteArray &s) = 0;
127 
128  /**
129  Returns the encoded header.
130  @param withHeaderType Specifies whether the header-type should be included.
131  */
132  Q_REQUIRED_RESULT virtual QByteArray
133  as7BitString(bool withHeaderType = true) const = 0;
134 
135  /**
136  Returns the charset that is used for RFC2047-encoding.
137  */
138  Q_REQUIRED_RESULT QByteArray rfc2047Charset() const;
139 
140  /**
141  Sets the charset for RFC2047-encoding.
142  @param cs The new charset used for RFC2047 encoding.
143  */
144  void setRFC2047Charset(const QByteArray &cs);
145 
146  /**
147  Parses the given string and set the charset.
148  @param s The header data as unicode string.
149  @param b The charset preferred for encoding.
150  */
151  virtual void fromUnicodeString(const QString &s, const QByteArray &b) = 0;
152 
153  /**
154  Returns the decoded content of the header without the header-type.
155 
156  @note The return value of this method should only be used when showing an
157  address to the user. It is not guaranteed that fromUnicodeString(
158  asUnicodeString(), ... ) will return the original string.
159  */
160  virtual QString asUnicodeString() const = 0;
161 
162  /**
163  Deletes.
164  */
165  virtual void clear() = 0;
166 
167  /**
168  Checks if this header contains any data.
169  */
170  virtual bool isEmpty() const = 0;
171 
172  /**
173  Returns the type of this header (e.g. "From").
174  */
175  virtual const char *type() const;
176 
177  /**
178  Checks if this header is of type @p t.
179  */
180  Q_REQUIRED_RESULT bool is(const char *t) const;
181 
182  /**
183  Checks if this header is a MIME header.
184  */
185  Q_REQUIRED_RESULT bool isMimeHeader() const;
186 
187 protected:
188  /**
189  Helper method, returns the header prefix including ":".
190  */
191  QByteArray typeIntro() const;
192 
193  //@cond PRIVATE
194  BasePrivate *d_ptr;
195  kmime_mk_dptr_ctor(Base)
196  //@endcond
197 
198 private:
199  Q_DECLARE_PRIVATE(Base)
200  Q_DISABLE_COPY(Base)
201 };
202 
203 //
204 //
205 // GENERIC BASE CLASSES FOR DIFFERENT TYPES OF FIELDS
206 //
207 //
208 
209 namespace Generics
210 {
211 
212 class UnstructuredPrivate;
213 
214 /**
215  Abstract base class for unstructured header fields
216  (e.g. "Subject", "Comment", "Content-description").
217 
218  Features: Decodes the header according to RFC2047, incl. RFC2231
219  extensions to encoded-words.
220 
221  Subclasses need only re-implement @p const @p char* @p type().
222 */
223 
224 // known issues:
225 // - uses old decodeRFC2047String function, instead of our own...
226 
227 class KMIME_EXPORT Unstructured : public Base
228 {
229  //@cond PRIVATE
230  kmime_mk_dptr_ctor(Unstructured)
231  //@endcond
232 public:
233  Unstructured();
234  ~Unstructured() override;
235 
236  using Base::from7BitString;
237  void from7BitString(const QByteArray &s) override;
238  QByteArray as7BitString(bool withHeaderType = true) const override;
239 
240  void fromUnicodeString(const QString &s, const QByteArray &b) override;
241  QString asUnicodeString() const override;
242 
243  void clear() override;
244 
245  bool isEmpty() const override;
246 
247 private:
248  Q_DECLARE_PRIVATE(Unstructured)
249 };
250 
251 class StructuredPrivate;
252 
253 /**
254  @brief
255  Base class for structured header fields.
256 
257  This is the base class for all structured header fields.
258  It contains parsing methods for all basic token types found in rfc2822.
259 
260  @section Parsing
261 
262  At the basic level, there are tokens & tspecials (rfc2045),
263  atoms & specials, quoted-strings, domain-literals (all rfc822) and
264  encoded-words (rfc2047).
265 
266  As a special token, we have the comment. It is one of the basic
267  tokens defined in rfc822, but it's parsing relies in part on the
268  basic token parsers (e.g. comments may contain encoded-words).
269  Also, most upper-level parsers (notably those for phrase and
270  dot-atom) choose to ignore any comment when parsing.
271 
272  Then there are the real composite tokens, which are made up of one
273  or more of the basic tokens (and semantically invisible comments):
274  phrases (rfc822 with rfc2047) and dot-atoms (rfc2822).
275 
276  This finishes the list of supported token types. Subclasses will
277  provide support for more higher-level tokens, where necessary,
278  using these parsers.
279 
280  @author Marc Mutz <[email protected]>
281 */
282 
283 class KMIME_EXPORT Structured : public Base
284 {
285 public:
286  Structured();
287  ~Structured() override;
288 
289  void from7BitString(const char *s, size_t len) override;
290  void from7BitString(const QByteArray &s) override;
291  QString asUnicodeString() const override;
292  void fromUnicodeString(const QString &s, const QByteArray &b) override;
293 
294 protected:
295  /**
296  This method parses the raw header and needs to be implemented in
297  every sub-class.
298 
299  @param scursor Pointer to the start of the data still to parse.
300  @param send Pointer to the end of the data.
301  @param isCRLF true if input string is terminated with a CRLF.
302  */
303  virtual bool parse(const char *&scursor, const char *const send,
304  bool isCRLF = false) = 0;
305 
306  //@cond PRIVATE
307  kmime_mk_dptr_ctor(Structured)
308  //@endcond
309 
310 private:
311  Q_DECLARE_PRIVATE(Structured)
312 };
313 
314 class AddressPrivate;
315 
316 /**
317  Base class for all address related headers.
318 */
319 class KMIME_EXPORT Address : public Structured
320 {
321 public:
322  Address();
323  ~Address() override;
324 protected:
325  //@cond PRIVATE
326  kmime_mk_dptr_ctor(Address)
327  //@endcond
328 private:
329  Q_DECLARE_PRIVATE(Address)
330 };
331 
332 class MailboxListPrivate;
333 
334 /**
335  Base class for headers that deal with (possibly multiple)
336  addresses, but don't allow groups.
337 
338  @see RFC 2822, section 3.4
339 */
340 class KMIME_EXPORT MailboxList : public Address
341 {
342  //@cond PRIVATE
343  kmime_mk_trivial_ctor(MailboxList)
344  kmime_mk_dptr_ctor(MailboxList)
345  //@endcond
346 public:
347  QByteArray as7BitString(bool withHeaderType = true) const override;
348  void fromUnicodeString(const QString &s, const QByteArray &b) override;
349  QString asUnicodeString() const override;
350 
351  void clear() override;
352  bool isEmpty() const override;
353 
354  /**
355  Adds an address to this header.
356 
357  @param mbox A Mailbox object specifying the address.
358  */
359  void addAddress(const Types::Mailbox &mbox);
360 
361  /**
362  Adds an address to this header.
363  @param address The actual email address, with or without angle brackets.
364  @param displayName An optional name associated with the address.
365  */
366  void addAddress(const QByteArray &address,
367  const QString &displayName = QString());
368 
369  /**
370  Returns a list of all addresses in this header, regardless of groups.
371  */
372  QList<QByteArray> addresses() const;
373 
374  /**
375  Returns a list of all display names associated with the addresses in
376  this header. The address is added for addresses that do not have
377  a display name.
378  */
379  QStringList displayNames() const;
380 
381  /**
382  Returns a single string for user-facing display of this mailbox list.
383  This is equivalent to displayNames().join(", ").
384  @since 5.14
385  */
386  QString displayString() const;
387 
388  /**
389  Returns a list of mailboxes listed in this header.
390  */
391  Types::Mailbox::List mailboxes() const;
392 
393 protected:
394  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
395 
396 private:
397  Q_DECLARE_PRIVATE(MailboxList)
398 };
399 
400 class SingleMailboxPrivate;
401 
402 /**
403  Base class for headers that deal with exactly one mailbox
404  (e.g. Sender).
405 */
406 class KMIME_EXPORT SingleMailbox : public MailboxList
407 {
408  //@cond PRIVATE
409  kmime_mk_trivial_ctor(SingleMailbox)
410  //@endcond
411 protected:
412  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
413 private:
414  Q_DECLARE_PRIVATE(SingleMailbox)
415 };
416 
417 class AddressListPrivate;
418 
419 /**
420  Base class for headers that deal with (possibly multiple)
421  addresses, allowing groups.
422 
423  Note: Groups are parsed but not represented in the API yet. All addresses in
424  groups are listed as if they would not be part of a group.
425 
426  @todo Add API for groups?
427 
428  @see RFC 2822, section 3.4
429 */
430 class KMIME_EXPORT AddressList : public Address
431 {
432  //@cond PRIVATE
433  kmime_mk_trivial_ctor(AddressList)
434  kmime_mk_dptr_ctor(AddressList)
435  //@endcond
436 public:
437  QByteArray as7BitString(bool withHeaderType = true) const override;
438  void fromUnicodeString(const QString &s, const QByteArray &b) override;
439  QString asUnicodeString() const override;
440 
441  void clear() override;
442  bool isEmpty() const override;
443 
444  /**
445  Adds an address to this header.
446 
447  @param mbox A Mailbox object specifying the address.
448  */
449  void addAddress(const Types::Mailbox &mbox);
450 
451  /**
452  Adds an address to this header.
453  @param address The actual email address, with or without angle brackets.
454  @param displayName An optional name associated with the address.
455  */
456  void addAddress(const QByteArray &address, const QString &displayName = QString());
457 
458  /**
459  Returns a list of all addresses in this header, regardless of groups.
460  */
461  QList<QByteArray> addresses() const;
462 
463  /**
464  Returns a list of all display names associated with the addresses in this header.
465  The address is added for addresses that don't have a display name.
466  */
467  QStringList displayNames() const;
468 
469  /**
470  Returns a single string for user-facing display of this address list.
471  This is equivalent to displayNames().join(", ").
472  @since 5.14
473  */
474  QString displayString() const;
475 
476  /**
477  Returns a list of mailboxes listed in this header.
478  */
479  Types::Mailbox::List mailboxes() const;
480 
481 protected:
482  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
483 
484 private:
485  Q_DECLARE_PRIVATE(AddressList)
486 };
487 
488 class IdentPrivate;
489 
490 /**
491  Base class for headers which deal with a list of msg-id's.
492 
493  @see RFC 2822, section 3.6.4
494 */
495 class KMIME_EXPORT Ident : public Address
496 {
497  //@cond PRIVATE
498  kmime_mk_trivial_ctor(Ident)
499  kmime_mk_dptr_ctor(Ident)
500  //@endcond
501 public:
502  QByteArray as7BitString(bool withHeaderType = true) const override;
503  void clear() override;
504  bool isEmpty() const override;
505 
506  /**
507  Initialize this identifier Copy the data from
508  */
509  void fromIdent(const Ident* ident);
510 
511  /**
512  Returns the list of identifiers contained in this header.
513  Note:
514  - Identifiers are not enclosed in angle-brackets.
515  - Identifiers are listed in the same order as in the header.
516  */
517  QList<QByteArray> identifiers() const;
518 
519  /**
520  Appends a new identifier to this header.
521  @param id The identifier to append, with or without angle-brackets.
522  */
523  void appendIdentifier(const QByteArray &id);
524 
525 protected:
526  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
527 
528 private:
529  Q_DECLARE_PRIVATE(Ident)
530 };
531 
532 class SingleIdentPrivate;
533 
534 /**
535  Base class for headers which deal with a single msg-id.
536 
537  @see RFC 2822, section 3.6.4
538 */
539 class KMIME_EXPORT SingleIdent : public Ident
540 {
541  //@cond PRIVATE
542  kmime_mk_trivial_ctor(SingleIdent)
543  kmime_mk_dptr_ctor(SingleIdent)
544  //@endcond
545 public:
546  /**
547  Returns the identifier contained in this header.
548  Note: The identifiers is not enclosed in angle-brackets.
549  */
550  QByteArray identifier() const;
551 
552  /**
553  Sets the identifier.
554  @param id The new identifier with or without angle-brackets.
555  */
556  void setIdentifier(const QByteArray &id);
557 
558 protected:
559  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
560 
561 private:
562  Q_DECLARE_PRIVATE(SingleIdent)
563 };
564 
565 class TokenPrivate;
566 
567 /**
568  Base class for headers which deal with a single atom.
569 */
570 class KMIME_EXPORT Token : public Structured
571 {
572  //@cond PRIVATE
573  kmime_mk_trivial_ctor(Token)
574  kmime_mk_dptr_ctor(Token)
575  //@endcond
576 public:
577  QByteArray as7BitString(bool withHeaderType = true) const override;
578  void clear() override;
579  bool isEmpty() const override;
580 
581  /**
582  Returns the token.
583  */
584  QByteArray token() const;
585 
586  /**
587  Sets the token to @p t,
588  */
589  void setToken(const QByteArray &t);
590 
591 protected:
592  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
593 
594 private:
595  Q_DECLARE_PRIVATE(Token)
596 };
597 
598 class PhraseListPrivate;
599 
600 /**
601  Base class for headers containing a list of phrases.
602 */
603 class KMIME_EXPORT PhraseList : public Structured
604 {
605  //@cond PRIVATE
606  kmime_mk_trivial_ctor(PhraseList)
607  //@endcond
608 public:
609  QByteArray as7BitString(bool withHeaderType = true) const override;
610  QString asUnicodeString() const override;
611  void clear() override;
612  bool isEmpty() const override;
613 
614  /**
615  Returns the list of phrases contained in this header.
616  */
617  QStringList phrases() const;
618 
619 protected:
620  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
621 
622 private:
623  Q_DECLARE_PRIVATE(PhraseList)
624 };
625 
626 class DotAtomPrivate;
627 
628 /**
629  Base class for headers containing a dot atom.
630 */
631 class KMIME_EXPORT DotAtom : public Structured
632 {
633  //@cond PRIVATE
634  kmime_mk_trivial_ctor(DotAtom)
635  //@endcond
636 public:
637  QByteArray as7BitString(bool withHeaderType = true) const override;
638  QString asUnicodeString() const override;
639  void clear() override;
640  bool isEmpty() const override;
641 
642 protected:
643  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
644 
645 private:
646  Q_DECLARE_PRIVATE(DotAtom)
647 };
648 
649 class ParametrizedPrivate;
650 
651 /**
652  Base class for headers containing a parameter list such as "Content-Type".
653 */
654 class KMIME_EXPORT Parametrized : public Structured
655 {
656  //@cond PRIVATE
657  kmime_mk_trivial_ctor(Parametrized)
658  kmime_mk_dptr_ctor(Parametrized)
659  //@endcond
660 public:
661  QByteArray as7BitString(bool withHeaderType = true) const override;
662 
663  bool isEmpty() const override;
664  void clear() override;
665 
666  //FIXME: Shouldn't the parameter keys be QByteArray and not QStrings? Only the values can be
667  // non-ascii!
668 
669  /**
670  Returns the value of the specified parameter.
671  @param key The parameter name.
672  */
673  QString parameter(const QString &key) const;
674 
675  /**
676  @param key the key of the parameter to check for
677  @return true if a parameter with the given @p key exists.
678  @since 4.5
679  */
680  bool hasParameter(const QString &key) const;
681 
682  /**
683  Sets the parameter @p key to @p value.
684  @param key The parameter name.
685  @param value The new value for @p key.
686  */
687  void setParameter(const QString &key, const QString &value);
688 
689 protected:
690  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
691 
692 private:
693  Q_DECLARE_PRIVATE(Parametrized)
694 };
695 
696 } // namespace Generics
697 
698 //
699 //
700 // INCOMPATIBLE, GSTRUCTURED-BASED FIELDS:
701 //
702 //
703 
704 class ReturnPathPrivate;
705 
706 /**
707  Represents the Return-Path header field.
708 
709  @see RFC 2822, section 3.6.7
710 */
711 class KMIME_EXPORT ReturnPath : public Generics::Address
712 {
713  //@cond PRIVATE
714  kmime_mk_trivial_ctor_with_name(ReturnPath)
715  //@endcond
716 public:
717  QByteArray as7BitString(bool withHeaderType = true) const override;
718  void clear() override;
719  bool isEmpty() const override;
720 
721 protected:
722  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
723 
724 private:
725  Q_DECLARE_PRIVATE(ReturnPath)
726 };
727 
728 // Address et al.:
729 
730 // rfc(2)822 headers:
731 /**
732  Represent a "From" header.
733 
734  @see RFC 2822, section 3.6.2.
735 */
736 class KMIME_EXPORT From : public Generics::MailboxList
737 {
738  kmime_mk_trivial_ctor_with_name(From)
739 };
740 
741 /**
742  Represents a "Sender" header.
743 
744  @see RFC 2822, section 3.6.2.
745 */
746 class KMIME_EXPORT Sender : public Generics::SingleMailbox
747 {
748  kmime_mk_trivial_ctor_with_name(Sender)
749 };
750 
751 /**
752  Represents a "To" header.
753 
754  @see RFC 2822, section 3.6.3.
755 */
756 class KMIME_EXPORT To : public Generics::AddressList
757 {
758  kmime_mk_trivial_ctor_with_name(To)
759 };
760 
761 /**
762  Represents a "Cc" header.
763 
764  @see RFC 2822, section 3.6.3.
765 */
766 class KMIME_EXPORT Cc : public Generics::AddressList
767 {
768  kmime_mk_trivial_ctor_with_name(Cc)
769 };
770 
771 /**
772  Represents a "Bcc" header.
773 
774  @see RFC 2822, section 3.6.3.
775 */
776 class KMIME_EXPORT Bcc : public Generics::AddressList
777 {
778  kmime_mk_trivial_ctor_with_name(Bcc)
779 };
780 
781 /**
782  Represents a "ReplyTo" header.
783 
784  @see RFC 2822, section 3.6.2.
785 */
786 class KMIME_EXPORT ReplyTo : public Generics::AddressList
787 {
788  kmime_mk_trivial_ctor_with_name(ReplyTo)
789 };
790 
791 class MailCopiesToPrivate;
792 
793 /**
794  Represents a "Mail-Copies-To" header.
795 
796  @see http://www.newsreaders.com/misc/mail-copies-to.html
797 */
798 class KMIME_EXPORT MailCopiesTo : public Generics::AddressList
799 {
800  //@cond PRIVATE
801  kmime_mk_trivial_ctor_with_name(MailCopiesTo)
802  //@endcond
803 public:
804  QByteArray as7BitString(bool withHeaderType = true) const override;
805  QString asUnicodeString() const override;
806 
807  void clear() override;
808  bool isEmpty() const override;
809 
810  /**
811  Returns true if a mail copy was explicitly requested.
812  */
813  bool alwaysCopy() const;
814 
815  /**
816  Sets the header to "poster".
817  */
818  void setAlwaysCopy();
819 
820  /**
821  Returns true if a mail copy was explicitly denied.
822  */
823  bool neverCopy() const;
824 
825  /**
826  Sets the header to "never".
827  */
828  void setNeverCopy();
829 
830 protected:
831  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
832 
833 private:
834  Q_DECLARE_PRIVATE(MailCopiesTo)
835 };
836 
837 class ContentTransferEncodingPrivate;
838 
839 /**
840  Represents a "Content-Transfer-Encoding" header.
841 
842  @see RFC 2045, section 6.
843 */
844 class KMIME_EXPORT ContentTransferEncoding : public Generics::Token
845 {
846  //@cond PRIVATE
847  kmime_mk_trivial_ctor_with_name(ContentTransferEncoding)
848  //@endcond
849 public:
850  void clear() override;
851 
852  /**
853  Returns the encoding specified in this header.
854  */
855  contentEncoding encoding() const;
856 
857  /**
858  Sets the encoding to @p e.
859  */
860  void setEncoding(contentEncoding e);
861 
862  /**
863  Returns whether the Content containing this header is already decoded.
864  */
865  bool isDecoded() const;
866 
867  /**
868  Set whether the Content containing this header is already decoded.
869  For instance, if you fill your Content with already-encoded base64 data,
870  you will want to setDecoded( false ).
871  @param decoded if @c true the content is already decoded
872  */
873  void setDecoded(bool isDecoded = true);
874 
875  /**
876  Returns whether the Content containing this header needs to be encoded
877  (i.e., if decoded() is true and encoding() is base64 or quoted-printable).
878  */
879  bool needToEncode() const;
880 
881 protected:
882  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
883 
884 private:
885  Q_DECLARE_PRIVATE(ContentTransferEncoding)
886 };
887 
888 /**
889  Represents a "Keywords" header.
890 
891  @see RFC 2822, section 3.6.5.
892 */
893 class KMIME_EXPORT Keywords : public Generics::PhraseList
894 {
895  kmime_mk_trivial_ctor_with_name(Keywords)
896 };
897 
898 // DotAtom:
899 
900 /**
901  Represents a "MIME-Version" header.
902 
903  @see RFC 2045, section 4.
904 */
905 class KMIME_EXPORT MIMEVersion : public Generics::DotAtom
906 {
907  kmime_mk_trivial_ctor_with_name(MIMEVersion)
908 };
909 
910 // Ident:
911 
912 /**
913  Represents a "Message-ID" header.
914 
915  @see RFC 2822, section 3.6.4.
916 */
917 class KMIME_EXPORT MessageID : public Generics::SingleIdent
918 {
919  //@cond PRIVATE
920  kmime_mk_trivial_ctor_with_name(MessageID)
921  //@endcond
922 public:
923  /**
924  Generate a message identifier.
925  @param fqdn A fully qualified domain name.
926  */
927  void generate(const QByteArray &fqdn);
928 };
929 
930 class ContentIDPrivate;
931 
932 /**
933  Represents a "Content-ID" header.
934 */
935 class KMIME_EXPORT ContentID : public Generics::SingleIdent
936 {
937  //@cond PRIVATE
938  kmime_mk_trivial_ctor_with_name(ContentID)
939  kmime_mk_dptr_ctor(ContentID)
940  //@endcond
941 
942 protected:
943  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
944 private:
945  Q_DECLARE_PRIVATE(ContentID)
946 };
947 
948 /**
949  Represents a "Supersedes" header.
950 */
951 class KMIME_EXPORT Supersedes : public Generics::SingleIdent
952 {
953  kmime_mk_trivial_ctor_with_name(Supersedes)
954 };
955 
956 /**
957  Represents a "In-Reply-To" header.
958 
959  @see RFC 2822, section 3.6.4.
960 */
961 class KMIME_EXPORT InReplyTo : public Generics::Ident
962 {
963  kmime_mk_trivial_ctor_with_name(InReplyTo)
964 };
965 
966 /**
967  Represents a "References" header.
968 
969  @see RFC 2822, section 3.6.4.
970 */
971 class KMIME_EXPORT References : public Generics::Ident
972 {
973  kmime_mk_trivial_ctor_with_name(References)
974 };
975 
976 class ContentTypePrivate;
977 
978 /**
979  Represents a "Content-Type" header.
980 
981  @see RFC 2045, section 5.
982 */
983 class KMIME_EXPORT ContentType : public Generics::Parametrized
984 {
985  //@cond PRIVATE
986  kmime_mk_trivial_ctor_with_name(ContentType)
987  //@endcond
988 public:
989  QByteArray as7BitString(bool withHeaderType = true) const override;
990  void clear() override;
991  bool isEmpty() const override;
992 
993  /**
994  Returns the mimetype.
995  */
996  QByteArray mimeType() const;
997 
998  /**
999  Returns the media type (first part of the mimetype).
1000  */
1001 
1002  QByteArray mediaType() const;
1003 
1004  /**
1005  Returns the mime sub-type (second part of the mimetype).
1006  */
1007  QByteArray subType() const;
1008 
1009  /**
1010  Sets the mimetype.
1011  @param mimeType The new mimetype.
1012  */
1013  void setMimeType(const QByteArray &mimeType);
1014 
1015  /**
1016  Tests if the media type equals @p mediatype.
1017  */
1018  bool isMediatype(const char *mediatype) const;
1019 
1020  /**
1021  Tests if the mime sub-type equals @p subtype.
1022  */
1023  bool isSubtype(const char *subtype) const;
1024 
1025  /**
1026  Tests if the mime type is @p mimeType.
1027  */
1028  bool isMimeType(const char *mimeType) const;
1029 
1030  /**
1031  Returns true if the associated MIME entity is a text.
1032  */
1033  bool isText() const;
1034 
1035  /**
1036  Returns true if the associated MIME entity is a plain text.
1037  */
1038  bool isPlainText() const;
1039 
1040  /**
1041  Returns true if the associated MIME entity is a HTML file.
1042  */
1043  bool isHTMLText() const;
1044 
1045  /**
1046  Returns true if the associated MIME entity is an image.
1047  */
1048  bool isImage() const;
1049 
1050  /**
1051  Returns true if the associated MIME entity is a multipart container.
1052  */
1053  bool isMultipart() const;
1054 
1055  /**
1056  Returns true if the associated MIME entity contains partial data.
1057  @see partialNumber(), partialCount()
1058  */
1059  bool isPartial() const;
1060 
1061  /**
1062  Returns the charset for the associated MIME entity.
1063  */
1064  QByteArray charset() const;
1065 
1066  /**
1067  Sets the charset.
1068  */
1069  void setCharset(const QByteArray &s);
1070 
1071  /**
1072  Returns the boundary (for multipart containers).
1073  */
1074  QByteArray boundary() const;
1075 
1076  /**
1077  Sets the multipart container boundary.
1078  */
1079  void setBoundary(const QByteArray &s);
1080 
1081  /**
1082  Returns the name of the associated MIME entity.
1083  */
1084  QString name() const;
1085 
1086  /**
1087  Sets the name to @p s using charset @p cs.
1088  */
1089  void setName(const QString &s, const QByteArray &cs);
1090 
1091  /**
1092  Returns the identifier of the associated MIME entity.
1093  */
1094  QByteArray id() const;
1095 
1096  /**
1097  Sets the identifier.
1098  */
1099  void setId(const QByteArray &s);
1100 
1101  /**
1102  Returns the position of this part in a multi-part set.
1103  @see isPartial(), partialCount()
1104  */
1105  int partialNumber() const;
1106 
1107  /**
1108  Returns the total number of parts in a multi-part set.
1109  @see isPartial(), partialNumber()
1110  */
1111  int partialCount() const;
1112 
1113  /**
1114  Sets parameters of a partial MIME entity.
1115  @param total The total number of entities in the multi-part set.
1116  @param number The number of this entity in a multi-part set.
1117  */
1118  void setPartialParams(int total, int number);
1119 
1120  // TODO: document
1121  contentCategory category() const;
1122 
1123  void setCategory(contentCategory c);
1124 
1125 protected:
1126  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1127 
1128 private:
1129  Q_DECLARE_PRIVATE(ContentType)
1130 };
1131 
1132 class ContentDispositionPrivate;
1133 
1134 /**
1135  Represents a "Content-Disposition" header.
1136 
1137  @see RFC 2183
1138 */
1139 class KMIME_EXPORT ContentDisposition : public Generics::Parametrized
1140 {
1141  //@cond PRIVATE
1142  kmime_mk_trivial_ctor_with_name(ContentDisposition)
1143  //@endcond
1144 public:
1145  QByteArray as7BitString(bool withHeaderType = true) const override;
1146  bool isEmpty() const override;
1147  void clear() override;
1148 
1149  /**
1150  Returns the content disposition.
1151  */
1152  contentDisposition disposition() const;
1153 
1154  /**
1155  Sets the content disposition.
1156  @param disp The new content disposition.
1157  */
1158  void setDisposition(contentDisposition disp);
1159 
1160  /**
1161  Returns the suggested filename for the associated MIME part.
1162  This is just a convenience function, it is equivalent to calling
1163  parameter( "filename" );
1164  */
1165  QString filename() const;
1166 
1167  /**
1168  Sets the suggested filename for the associated MIME part.
1169  This is just a convenience function, it is equivalent to calling
1170  setParameter( "filename", filename );
1171  @param filename The filename.
1172  */
1173  void setFilename(const QString &filename);
1174 
1175 protected:
1176  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1177 
1178 private:
1179  Q_DECLARE_PRIVATE(ContentDisposition)
1180 };
1181 
1182 //
1183 //
1184 // COMPATIBLE GUNSTRUCTURED-BASED FIELDS:
1185 //
1186 //
1187 
1188 class GenericPrivate;
1189 
1190 /**
1191  Represents an arbitrary header, that can contain any header-field.
1192  Adds a type over Unstructured.
1193  @see Unstructured
1194 */
1195 class KMIME_EXPORT Generic : public Generics::Unstructured
1196 {
1197 public:
1198  Generic();
1199  Generic(const char *t, int len = -1);
1200  ~Generic() override;
1201 
1202  void clear() override;
1203 
1204  bool isEmpty() const override;
1205 
1206  const char *type() const override;
1207 
1208  void setType(const char *type, int len = -1);
1209 
1210 private:
1211  Q_DECLARE_PRIVATE(Generic)
1212 };
1213 
1214 /**
1215  Represents a "Subject" header.
1216 
1217  @see RFC 2822, section 3.6.5.
1218 */
1219 class KMIME_EXPORT Subject : public Generics::Unstructured
1220 {
1221  //@cond PRIVATE
1222  kmime_mk_trivial_ctor_with_name(Subject)
1223  //@endcond
1224 };
1225 
1226 /**
1227  Represents a "Organization" header.
1228 */
1229 class KMIME_EXPORT Organization : public Generics::Unstructured
1230 {
1231  kmime_mk_trivial_ctor_with_name(Organization)
1232 };
1233 
1234 /**
1235  Represents a "Content-Description" header.
1236 */
1237 class KMIME_EXPORT ContentDescription : public Generics::Unstructured
1238 {
1239  kmime_mk_trivial_ctor_with_name(ContentDescription)
1240 };
1241 
1242 /**
1243  Represents a "Content-Location" header.
1244  @since 4.2
1245 */
1246 class KMIME_EXPORT ContentLocation : public Generics::Unstructured
1247 {
1248  kmime_mk_trivial_ctor_with_name(ContentLocation)
1249 };
1250 
1251 class ControlPrivate;
1252 
1253 /**
1254  Represents a "Control" header.
1255 
1256  @see RFC 1036, section 3.
1257 */
1258 class KMIME_EXPORT Control : public Generics::Structured
1259 {
1260  //@cond PRIVATE
1261  kmime_mk_trivial_ctor_with_name(Control)
1262  //@endcond
1263 public:
1264  QByteArray as7BitString(bool withHeaderType = true) const override;
1265  void clear() override;
1266  bool isEmpty() const override;
1267 
1268  /**
1269  Returns the control message type.
1270  */
1271  QByteArray controlType() const;
1272 
1273  /**
1274  Returns the control message parameter.
1275  */
1276  QByteArray parameter() const;
1277 
1278  /**
1279  Returns true if this is a cancel control message.
1280  @see RFC 1036, section 3.1.
1281  */
1282  bool isCancel() const;
1283 
1284  /**
1285  Changes this header into a cancel control message for the given message-id.
1286  @param msgid The message-id of the article that should be canceled.
1287  */
1288  void setCancel(const QByteArray &msgid);
1289 
1290 protected:
1291  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1292 
1293 private:
1294  Q_DECLARE_PRIVATE(Control)
1295 };
1296 
1297 class DatePrivate;
1298 
1299 /**
1300  Represents a "Date" header.
1301 
1302  @see RFC 2822, section 3.3.
1303 */
1304 class KMIME_EXPORT Date : public Generics::Structured
1305 {
1306  //@cond PRIVATE
1307  kmime_mk_trivial_ctor_with_name(Date)
1308  //@endcond
1309 public:
1310  QByteArray as7BitString(bool withHeaderType = true) const override;
1311  void clear() override;
1312  bool isEmpty() const override;
1313 
1314  /**
1315  Returns the date contained in this header.
1316  */
1317  QDateTime dateTime() const;
1318 
1319  /**
1320  Sets the date.
1321  */
1322  void setDateTime(const QDateTime &dt);
1323 
1324  /**
1325  Returns the age of the message.
1326  */
1327  int ageInDays() const;
1328 
1329 protected:
1330  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1331 
1332 private:
1333  Q_DECLARE_PRIVATE(Date)
1334 };
1335 
1336 class NewsgroupsPrivate;
1337 
1338 /**
1339  Represents a "Newsgroups" header.
1340 
1341  @see RFC 1036, section 2.1.3.
1342 */
1343 class KMIME_EXPORT Newsgroups : public Generics::Structured
1344 {
1345  //@cond PRIVATE
1346  kmime_mk_trivial_ctor_with_name(Newsgroups)
1347  //@endcond
1348 public:
1349  QByteArray as7BitString(bool withHeaderType = true) const override;
1350  void fromUnicodeString(const QString &s, const QByteArray &b) override;
1351  QString asUnicodeString() const override;
1352  void clear() override;
1353  bool isEmpty() const override;
1354 
1355  /**
1356  Returns the list of newsgroups.
1357  */
1358  QList<QByteArray> groups() const;
1359 
1360  /**
1361  Sets the newsgroup list.
1362  */
1363  void setGroups(const QList<QByteArray> &groups);
1364 
1365  /**
1366  Returns true if this message has been cross-posted, i.e. if it has been
1367  posted to multiple groups.
1368  */
1369  bool isCrossposted() const;
1370 
1371 protected:
1372  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1373 
1374 private:
1375  Q_DECLARE_PRIVATE(Newsgroups)
1376 };
1377 
1378 /**
1379  Represents a "Followup-To" header.
1380 
1381  @see RFC 1036, section 2.2.3.
1382 */
1383 class KMIME_EXPORT FollowUpTo : public Newsgroups
1384 {
1385  //@cond PRIVATE
1386  kmime_mk_trivial_ctor_with_name(FollowUpTo)
1387  //@endcond
1388 };
1389 
1390 class LinesPrivate;
1391 
1392 /**
1393  Represents a "Lines" header.
1394 
1395  @see RFC 1036, section 2.2.12.
1396 */
1397 class KMIME_EXPORT Lines : public Generics::Structured
1398 {
1399  //@cond PRIVATE
1400  kmime_mk_trivial_ctor_with_name(Lines)
1401  //@endcond
1402 public:
1403  QByteArray as7BitString(bool withHeaderType = true) const override;
1404  QString asUnicodeString() const override;
1405  void clear() override;
1406  bool isEmpty() const override;
1407 
1408  /**
1409  Returns the number of lines, undefined if isEmpty() returns true.
1410  */
1411  int numberOfLines() const;
1412 
1413  /**
1414  Sets the number of lines to @p lines.
1415  */
1416  void setNumberOfLines(int lines);
1417 
1418 protected:
1419  bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override;
1420 
1421 private:
1422  Q_DECLARE_PRIVATE(Lines)
1423 };
1424 
1425 /**
1426  Represents a "User-Agent" header.
1427 */
1428 class KMIME_EXPORT UserAgent : public Generics::Unstructured
1429 {
1430  kmime_mk_trivial_ctor_with_name(UserAgent)
1431 };
1432 
1433 /** Creates a header based on @param type. If @param type is a known header type,
1434  * the right object type will be created, otherwise a null pointer is returned. */
1435 KMIME_EXPORT Base *createHeader(const QByteArray &type);
1436 
1437 } //namespace Headers
1438 
1439 } //namespace KMime
1440 
1441 // undefine code generation macros again
1442 #undef kmime_mk_trivial_ctor
1443 #undef kmime_mk_dptr_ctor
1444 #undef kmime_mk_trivial_ctor_with_name
1445 
1446 Q_DECLARE_METATYPE(KMime::Headers::To*)
1447 Q_DECLARE_METATYPE(KMime::Headers::Cc*)
1448 Q_DECLARE_METATYPE(KMime::Headers::Bcc*)
1449 
Represents a "Newsgroups" header.
Represents a "User-Agent" header.
QList< KMime::Headers::Base * > List
A vector of headers.
Represents an (email address, display name) pair according RFC 2822, section 3.4.
Definition: kmime_types.h:37
Base class for headers that deal with (possibly multiple) addresses, allowing groups.
Represents a "Content-Transfer-Encoding" header.
@ CEquPr
quoted-printable
Definition: kmime_headers.h:62
@ CEbinary
binary
Definition: kmime_headers.h:65
Base class for headers containing a dot atom.
contentEncoding
Various possible values for the "Content-Transfer-Encoding" header.
Definition: kmime_headers.h:59
Represent a "From" header.
@ CDinline
inline
Definition: kmime_headers.h:73
Baseclass of all header-classes.
Base class for all address related headers.
Represents a "Sender" header.
Represents a "Message-ID" header.
Represents a "References" header.
Base class for headers that deal with (possibly multiple) addresses, but don't allow groups.
Represents a "Content-ID" header.
@ CEbase64
base64
Definition: kmime_headers.h:63
Represents a "Keywords" header.
Represents an arbitrary header, that can contain any header-field.
Represents a "Control" header.
Represents a "Organization" header.
Base class for headers containing a parameter list such as "Content-Type".
Represents a "Bcc" header.
@ CDattachment
attachment
Definition: kmime_headers.h:74
Represents a "Followup-To" header.
Base class for headers which deal with a list of msg-id's.
Represents a "Cc" header.
Represents a "To" header.
Represents a "MIME-Version" header.
Represents a "Content-Description" header.
virtual void from7BitString(const char *s, size_t len)
Parses the given string.
Represents a "Content-Type" header.
@ CEuuenc
uuencode
Definition: kmime_headers.h:64
Base class for headers which deal with a single atom.
@ CDInvalid
Default, invalid value.
Definition: kmime_headers.h:72
Base * createHeader(const QByteArray &type)
Creates a header based on.
Represents a "ReplyTo" header.
Base class for headers containing a list of phrases.
@ CDparallel
parallel (invalid, do not use)
Definition: kmime_headers.h:75
Represents a "Subject" header.
Abstract base class for unstructured header fields (e.g.
Base class for structured header fields.
Represents a "Mail-Copies-To" header.
Base class for headers that deal with exactly one mailbox (e.g.
contentDisposition
Various possible values for the "Content-Disposition" header.
Definition: kmime_headers.h:71
Represents a "Supersedes" header.
Represents a "Date" header.
Base class for headers which deal with a single msg-id.
Represents a "In-Reply-To" header.
Represents a "Content-Disposition" header.
Represents a "Content-Location" header.
Represents the Return-Path header field.
Represents a "Lines" header.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Sep 25 2023 03:50:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.