File indexing completed on 2024-03-24 16:53:08

0001 /*  -*- c++ -*-
0002     kmime_header_types.h
0003 
0004     KMime, the KDE Internet mail/usenet news message library.
0005     SPDX-FileCopyrightText: 2001-2002 Marc Mutz <mutz@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.0-or-later
0008 */
0009 
0010 #pragma once
0011 
0012 #include <QList>
0013 #include <QString>
0014 
0015 #include "kmime_export.h"
0016 
0017 namespace KMime
0018 {
0019 
0020 namespace Types
0021 {
0022 
0023 struct KMIME_EXPORT AddrSpec {
0024     QString asString() const;
0025     /*! This is the same as asString(), except it decodes IDNs for display */
0026     QString asPrettyString() const;
0027     bool isEmpty() const;
0028     QString localPart;
0029     QString domain;
0030 };
0031 using AddrSpecList = QList<AddrSpec>;
0032 
0033 /**
0034   Represents an (email address, display name) pair according RFC 2822,
0035   section 3.4.
0036 */
0037 class KMIME_EXPORT Mailbox
0038 {
0039 public:
0040   typedef QList<Mailbox> List;
0041 
0042   /**
0043     Returns a string representation of the email address, without
0044     the angle brackets.
0045   */
0046   [[nodiscard]] QByteArray address() const;
0047 
0048   [[nodiscard]] AddrSpec addrSpec() const;
0049 
0050   /**
0051     Returns the display name.
0052   */
0053   [[nodiscard]] QString name() const;
0054 
0055   /**
0056     Sets the email address.
0057   */
0058   void setAddress(const AddrSpec &addr);
0059 
0060   /**
0061     Sets the email address.
0062   */
0063   void setAddress(const QByteArray &addr);
0064 
0065   /**
0066     Sets the name.
0067   */
0068   void setName(const QString &name);
0069 
0070   /**
0071     Sets the name based on a 7bit encoded string.
0072   */
0073   void setNameFrom7Bit(const QByteArray &name,
0074                        const QByteArray &defaultCharset = QByteArray());
0075 
0076   /**
0077     Returns true if this mailbox has an address.
0078   */
0079   [[nodiscard]] bool hasAddress() const;
0080 
0081   /**
0082     Returns true if this mailbox has a display name.
0083   */
0084   [[nodiscard]] bool hasName() const;
0085 
0086   /**
0087    * Describes how display names should be quoted
0088    * @since 4.5
0089    */
0090   // AK_REVIEW: remove this enum
0091   enum Quoting {
0092     QuoteNever, ///< Don't quote display names at all. Such an unquoted display
0093                 ///< name can not
0094     ///  be machine-processed anymore in some cases, for example when it
0095     ///  contains commas, like in "Lastname, Firstname".
0096     QuoteWhenNecessary, ///< Only quote display names when they contain
0097                         ///< characters that need to be
0098     ///  quoted, like commas or quote signs.
0099     QuoteAlways ///< Always quote the display name
0100   };
0101 
0102   /**
0103    * Overloaded method that gives more control over the quoting of the display
0104    * name
0105    * @param quoting describes how the display name should be quoted
0106    * @since 4.5
0107    */
0108   [[nodiscard]] QString prettyAddress(Quoting quoting = QuoteNever) const;
0109 
0110   /**
0111     Parses the given unicode string.
0112   */
0113   void fromUnicodeString(const QString &s);
0114 
0115   /**
0116     Parses the given 7bit encoded string.
0117   */
0118   void from7BitString(const QByteArray &s);
0119 
0120   /**
0121     Returns a 7bit transport encoded representation of this mailbox.
0122 
0123     @param encCharset The charset used for encoding.
0124   */
0125   [[nodiscard]] QByteArray as7BitString(const QByteArray &encCharset) const;
0126 
0127   /**
0128    * Returns a list of mailboxes from an unicode string.
0129    *
0130    * @since 5.14
0131    */
0132   [[nodiscard]] static QList<Mailbox> listFromUnicodeString(const QString &s);
0133 
0134   /**
0135    * Returns a list of mailboxes from an encoded 7bit string.
0136    *
0137    * @since 5.14
0138    */
0139   [[nodiscard]] static QList<Mailbox> listFrom7BitString(const QByteArray &s);
0140 
0141   /**
0142    * Returns a unicode string representing the given list of mailboxes.
0143    *
0144    * @since 5.15
0145    */
0146   [[nodiscard]] static QString
0147   listToUnicodeString(const QList<Mailbox> &mailboxes);
0148 
0149 private:
0150     QString mDisplayName;
0151     AddrSpec mAddrSpec;
0152 };
0153 
0154 typedef QList<Mailbox> MailboxList;
0155 
0156 struct KMIME_EXPORT Address {
0157     QString displayName;
0158     MailboxList mailboxList;
0159 };
0160 typedef QList<Address> AddressList;
0161 
0162 } // namespace KMime::Types
0163 
0164 } // namespace KMime
0165 
0166 Q_DECLARE_TYPEINFO(KMime::Types::Mailbox, Q_RELOCATABLE_TYPE);
0167 Q_DECLARE_TYPEINFO(KMime::Types::Address, Q_RELOCATABLE_TYPE);
0168 Q_DECLARE_TYPEINFO(KMime::Types::AddrSpec, Q_RELOCATABLE_TYPE);
0169 
0170