File indexing completed on 2022-10-04 16:37:47

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