Messagelib

stringutil.h
1 /* SPDX-FileCopyrightText: 2009 Thomas McGuire <[email protected]>
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 
QString replySubject(KMime::Message *msg)
Return this mails subject, formatted for "reply" mails.
Definition: stringutil.cpp:744
QByteArray asSendableString(const KMime::Message::Ptr &originalMessage)
Returns the message contents with the headers that should not be sent stripped off.
Definition: stringutil.cpp:383
QString stripSignature(const QString &msg)
Strips the signature blocks from a message text.
Definition: stringutil.cpp:223
bool addressIsInAddressList(const QString &address, const QStringList &addresses)
Returns true if the given address is contained in the given address list.
Definition: stringutil.cpp:495
QString replacePrefixes(const QString &str, const QStringList &prefixRegExps, bool replace, const QString &newPrefix)
Check for prefixes prefixRegExps in str.
Definition: stringutil.cpp:752
AddressMode
Used to determine if the address field should be expandable/collapsible.
Definition: stringutil.h:102
QString quoteHtmlChars(const QString &str, bool removeLineBreaks)
Quotes the following characters which have a special meaning in HTML: &#39;<&#39; &#39;>&#39; &#39;&&#39; &#39;"&#39;...
Definition: stringutil.cpp:317
QString forwardSubject(KMime::Message *msg)
Return this mails subject, formatted for "forward" mails.
Definition: stringutil.cpp:736
QString guessEmailAddressFromLoginName(const QString &loginName)
Uses the hostname as domain part and tries to determine the real name from the entries in the passwor...
Definition: stringutil.cpp:509
QString smartQuote(const QString &msg, int maxLineLength)
Relayouts the given string so that the individual lines don&#39;t exceed the given maximal length...
Definition: stringutil.cpp:529
QString formatQuotePrefix(const QString &wildString, const QString &fromDisplayString)
Convert quote wildcards into the final quote prefix.
Definition: stringutil.cpp:635
QVector< QPair< QString, QString > > parseMailtoUrl(const QUrl &url)
Parses a mailto: url and extracts the information in the QMap (field name as key).
Definition: stringutil.cpp:162
QString stripOffPrefixes(const QString &subject)
Removes the forward and reply marks (e.g.
Definition: stringutil.cpp:783
AddressList splitAddressField(const QByteArray &text)
Splits the given address list text into separate addresses.
Definition: stringutil.cpp:283
void removePrivateHeaderFields(const KMime::Message::Ptr &message, bool cleanUpHeader)
Removes all private header fields (e.g.
Definition: stringutil.cpp:354
QByteArray headerAsSendableString(const KMime::Message::Ptr &originalMessage)
Return the message header with the headers that should not be sent stripped off.
Definition: stringutil.cpp:394
Display
Used to determine if the visible part of the anchor contains only the name part and not the given ema...
Definition: stringutil.h:92
QString cleanFileName(const QString &name)
Cleans a filename by replacing characters not allowed or wanted on the filesystem e...
Definition: stringutil.cpp:686
QString cleanSubject(KMime::Message *msg)
Return this mails subject, with all "forward" and "reply" prefixes removed.
Definition: stringutil.cpp:722
Link
Used to determine if the address should be a link or not.
Definition: stringutil.h:97
QString generateMessageId(const QString &address, const QString &suffix)
Generates the Message-Id.
Definition: stringutil.cpp:300
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 23:16:43 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.