1 /* SPDX-FileCopyrightText: 2009 Thomas McGuire <mcguire@kde.org> 2 3 SPDX-License-Identifier: GPL-2.0-only OR GPL-3.0-only OR LicenseRef-KDE-Accepted-GPL 4 */ 5 #pragma once 6 7 #include "kmime/kmime_header_parsing.h" 8 #include "kmime/kmime_message.h" 9 #include "messagecore_export.h" 10 11 #include <QStringList> 12 #include <QVector> 13 class QUrl; 14 15 namespace KMime 16 { 17 namespace Types 18 { 19 struct Address; 20 using AddressList = QVector<Address>; 21 class Mailbox; 22 } 23 namespace Headers 24 { 25 namespace Generics 26 { 27 class MailboxList; 28 class AddressList; 29 } 30 } 31 } 32 33 namespace MessageCore 34 { 35 /** 36 * This namespace contain helper functions for string manipulation 37 */ 38 namespace StringUtil 39 { 40 /** 41 * Parses a mailto: url and extracts the information in the QMap (field name as key). 42 */ 43 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QVector<QPair<QString, QString>> parseMailtoUrl(const QUrl &url); 44 45 /** 46 * Strips the signature blocks from a message text. "-- " is considered as a signature block separator. 47 * 48 * @param message The message to remove the signature block from. 49 */ 50 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString stripSignature(const QString &message); 51 52 /** 53 * Splits the given address list @p text into separate addresses. 54 */ 55 Q_REQUIRED_RESULT MESSAGECORE_EXPORT KMime::Types::AddressList splitAddressField(const QByteArray &text); 56 57 /** 58 * Generates the Message-Id. It uses either the Message-Id @p suffix 59 * defined by the user or the given email address as suffix. The @p address 60 * must be given as addr-spec as defined in RFC 2822. 61 */ 62 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString generateMessageId(const QString &address, const QString &suffix); 63 64 /** 65 * Quotes the following characters which have a special meaning in HTML: 66 * '<' '>' '&' '"'. Additionally '\\n' is converted to "<br />" if 67 * @p removeLineBreaks is false. If @p removeLineBreaks is true, then 68 * '\\n' is removed. Last but not least '\\r' is removed. 69 */ 70 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString quoteHtmlChars(const QString &text, bool removeLineBreaks = false); 71 72 /** 73 * Removes all private header fields (e.g. *Status: and X-KMail-*) from the given @p message. 74 * if cleanUpHeader is false don't remove X-KMail-Identity and X-KMail-Dictionary which is useful when we want restore mail. 75 */ 76 MESSAGECORE_EXPORT void removePrivateHeaderFields(const KMime::Message::Ptr &message, bool cleanUpHeader = true); 77 78 /** 79 * Returns the @p message contents with the headers that should not be sent stripped off. 80 */ 81 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QByteArray asSendableString(const KMime::Message::Ptr &message); 82 83 /** 84 * Return the message header with the headers that should not be sent stripped off. 85 */ 86 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QByteArray headerAsSendableString(const KMime::Message::Ptr &message); 87 88 /** 89 * Used to determine if the visible part of the anchor contains 90 * only the name part and not the given emailAddr or the full address. 91 */ 92 enum Display { DisplayNameOnly, DisplayFullAddress }; 93 94 /** 95 * Used to determine if the address should be a link or not. 96 */ 97 enum Link { ShowLink, HideLink }; 98 99 /** 100 * Used to determine if the address field should be expandable/collapsible. 101 */ 102 enum AddressMode { ExpandableAddresses, FullAddresses }; 103 104 /** 105 * Converts the email address(es) to (a) nice HTML mailto: anchor(s). 106 * @p display determines if only the name part or the entire address should be returned. 107 * @p cssStyle a custom css template. 108 * @p link determines if the result should be a html link or not. 109 * @p expandable determines if a long list of addresses should be expandable or shown 110 * in full. 111 * @p fieldName the name that the divs should be based on if expandable is set to ExpanableAddesses. 112 * @p The number of addresses to show before collapsing the rest, if expandable is set to 113 * ExpandableAddresses. 114 */ 115 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString emailAddrAsAnchor(const KMime::Headers::Generics::MailboxList *mailboxList, 116 Display display = DisplayNameOnly, 117 const QString &cssStyle = QString(), 118 Link link = ShowLink, 119 AddressMode expandable = FullAddresses, 120 const QString &fieldName = QString(), 121 int collapseNumber = 4); 122 123 /** 124 * Same as above method, only for AddressList headers. 125 */ 126 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString emailAddrAsAnchor(const KMime::Headers::Generics::AddressList *addressList, 127 Display display = DisplayNameOnly, 128 const QString &cssStyle = QString(), 129 Link link = ShowLink, 130 AddressMode expandable = FullAddresses, 131 const QString &fieldName = QString(), 132 int collapseNumber = 4); 133 134 /** 135 * Same as the above, only for Mailbox::List types. 136 */ 137 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString emailAddrAsAnchor(const QVector<KMime::Types::Mailbox> &mailboxList, 138 Display display = DisplayNameOnly, 139 const QString &cssStyle = QString(), 140 Link link = ShowLink, 141 AddressMode expandable = FullAddresses, 142 const QString &fieldName = QString(), 143 int collapseNumber = 4); 144 145 /** 146 * Returns true if the given address is contained in the given address list. 147 */ 148 Q_REQUIRED_RESULT MESSAGECORE_EXPORT bool addressIsInAddressList(const QString &address, const QStringList &addresses); 149 150 /** 151 * Uses the hostname as domain part and tries to determine the real name 152 * from the entries in the password file. 153 */ 154 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString guessEmailAddressFromLoginName(const QString &userName); 155 156 /** 157 * Relayouts the given string so that the individual lines don't exceed the given 158 * maximal length. 159 * 160 * As the name of the function implies, it is smart, which means it deals with quoting 161 * correctly. This means if a line already starts with quote characters and needs to be 162 * broken, the same quote characters are prepended to the next line as well. 163 * 164 * This does _not_ add new quote characters in front of every line, that is the responsibility 165 * of the caller. 166 * 167 * @param message The string which it to be relayouted 168 * @param maxLineLength reformat text to be this amount of columns at maximum. Note that this 169 * also includes the trailing \n! 170 */ 171 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString smartQuote(const QString &message, int maxLineLength); 172 173 /** 174 * Convert quote wildcards into the final quote prefix. 175 * @param wildString the string to be converted 176 * @param fromDisplayString displayable string of the from email address 177 */ 178 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString formatQuotePrefix(const QString &wildString, const QString &fromDisplayString); 179 180 /** 181 * Cleans a filename by replacing characters not allowed or wanted on the filesystem 182 * e.g. ':', '/', '\' with '_' 183 */ 184 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString cleanFileName(const QString &fileName); 185 186 /** 187 * Removes the forward and reply marks (e.g. Re: or Fwd:) from a @p subject string. 188 * Additional markers to act on can be specified in the MessageCore::GlobalSettings 189 * object. 190 */ 191 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString stripOffPrefixes(const QString &subject); 192 193 MESSAGECORE_EXPORT void setEncodingFile(QUrl &url, const QString &encoding); 194 195 /** Check for prefixes @p prefixRegExps in #subject(). If none 196 is found, @p newPrefix + ' ' is prepended to the subject and the 197 resulting string is returned. If @p replace is true, any 198 sequence of whitespace-delimited prefixes at the beginning of 199 #subject() is replaced by @p newPrefix 200 **/ 201 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString cleanSubject(KMime::Message *msg, const QStringList &prefixRegExps, bool replace, const QString &newPrefix); 202 203 /** Return this mails subject, with all "forward" and "reply" 204 prefixes removed */ 205 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString cleanSubject(KMime::Message *msg); 206 207 /** Return this mails subject, formatted for "forward" mails */ 208 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString forwardSubject(KMime::Message *msg); 209 210 /** Return this mails subject, formatted for "reply" mails */ 211 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString replySubject(KMime::Message *msg); 212 /** Check for prefixes @p prefixRegExps in @p str. If none 213 is found, @p newPrefix + ' ' is prepended to @p str and the 214 resulting string is returned. If @p replace is true, any 215 sequence of whitespace-delimited prefixes at the beginning of 216 @p str is replaced by @p newPrefix. 217 **/ 218 Q_REQUIRED_RESULT MESSAGECORE_EXPORT QString replacePrefixes(const QString &str, const QStringList &prefixRegExps, bool replace, const QString &newPrefix); 219 } 220 } 221 222