File indexing completed on 2024-03-24 05:21:19
0001 /* -*- c++ -*- 0002 kmime_headers.h 0003 0004 KMime, the KDE Internet mail/usenet news message library. 0005 SPDX-FileCopyrightText: 2001-2002 the KMime authors. 0006 See file AUTHORS for details 0007 SPDX-FileCopyrightText: 2006 Volker Krause <vkrause@kde.org> 0008 0009 SPDX-License-Identifier: LGPL-2.0-or-later 0010 */ 0011 /** 0012 @file 0013 This file is part of the API for handling @ref MIME data and 0014 defines the various header classes: 0015 - header's base class defining the common interface 0016 - generic base classes for different types of fields 0017 - incompatible, Structured-based field classes 0018 - compatible, Unstructured-based field classes 0019 0020 @brief 0021 Defines the various headers classes. 0022 0023 @authors the KMime authors (see AUTHORS file), 0024 Volker Krause \<vkrause@kde.org\> 0025 */ 0026 0027 #pragma once 0028 0029 #include "kmime_export.h" 0030 #include "kmime_header_parsing.h" 0031 0032 #include <QByteArray> 0033 #include <QDateTime> 0034 #include <QList> 0035 #include <QMetaType> 0036 #include <QString> 0037 #include <QStringList> 0038 0039 namespace KMime 0040 { 0041 0042 class Content; 0043 0044 namespace Headers 0045 { 0046 0047 class BasePrivate; 0048 0049 /** 0050 Various possible values for the "Content-Transfer-Encoding" header. 0051 */ 0052 enum contentEncoding { 0053 CE7Bit, ///< 7bit 0054 CE8Bit, ///< 8bit 0055 CEquPr, ///< quoted-printable 0056 CEbase64, ///< base64 0057 CEuuenc, ///< uuencode 0058 CEbinary ///< binary 0059 }; 0060 0061 /** 0062 Various possible values for the "Content-Disposition" header. 0063 */ 0064 enum contentDisposition { 0065 CDInvalid, ///< Default, invalid value 0066 CDinline, ///< inline 0067 CDattachment, ///< attachment 0068 CDparallel ///< parallel (invalid, do not use) 0069 }; 0070 0071 //@cond PRIVATE 0072 // internal macro to generate default constructors 0073 #define kmime_mk_trivial_ctor( subclass ) \ 0074 public: \ 0075 subclass(); \ 0076 ~subclass() override; 0077 0078 #define kmime_mk_dptr_ctor( subclass ) \ 0079 protected: \ 0080 explicit subclass( subclass##Private *d ); 0081 0082 #define kmime_mk_trivial_ctor_with_name( subclass ) \ 0083 kmime_mk_trivial_ctor( subclass ) \ 0084 const char *type() const override; \ 0085 static const char *staticType(); 0086 //@endcond 0087 0088 // 0089 // 0090 // HEADER'S BASE CLASS. DEFINES THE COMMON INTERFACE 0091 // 0092 // 0093 0094 /** Baseclass of all header-classes. It represents a 0095 header-field as described in RFC-822. */ 0096 class KMIME_EXPORT Base 0097 { 0098 public: 0099 /** 0100 A vector of headers. 0101 */ 0102 typedef QList<KMime::Headers::Base *> List; 0103 0104 /** 0105 Creates an empty header. 0106 */ 0107 Base(); 0108 0109 /** 0110 Destructor. 0111 */ 0112 virtual ~Base(); 0113 0114 /** 0115 Parses the given string. Take care of RFC2047-encoded strings. 0116 @param s The encoded header data. 0117 */ 0118 virtual void from7BitString(const char *s, size_t len); 0119 virtual void from7BitString(const QByteArray &s) = 0; 0120 0121 /** 0122 Returns the encoded header. 0123 @param withHeaderType Specifies whether the header-type should be included. 0124 */ 0125 [[nodiscard]] virtual QByteArray 0126 as7BitString(bool withHeaderType = true) const = 0; 0127 0128 /** 0129 Returns the charset that is used for RFC2047-encoding. 0130 */ 0131 [[nodiscard]] QByteArray rfc2047Charset() const; 0132 0133 /** 0134 Sets the charset for RFC2047-encoding. 0135 @param cs The new charset used for RFC2047 encoding. 0136 */ 0137 void setRFC2047Charset(const QByteArray &cs); 0138 0139 /** 0140 Parses the given string and set the charset. 0141 @param s The header data as unicode string. 0142 @param b The charset preferred for encoding. 0143 */ 0144 virtual void fromUnicodeString(const QString &s, const QByteArray &b) = 0; 0145 0146 /** 0147 Returns the decoded content of the header without the header-type. 0148 0149 @note The return value of this method should only be used when showing an 0150 address to the user. It is not guaranteed that fromUnicodeString( 0151 asUnicodeString(), ... ) will return the original string. 0152 */ 0153 virtual QString asUnicodeString() const = 0; 0154 0155 /** 0156 Deletes. 0157 */ 0158 virtual void clear() = 0; 0159 0160 /** 0161 Checks if this header contains any data. 0162 */ 0163 virtual bool isEmpty() const = 0; 0164 0165 /** 0166 Returns the type of this header (e.g. "From"). 0167 */ 0168 virtual const char *type() const; 0169 0170 /** 0171 Checks if this header is of type @p t. 0172 */ 0173 [[nodiscard]] bool is(const char *t) const; 0174 0175 /** 0176 Checks if this header is a MIME header. 0177 */ 0178 [[nodiscard]] bool isMimeHeader() const; 0179 0180 protected: 0181 /** 0182 Helper method, returns the header prefix including ":". 0183 */ 0184 QByteArray typeIntro() const; 0185 0186 //@cond PRIVATE 0187 BasePrivate *d_ptr; 0188 kmime_mk_dptr_ctor(Base) 0189 //@endcond 0190 0191 private: 0192 Q_DECLARE_PRIVATE(Base) 0193 Q_DISABLE_COPY(Base) 0194 }; 0195 0196 // 0197 // 0198 // GENERIC BASE CLASSES FOR DIFFERENT TYPES OF FIELDS 0199 // 0200 // 0201 0202 namespace Generics 0203 { 0204 0205 class UnstructuredPrivate; 0206 0207 /** 0208 Abstract base class for unstructured header fields 0209 (e.g. "Subject", "Comment", "Content-description"). 0210 0211 Features: Decodes the header according to RFC2047, incl. RFC2231 0212 extensions to encoded-words. 0213 0214 Subclasses need only re-implement @p const @p char* @p type(). 0215 */ 0216 0217 // known issues: 0218 // - uses old decodeRFC2047String function, instead of our own... 0219 0220 class KMIME_EXPORT Unstructured : public Base 0221 { 0222 //@cond PRIVATE 0223 kmime_mk_dptr_ctor(Unstructured) 0224 //@endcond 0225 public: 0226 Unstructured(); 0227 ~Unstructured() override; 0228 0229 using Base::from7BitString; 0230 void from7BitString(const QByteArray &s) override; 0231 QByteArray as7BitString(bool withHeaderType = true) const override; 0232 0233 void fromUnicodeString(const QString &s, const QByteArray &b) override; 0234 QString asUnicodeString() const override; 0235 0236 void clear() override; 0237 0238 bool isEmpty() const override; 0239 0240 private: 0241 Q_DECLARE_PRIVATE(Unstructured) 0242 }; 0243 0244 class StructuredPrivate; 0245 0246 /** 0247 @brief 0248 Base class for structured header fields. 0249 0250 This is the base class for all structured header fields. 0251 It contains parsing methods for all basic token types found in rfc2822. 0252 0253 @section Parsing 0254 0255 At the basic level, there are tokens & tspecials (rfc2045), 0256 atoms & specials, quoted-strings, domain-literals (all rfc822) and 0257 encoded-words (rfc2047). 0258 0259 As a special token, we have the comment. It is one of the basic 0260 tokens defined in rfc822, but it's parsing relies in part on the 0261 basic token parsers (e.g. comments may contain encoded-words). 0262 Also, most upper-level parsers (notably those for phrase and 0263 dot-atom) choose to ignore any comment when parsing. 0264 0265 Then there are the real composite tokens, which are made up of one 0266 or more of the basic tokens (and semantically invisible comments): 0267 phrases (rfc822 with rfc2047) and dot-atoms (rfc2822). 0268 0269 This finishes the list of supported token types. Subclasses will 0270 provide support for more higher-level tokens, where necessary, 0271 using these parsers. 0272 0273 @author Marc Mutz <mutz@kde.org> 0274 */ 0275 0276 class KMIME_EXPORT Structured : public Base 0277 { 0278 public: 0279 Structured(); 0280 ~Structured() override; 0281 0282 void from7BitString(const char *s, size_t len) override; 0283 void from7BitString(const QByteArray &s) override; 0284 QString asUnicodeString() const override; 0285 void fromUnicodeString(const QString &s, const QByteArray &b) override; 0286 0287 protected: 0288 /** 0289 This method parses the raw header and needs to be implemented in 0290 every sub-class. 0291 0292 @param scursor Pointer to the start of the data still to parse. 0293 @param send Pointer to the end of the data. 0294 @param isCRLF true if input string is terminated with a CRLF. 0295 */ 0296 virtual bool parse(const char *&scursor, const char *const send, 0297 bool isCRLF = false) = 0; 0298 0299 //@cond PRIVATE 0300 kmime_mk_dptr_ctor(Structured) 0301 //@endcond 0302 0303 private: 0304 Q_DECLARE_PRIVATE(Structured) 0305 }; 0306 0307 class AddressPrivate; 0308 0309 /** 0310 Base class for all address related headers. 0311 */ 0312 class KMIME_EXPORT Address : public Structured 0313 { 0314 public: 0315 Address(); 0316 ~Address() override; 0317 protected: 0318 //@cond PRIVATE 0319 kmime_mk_dptr_ctor(Address) 0320 //@endcond 0321 private: 0322 Q_DECLARE_PRIVATE(Address) 0323 }; 0324 0325 class MailboxListPrivate; 0326 0327 /** 0328 Base class for headers that deal with (possibly multiple) 0329 addresses, but don't allow groups. 0330 0331 @see RFC 2822, section 3.4 0332 */ 0333 class KMIME_EXPORT MailboxList : public Address 0334 { 0335 //@cond PRIVATE 0336 kmime_mk_trivial_ctor(MailboxList) 0337 kmime_mk_dptr_ctor(MailboxList) 0338 //@endcond 0339 public: 0340 QByteArray as7BitString(bool withHeaderType = true) const override; 0341 void fromUnicodeString(const QString &s, const QByteArray &b) override; 0342 QString asUnicodeString() const override; 0343 0344 void clear() override; 0345 bool isEmpty() const override; 0346 0347 /** 0348 Adds an address to this header. 0349 0350 @param mbox A Mailbox object specifying the address. 0351 */ 0352 void addAddress(const Types::Mailbox &mbox); 0353 0354 /** 0355 Adds an address to this header. 0356 @param address The actual email address, with or without angle brackets. 0357 @param displayName An optional name associated with the address. 0358 */ 0359 void addAddress(const QByteArray &address, 0360 const QString &displayName = QString()); 0361 0362 /** 0363 Returns a list of all addresses in this header, regardless of groups. 0364 */ 0365 QList<QByteArray> addresses() const; 0366 0367 /** 0368 Returns a list of all display names associated with the addresses in 0369 this header. The address is added for addresses that do not have 0370 a display name. 0371 */ 0372 QStringList displayNames() const; 0373 0374 /** 0375 Returns a single string for user-facing display of this mailbox list. 0376 This is equivalent to displayNames().join(", "). 0377 @since 5.14 0378 */ 0379 QString displayString() const; 0380 0381 /** 0382 Returns a list of mailboxes listed in this header. 0383 */ 0384 Types::Mailbox::List mailboxes() const; 0385 0386 protected: 0387 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0388 0389 private: 0390 Q_DECLARE_PRIVATE(MailboxList) 0391 }; 0392 0393 class SingleMailboxPrivate; 0394 0395 /** 0396 Base class for headers that deal with exactly one mailbox 0397 (e.g. Sender). 0398 */ 0399 class KMIME_EXPORT SingleMailbox : public MailboxList 0400 { 0401 //@cond PRIVATE 0402 kmime_mk_trivial_ctor(SingleMailbox) 0403 //@endcond 0404 protected: 0405 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0406 private: 0407 Q_DECLARE_PRIVATE(SingleMailbox) 0408 }; 0409 0410 class AddressListPrivate; 0411 0412 /** 0413 Base class for headers that deal with (possibly multiple) 0414 addresses, allowing groups. 0415 0416 Note: Groups are parsed but not represented in the API yet. All addresses in 0417 groups are listed as if they would not be part of a group. 0418 0419 @todo Add API for groups? 0420 0421 @see RFC 2822, section 3.4 0422 */ 0423 class KMIME_EXPORT AddressList : public Address 0424 { 0425 //@cond PRIVATE 0426 kmime_mk_trivial_ctor(AddressList) 0427 kmime_mk_dptr_ctor(AddressList) 0428 //@endcond 0429 public: 0430 QByteArray as7BitString(bool withHeaderType = true) const override; 0431 void fromUnicodeString(const QString &s, const QByteArray &b) override; 0432 QString asUnicodeString() const override; 0433 0434 void clear() override; 0435 bool isEmpty() const override; 0436 0437 /** 0438 Adds an address to this header. 0439 0440 @param mbox A Mailbox object specifying the address. 0441 */ 0442 void addAddress(const Types::Mailbox &mbox); 0443 0444 /** 0445 Adds an address to this header. 0446 @param address The actual email address, with or without angle brackets. 0447 @param displayName An optional name associated with the address. 0448 */ 0449 void addAddress(const QByteArray &address, const QString &displayName = QString()); 0450 0451 /** 0452 Returns a list of all addresses in this header, regardless of groups. 0453 */ 0454 QList<QByteArray> addresses() const; 0455 0456 /** 0457 Returns a list of all display names associated with the addresses in this header. 0458 The address is added for addresses that don't have a display name. 0459 */ 0460 QStringList displayNames() const; 0461 0462 /** 0463 Returns a single string for user-facing display of this address list. 0464 This is equivalent to displayNames().join(", "). 0465 @since 5.14 0466 */ 0467 QString displayString() const; 0468 0469 /** 0470 Returns a list of mailboxes listed in this header. 0471 */ 0472 Types::Mailbox::List mailboxes() const; 0473 0474 protected: 0475 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0476 0477 private: 0478 Q_DECLARE_PRIVATE(AddressList) 0479 }; 0480 0481 class IdentPrivate; 0482 0483 /** 0484 Base class for headers which deal with a list of msg-id's. 0485 0486 @see RFC 2822, section 3.6.4 0487 */ 0488 class KMIME_EXPORT Ident : public Address 0489 { 0490 //@cond PRIVATE 0491 kmime_mk_trivial_ctor(Ident) 0492 kmime_mk_dptr_ctor(Ident) 0493 //@endcond 0494 public: 0495 QByteArray as7BitString(bool withHeaderType = true) const override; 0496 void clear() override; 0497 bool isEmpty() const override; 0498 0499 /** 0500 Initialize this identifier Copy the data from 0501 */ 0502 void fromIdent(const Ident* ident); 0503 0504 /** 0505 Returns the list of identifiers contained in this header. 0506 Note: 0507 - Identifiers are not enclosed in angle-brackets. 0508 - Identifiers are listed in the same order as in the header. 0509 */ 0510 QList<QByteArray> identifiers() const; 0511 0512 /** 0513 Appends a new identifier to this header. 0514 @param id The identifier to append, with or without angle-brackets. 0515 */ 0516 void appendIdentifier(const QByteArray &id); 0517 0518 protected: 0519 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0520 0521 private: 0522 Q_DECLARE_PRIVATE(Ident) 0523 }; 0524 0525 class SingleIdentPrivate; 0526 0527 /** 0528 Base class for headers which deal with a single msg-id. 0529 0530 @see RFC 2822, section 3.6.4 0531 */ 0532 class KMIME_EXPORT SingleIdent : public Ident 0533 { 0534 //@cond PRIVATE 0535 kmime_mk_trivial_ctor(SingleIdent) 0536 kmime_mk_dptr_ctor(SingleIdent) 0537 //@endcond 0538 public: 0539 /** 0540 Returns the identifier contained in this header. 0541 Note: The identifiers is not enclosed in angle-brackets. 0542 */ 0543 QByteArray identifier() const; 0544 0545 /** 0546 Sets the identifier. 0547 @param id The new identifier with or without angle-brackets. 0548 */ 0549 void setIdentifier(const QByteArray &id); 0550 0551 protected: 0552 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0553 0554 private: 0555 Q_DECLARE_PRIVATE(SingleIdent) 0556 }; 0557 0558 class TokenPrivate; 0559 0560 /** 0561 Base class for headers which deal with a single atom. 0562 */ 0563 class KMIME_EXPORT Token : public Structured 0564 { 0565 //@cond PRIVATE 0566 kmime_mk_trivial_ctor(Token) 0567 kmime_mk_dptr_ctor(Token) 0568 //@endcond 0569 public: 0570 QByteArray as7BitString(bool withHeaderType = true) const override; 0571 void clear() override; 0572 bool isEmpty() const override; 0573 0574 /** 0575 Returns the token. 0576 */ 0577 QByteArray token() const; 0578 0579 /** 0580 Sets the token to @p t, 0581 */ 0582 void setToken(const QByteArray &t); 0583 0584 protected: 0585 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0586 0587 private: 0588 Q_DECLARE_PRIVATE(Token) 0589 }; 0590 0591 class PhraseListPrivate; 0592 0593 /** 0594 Base class for headers containing a list of phrases. 0595 */ 0596 class KMIME_EXPORT PhraseList : public Structured 0597 { 0598 //@cond PRIVATE 0599 kmime_mk_trivial_ctor(PhraseList) 0600 //@endcond 0601 public: 0602 QByteArray as7BitString(bool withHeaderType = true) const override; 0603 QString asUnicodeString() const override; 0604 void clear() override; 0605 bool isEmpty() const override; 0606 0607 /** 0608 Returns the list of phrases contained in this header. 0609 */ 0610 QStringList phrases() const; 0611 0612 protected: 0613 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0614 0615 private: 0616 Q_DECLARE_PRIVATE(PhraseList) 0617 }; 0618 0619 class DotAtomPrivate; 0620 0621 /** 0622 Base class for headers containing a dot atom. 0623 */ 0624 class KMIME_EXPORT DotAtom : public Structured 0625 { 0626 //@cond PRIVATE 0627 kmime_mk_trivial_ctor(DotAtom) 0628 //@endcond 0629 public: 0630 QByteArray as7BitString(bool withHeaderType = true) const override; 0631 QString asUnicodeString() const override; 0632 void clear() override; 0633 bool isEmpty() const override; 0634 0635 protected: 0636 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0637 0638 private: 0639 Q_DECLARE_PRIVATE(DotAtom) 0640 }; 0641 0642 class ParametrizedPrivate; 0643 0644 /** 0645 Base class for headers containing a parameter list such as "Content-Type". 0646 */ 0647 class KMIME_EXPORT Parametrized : public Structured 0648 { 0649 //@cond PRIVATE 0650 kmime_mk_trivial_ctor(Parametrized) 0651 kmime_mk_dptr_ctor(Parametrized) 0652 //@endcond 0653 public: 0654 QByteArray as7BitString(bool withHeaderType = true) const override; 0655 0656 bool isEmpty() const override; 0657 void clear() override; 0658 0659 //FIXME: Shouldn't the parameter keys be QByteArray and not QStrings? Only the values can be 0660 // non-ascii! 0661 0662 /** 0663 Returns the value of the specified parameter. 0664 @param key The parameter name. 0665 */ 0666 QString parameter(const QString &key) const; 0667 0668 /** 0669 @param key the key of the parameter to check for 0670 @return true if a parameter with the given @p key exists. 0671 @since 4.5 0672 */ 0673 bool hasParameter(const QString &key) const; 0674 0675 /** 0676 Sets the parameter @p key to @p value. 0677 @param key The parameter name. 0678 @param value The new value for @p key. 0679 */ 0680 void setParameter(const QString &key, const QString &value); 0681 0682 protected: 0683 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0684 0685 private: 0686 Q_DECLARE_PRIVATE(Parametrized) 0687 }; 0688 0689 } // namespace Generics 0690 0691 // 0692 // 0693 // INCOMPATIBLE, GSTRUCTURED-BASED FIELDS: 0694 // 0695 // 0696 0697 class ReturnPathPrivate; 0698 0699 /** 0700 Represents the Return-Path header field. 0701 0702 @see RFC 2822, section 3.6.7 0703 */ 0704 class KMIME_EXPORT ReturnPath : public Generics::Address 0705 { 0706 //@cond PRIVATE 0707 kmime_mk_trivial_ctor_with_name(ReturnPath) 0708 //@endcond 0709 public: 0710 QByteArray as7BitString(bool withHeaderType = true) const override; 0711 void clear() override; 0712 bool isEmpty() const override; 0713 0714 protected: 0715 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0716 0717 private: 0718 Q_DECLARE_PRIVATE(ReturnPath) 0719 }; 0720 0721 // Address et al.: 0722 0723 // rfc(2)822 headers: 0724 /** 0725 Represent a "From" header. 0726 0727 @see RFC 2822, section 3.6.2. 0728 */ 0729 class KMIME_EXPORT From : public Generics::MailboxList 0730 { 0731 kmime_mk_trivial_ctor_with_name(From) 0732 }; 0733 0734 /** 0735 Represents a "Sender" header. 0736 0737 @see RFC 2822, section 3.6.2. 0738 */ 0739 class KMIME_EXPORT Sender : public Generics::SingleMailbox 0740 { 0741 kmime_mk_trivial_ctor_with_name(Sender) 0742 }; 0743 0744 /** 0745 Represents a "To" header. 0746 0747 @see RFC 2822, section 3.6.3. 0748 */ 0749 class KMIME_EXPORT To : public Generics::AddressList 0750 { 0751 kmime_mk_trivial_ctor_with_name(To) 0752 }; 0753 0754 /** 0755 Represents a "Cc" header. 0756 0757 @see RFC 2822, section 3.6.3. 0758 */ 0759 class KMIME_EXPORT Cc : public Generics::AddressList 0760 { 0761 kmime_mk_trivial_ctor_with_name(Cc) 0762 }; 0763 0764 /** 0765 Represents a "Bcc" header. 0766 0767 @see RFC 2822, section 3.6.3. 0768 */ 0769 class KMIME_EXPORT Bcc : public Generics::AddressList 0770 { 0771 kmime_mk_trivial_ctor_with_name(Bcc) 0772 }; 0773 0774 /** 0775 Represents a "ReplyTo" header. 0776 0777 @see RFC 2822, section 3.6.2. 0778 */ 0779 class KMIME_EXPORT ReplyTo : public Generics::AddressList 0780 { 0781 kmime_mk_trivial_ctor_with_name(ReplyTo) 0782 }; 0783 0784 class MailCopiesToPrivate; 0785 0786 /** 0787 Represents a "Mail-Copies-To" header. 0788 0789 @see http://www.newsreaders.com/misc/mail-copies-to.html 0790 */ 0791 class KMIME_EXPORT MailCopiesTo : public Generics::AddressList 0792 { 0793 //@cond PRIVATE 0794 kmime_mk_trivial_ctor_with_name(MailCopiesTo) 0795 //@endcond 0796 public: 0797 QByteArray as7BitString(bool withHeaderType = true) const override; 0798 QString asUnicodeString() const override; 0799 0800 void clear() override; 0801 bool isEmpty() const override; 0802 0803 /** 0804 Returns true if a mail copy was explicitly requested. 0805 */ 0806 bool alwaysCopy() const; 0807 0808 /** 0809 Sets the header to "poster". 0810 */ 0811 void setAlwaysCopy(); 0812 0813 /** 0814 Returns true if a mail copy was explicitly denied. 0815 */ 0816 bool neverCopy() const; 0817 0818 /** 0819 Sets the header to "never". 0820 */ 0821 void setNeverCopy(); 0822 0823 protected: 0824 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0825 0826 private: 0827 Q_DECLARE_PRIVATE(MailCopiesTo) 0828 }; 0829 0830 class ContentTransferEncodingPrivate; 0831 0832 /** 0833 Represents a "Content-Transfer-Encoding" header. 0834 0835 @see RFC 2045, section 6. 0836 */ 0837 class KMIME_EXPORT ContentTransferEncoding : public Generics::Token 0838 { 0839 //@cond PRIVATE 0840 kmime_mk_trivial_ctor_with_name(ContentTransferEncoding) 0841 //@endcond 0842 public: 0843 void clear() override; 0844 0845 /** 0846 Returns the encoding specified in this header. 0847 */ 0848 contentEncoding encoding() const; 0849 0850 /** 0851 Sets the encoding to @p e. 0852 */ 0853 void setEncoding(contentEncoding e); 0854 0855 /** 0856 Returns whether the Content containing this header is already decoded. 0857 */ 0858 bool isDecoded() const; 0859 0860 /** 0861 Set whether the Content containing this header is already decoded. 0862 For instance, if you fill your Content with already-encoded base64 data, 0863 you will want to setDecoded( false ). 0864 @param decoded if @c true the content is already decoded 0865 */ 0866 void setDecoded(bool isDecoded = true); 0867 0868 /** 0869 Returns whether the Content containing this header needs to be encoded 0870 (i.e., if decoded() is true and encoding() is base64 or quoted-printable). 0871 */ 0872 bool needToEncode() const; 0873 0874 protected: 0875 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0876 0877 private: 0878 Q_DECLARE_PRIVATE(ContentTransferEncoding) 0879 }; 0880 0881 /** 0882 Represents a "Keywords" header. 0883 0884 @see RFC 2822, section 3.6.5. 0885 */ 0886 class KMIME_EXPORT Keywords : public Generics::PhraseList 0887 { 0888 kmime_mk_trivial_ctor_with_name(Keywords) 0889 }; 0890 0891 // DotAtom: 0892 0893 /** 0894 Represents a "MIME-Version" header. 0895 0896 @see RFC 2045, section 4. 0897 */ 0898 class KMIME_EXPORT MIMEVersion : public Generics::DotAtom 0899 { 0900 kmime_mk_trivial_ctor_with_name(MIMEVersion) 0901 }; 0902 0903 // Ident: 0904 0905 /** 0906 Represents a "Message-ID" header. 0907 0908 @see RFC 2822, section 3.6.4. 0909 */ 0910 class KMIME_EXPORT MessageID : public Generics::SingleIdent 0911 { 0912 //@cond PRIVATE 0913 kmime_mk_trivial_ctor_with_name(MessageID) 0914 //@endcond 0915 public: 0916 /** 0917 Generate a message identifier. 0918 @param fqdn A fully qualified domain name. 0919 */ 0920 void generate(const QByteArray &fqdn); 0921 }; 0922 0923 class ContentIDPrivate; 0924 0925 /** 0926 Represents a "Content-ID" header. 0927 */ 0928 class KMIME_EXPORT ContentID : public Generics::SingleIdent 0929 { 0930 //@cond PRIVATE 0931 kmime_mk_trivial_ctor_with_name(ContentID) 0932 kmime_mk_dptr_ctor(ContentID) 0933 //@endcond 0934 0935 protected: 0936 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 0937 private: 0938 Q_DECLARE_PRIVATE(ContentID) 0939 }; 0940 0941 /** 0942 Represents a "Supersedes" header. 0943 */ 0944 class KMIME_EXPORT Supersedes : public Generics::SingleIdent 0945 { 0946 kmime_mk_trivial_ctor_with_name(Supersedes) 0947 }; 0948 0949 /** 0950 Represents a "In-Reply-To" header. 0951 0952 @see RFC 2822, section 3.6.4. 0953 */ 0954 class KMIME_EXPORT InReplyTo : public Generics::Ident 0955 { 0956 kmime_mk_trivial_ctor_with_name(InReplyTo) 0957 }; 0958 0959 /** 0960 Represents a "References" header. 0961 0962 @see RFC 2822, section 3.6.4. 0963 */ 0964 class KMIME_EXPORT References : public Generics::Ident 0965 { 0966 kmime_mk_trivial_ctor_with_name(References) 0967 }; 0968 0969 class ContentTypePrivate; 0970 0971 /** 0972 Represents a "Content-Type" header. 0973 0974 @see RFC 2045, section 5. 0975 */ 0976 class KMIME_EXPORT ContentType : public Generics::Parametrized 0977 { 0978 //@cond PRIVATE 0979 kmime_mk_trivial_ctor_with_name(ContentType) 0980 //@endcond 0981 public: 0982 QByteArray as7BitString(bool withHeaderType = true) const override; 0983 void clear() override; 0984 bool isEmpty() const override; 0985 0986 /** 0987 Returns the mimetype. 0988 */ 0989 QByteArray mimeType() const; 0990 0991 /** 0992 Returns the media type (first part of the mimetype). 0993 */ 0994 0995 QByteArray mediaType() const; 0996 0997 /** 0998 Returns the mime sub-type (second part of the mimetype). 0999 */ 1000 QByteArray subType() const; 1001 1002 /** 1003 Sets the mimetype. 1004 @param mimeType The new mimetype. 1005 */ 1006 void setMimeType(const QByteArray &mimeType); 1007 1008 /** 1009 Tests if the media type equals @p mediatype. 1010 */ 1011 bool isMediatype(const char *mediatype) const; 1012 1013 /** 1014 Tests if the mime sub-type equals @p subtype. 1015 */ 1016 bool isSubtype(const char *subtype) const; 1017 1018 /** 1019 Tests if the mime type is @p mimeType. 1020 */ 1021 bool isMimeType(const char *mimeType) const; 1022 1023 /** 1024 Returns true if the associated MIME entity is a text. 1025 */ 1026 bool isText() const; 1027 1028 /** 1029 Returns true if the associated MIME entity is a plain text. 1030 */ 1031 bool isPlainText() const; 1032 1033 /** 1034 Returns true if the associated MIME entity is a HTML file. 1035 */ 1036 bool isHTMLText() const; 1037 1038 /** 1039 Returns true if the associated MIME entity is an image. 1040 */ 1041 bool isImage() const; 1042 1043 /** 1044 Returns true if the associated MIME entity is a multipart container. 1045 */ 1046 bool isMultipart() const; 1047 1048 /** 1049 Returns true if the associated MIME entity contains partial data. 1050 @see partialNumber(), partialCount() 1051 */ 1052 bool isPartial() const; 1053 1054 /** 1055 Returns the charset for the associated MIME entity. 1056 */ 1057 QByteArray charset() const; 1058 1059 /** 1060 Sets the charset. 1061 */ 1062 void setCharset(const QByteArray &s); 1063 1064 /** 1065 Returns the boundary (for multipart containers). 1066 */ 1067 QByteArray boundary() const; 1068 1069 /** 1070 Sets the multipart container boundary. 1071 */ 1072 void setBoundary(const QByteArray &s); 1073 1074 /** 1075 Returns the name of the associated MIME entity. 1076 */ 1077 QString name() const; 1078 1079 /** 1080 Sets the name to @p s using charset @p cs. 1081 */ 1082 void setName(const QString &s, const QByteArray &cs); 1083 1084 /** 1085 Returns the identifier of the associated MIME entity. 1086 */ 1087 QByteArray id() const; 1088 1089 /** 1090 Sets the identifier. 1091 */ 1092 void setId(const QByteArray &s); 1093 1094 /** 1095 Returns the position of this part in a multi-part set. 1096 @see isPartial(), partialCount() 1097 */ 1098 int partialNumber() const; 1099 1100 /** 1101 Returns the total number of parts in a multi-part set. 1102 @see isPartial(), partialNumber() 1103 */ 1104 int partialCount() const; 1105 1106 /** 1107 Sets parameters of a partial MIME entity. 1108 @param total The total number of entities in the multi-part set. 1109 @param number The number of this entity in a multi-part set. 1110 */ 1111 void setPartialParams(int total, int number); 1112 1113 protected: 1114 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 1115 1116 private: 1117 Q_DECLARE_PRIVATE(ContentType) 1118 }; 1119 1120 class ContentDispositionPrivate; 1121 1122 /** 1123 Represents a "Content-Disposition" header. 1124 1125 @see RFC 2183 1126 */ 1127 class KMIME_EXPORT ContentDisposition : public Generics::Parametrized 1128 { 1129 //@cond PRIVATE 1130 kmime_mk_trivial_ctor_with_name(ContentDisposition) 1131 //@endcond 1132 public: 1133 QByteArray as7BitString(bool withHeaderType = true) const override; 1134 bool isEmpty() const override; 1135 void clear() override; 1136 1137 /** 1138 Returns the content disposition. 1139 */ 1140 contentDisposition disposition() const; 1141 1142 /** 1143 Sets the content disposition. 1144 @param disp The new content disposition. 1145 */ 1146 void setDisposition(contentDisposition disp); 1147 1148 /** 1149 Returns the suggested filename for the associated MIME part. 1150 This is just a convenience function, it is equivalent to calling 1151 parameter( "filename" ); 1152 */ 1153 QString filename() const; 1154 1155 /** 1156 Sets the suggested filename for the associated MIME part. 1157 This is just a convenience function, it is equivalent to calling 1158 setParameter( "filename", filename ); 1159 @param filename The filename. 1160 */ 1161 void setFilename(const QString &filename); 1162 1163 protected: 1164 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 1165 1166 private: 1167 Q_DECLARE_PRIVATE(ContentDisposition) 1168 }; 1169 1170 // 1171 // 1172 // COMPATIBLE GUNSTRUCTURED-BASED FIELDS: 1173 // 1174 // 1175 1176 class GenericPrivate; 1177 1178 /** 1179 Represents an arbitrary header, that can contain any header-field. 1180 Adds a type over Unstructured. 1181 @see Unstructured 1182 */ 1183 class KMIME_EXPORT Generic : public Generics::Unstructured 1184 { 1185 public: 1186 Generic(); 1187 Generic(const char *t, int len = -1); 1188 ~Generic() override; 1189 1190 void clear() override; 1191 1192 bool isEmpty() const override; 1193 1194 const char *type() const override; 1195 1196 void setType(const char *type, int len = -1); 1197 1198 private: 1199 Q_DECLARE_PRIVATE(Generic) 1200 }; 1201 1202 /** 1203 Represents a "Subject" header. 1204 1205 @see RFC 2822, section 3.6.5. 1206 */ 1207 class KMIME_EXPORT Subject : public Generics::Unstructured 1208 { 1209 //@cond PRIVATE 1210 kmime_mk_trivial_ctor_with_name(Subject) 1211 //@endcond 1212 }; 1213 1214 /** 1215 Represents a "Organization" header. 1216 */ 1217 class KMIME_EXPORT Organization : public Generics::Unstructured 1218 { 1219 kmime_mk_trivial_ctor_with_name(Organization) 1220 }; 1221 1222 /** 1223 Represents a "Content-Description" header. 1224 */ 1225 class KMIME_EXPORT ContentDescription : public Generics::Unstructured 1226 { 1227 kmime_mk_trivial_ctor_with_name(ContentDescription) 1228 }; 1229 1230 /** 1231 Represents a "Content-Location" header. 1232 @since 4.2 1233 */ 1234 class KMIME_EXPORT ContentLocation : public Generics::Unstructured 1235 { 1236 kmime_mk_trivial_ctor_with_name(ContentLocation) 1237 }; 1238 1239 class ControlPrivate; 1240 1241 /** 1242 Represents a "Control" header. 1243 1244 @see RFC 1036, section 3. 1245 */ 1246 class KMIME_EXPORT Control : public Generics::Structured 1247 { 1248 //@cond PRIVATE 1249 kmime_mk_trivial_ctor_with_name(Control) 1250 //@endcond 1251 public: 1252 QByteArray as7BitString(bool withHeaderType = true) const override; 1253 void clear() override; 1254 bool isEmpty() const override; 1255 1256 /** 1257 Returns the control message type. 1258 */ 1259 QByteArray controlType() const; 1260 1261 /** 1262 Returns the control message parameter. 1263 */ 1264 QByteArray parameter() const; 1265 1266 /** 1267 Returns true if this is a cancel control message. 1268 @see RFC 1036, section 3.1. 1269 */ 1270 bool isCancel() const; 1271 1272 /** 1273 Changes this header into a cancel control message for the given message-id. 1274 @param msgid The message-id of the article that should be canceled. 1275 */ 1276 void setCancel(const QByteArray &msgid); 1277 1278 protected: 1279 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 1280 1281 private: 1282 Q_DECLARE_PRIVATE(Control) 1283 }; 1284 1285 class DatePrivate; 1286 1287 /** 1288 Represents a "Date" header. 1289 1290 @see RFC 2822, section 3.3. 1291 */ 1292 class KMIME_EXPORT Date : public Generics::Structured 1293 { 1294 //@cond PRIVATE 1295 kmime_mk_trivial_ctor_with_name(Date) 1296 //@endcond 1297 public: 1298 QByteArray as7BitString(bool withHeaderType = true) const override; 1299 void clear() override; 1300 bool isEmpty() const override; 1301 1302 /** 1303 Returns the date contained in this header. 1304 */ 1305 QDateTime dateTime() const; 1306 1307 /** 1308 Sets the date. 1309 */ 1310 void setDateTime(const QDateTime &dt); 1311 1312 /** 1313 Returns the age of the message. 1314 */ 1315 int ageInDays() const; 1316 1317 protected: 1318 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 1319 1320 private: 1321 Q_DECLARE_PRIVATE(Date) 1322 }; 1323 1324 class NewsgroupsPrivate; 1325 1326 /** 1327 Represents a "Newsgroups" header. 1328 1329 @see RFC 1036, section 2.1.3. 1330 */ 1331 class KMIME_EXPORT Newsgroups : public Generics::Structured 1332 { 1333 //@cond PRIVATE 1334 kmime_mk_trivial_ctor_with_name(Newsgroups) 1335 //@endcond 1336 public: 1337 QByteArray as7BitString(bool withHeaderType = true) const override; 1338 void fromUnicodeString(const QString &s, const QByteArray &b) override; 1339 QString asUnicodeString() const override; 1340 void clear() override; 1341 bool isEmpty() const override; 1342 1343 /** 1344 Returns the list of newsgroups. 1345 */ 1346 QList<QByteArray> groups() const; 1347 1348 /** 1349 Sets the newsgroup list. 1350 */ 1351 void setGroups(const QList<QByteArray> &groups); 1352 1353 /** 1354 Returns true if this message has been cross-posted, i.e. if it has been 1355 posted to multiple groups. 1356 */ 1357 bool isCrossposted() const; 1358 1359 protected: 1360 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 1361 1362 private: 1363 Q_DECLARE_PRIVATE(Newsgroups) 1364 }; 1365 1366 /** 1367 Represents a "Followup-To" header. 1368 1369 @see RFC 1036, section 2.2.3. 1370 */ 1371 class KMIME_EXPORT FollowUpTo : public Newsgroups 1372 { 1373 //@cond PRIVATE 1374 kmime_mk_trivial_ctor_with_name(FollowUpTo) 1375 //@endcond 1376 }; 1377 1378 class LinesPrivate; 1379 1380 /** 1381 Represents a "Lines" header. 1382 1383 @see RFC 1036, section 2.2.12. 1384 */ 1385 class KMIME_EXPORT Lines : public Generics::Structured 1386 { 1387 //@cond PRIVATE 1388 kmime_mk_trivial_ctor_with_name(Lines) 1389 //@endcond 1390 public: 1391 QByteArray as7BitString(bool withHeaderType = true) const override; 1392 QString asUnicodeString() const override; 1393 void clear() override; 1394 bool isEmpty() const override; 1395 1396 /** 1397 Returns the number of lines, undefined if isEmpty() returns true. 1398 */ 1399 int numberOfLines() const; 1400 1401 /** 1402 Sets the number of lines to @p lines. 1403 */ 1404 void setNumberOfLines(int lines); 1405 1406 protected: 1407 bool parse(const char *&scursor, const char *const send, bool isCRLF = false) override; 1408 1409 private: 1410 Q_DECLARE_PRIVATE(Lines) 1411 }; 1412 1413 /** 1414 Represents a "User-Agent" header. 1415 */ 1416 class KMIME_EXPORT UserAgent : public Generics::Unstructured 1417 { 1418 kmime_mk_trivial_ctor_with_name(UserAgent) 1419 }; 1420 1421 /** Creates a header based on @param type. If @param type is a known header type, 1422 * the right object type will be created, otherwise a null pointer is returned. */ 1423 KMIME_EXPORT Base *createHeader(const QByteArray &type); 1424 1425 } //namespace Headers 1426 1427 } //namespace KMime 1428 1429 // undefine code generation macros again 1430 #undef kmime_mk_trivial_ctor 1431 #undef kmime_mk_dptr_ctor 1432 #undef kmime_mk_trivial_ctor_with_name 1433 1434 Q_DECLARE_METATYPE(KMime::Headers::To*) 1435 Q_DECLARE_METATYPE(KMime::Headers::Cc*) 1436 Q_DECLARE_METATYPE(KMime::Headers::Bcc*) 1437