KMime

kmime_util.h
1 /* -*- c++ -*-
2  kmime_util.h
3 
4  KMime, the KDE Internet mail/usenet news message library.
5  SPDX-FileCopyrightText: 2001 the KMime authors.
6  See file AUTHORS for details
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 #pragma once
11 
12 #include "kmime_export.h"
13 #include "kmime_headers.h"
14 #include "kmime_content.h"
15 
16 #include <QString>
17 #include <QVector>
18 
19 namespace KMime
20 {
21 
22 class Message;
23 
24 /**
25  Checks whether @p s contains any non-us-ascii characters.
26  @param s
27 */
28 KMIME_EXPORT extern bool isUsAscii(const QString &s);
29 
30 /**
31  Returns a user-visible string for a contentEncoding, for example
32  "quoted-printable" for CEquPr.
33  @param enc the contentEncoding to return string for
34  @ since 4.4
35  TODO should they be i18n'ed?
36 */
37 KMIME_EXPORT extern QString nameForEncoding(KMime::Headers::contentEncoding enc);
38 
39 /**
40  Returns a list of encodings that can correctly encode the @p data.
41  @param data the data to check encodings for
42  @ since 4.4
43 */
44 Q_REQUIRED_RESULT KMIME_EXPORT QVector<KMime::Headers::contentEncoding> encodingsForData(const QByteArray &data);
45 
46 /**
47  * Set whether or not to use outlook compatible attachment filename encoding. Outlook
48  * fails to properly adhere to the RFC2322 standard for parametrized header fields, and
49  * instead is only able to read and write attachment filenames encoded in RFC2047-style.
50  * This will create mails that are not standards-compliant!
51  *
52  * @param violateStandard Whether or not to use outlook-compatible attachment
53  * filename encodings.
54  *
55  * @since 4.5
56  */
57 KMIME_EXPORT extern void setUseOutlookAttachmentEncoding(bool violateStandard);
58 
59 /**
60  * Retrieve whether or not to use outlook compatible encodings for attachments.
61  */
62 KMIME_EXPORT extern bool useOutlookAttachmentEncoding();
63 
64 /**
65  Constructs a random string (sans leading/trailing "--") that can
66  be used as a multipart delimiter (ie. as @p boundary parameter
67  to a multipart/... content-type).
68 
69  @return the randomized string.
70  @see uniqueString
71 */
72 KMIME_EXPORT extern QByteArray multiPartBoundary();
73 
74 /**
75  Unfolds the given header if necessary.
76  @param header The header to unfold.
77 */
78 
79 KMIME_EXPORT extern QByteArray unfoldHeader(const QByteArray &header);
80 KMIME_EXPORT extern QByteArray unfoldHeader(const char *header, size_t headerSize);
81 
82 /**
83  Tries to extract the header with name @p name from the string
84  @p src, unfolding it if necessary.
85 
86  @param src the source string.
87  @param name the name of the header to search for.
88 
89  @return the first instance of the header @p name in @p src
90  or a null QByteArray if no such header was found.
91 */
92 KMIME_EXPORT extern QByteArray extractHeader(const QByteArray &src,
93  const QByteArray &name);
94 
95 /**
96  Converts all occurrences of "\r\n" (CRLF) in @p s to "\n" (LF).
97 
98  This function is expensive and should be used only if the mail
99  will be stored locally. All decode functions can cope with both
100  line endings.
101 
102  @param s source string containing CRLF's
103 
104  @return the string with CRLF's substituted for LF's
105  @see CRLFtoLF(const char*) LFtoCRLF
106 */
107 KMIME_EXPORT extern QByteArray CRLFtoLF(const QByteArray &s);
108 
109 /**
110  Converts all occurrences of "\r\n" (CRLF) in @p s to "\n" (LF).
111 
112  This function is expensive and should be used only if the mail
113  will be stored locally. All decode functions can cope with both
114  line endings.
115 
116  @param s source string containing CRLF's
117 
118  @return the string with CRLF's substituted for LF's
119  @see CRLFtoLF(const QByteArray&) LFtoCRLF
120 */
121 KMIME_EXPORT extern QByteArray CRLFtoLF(const char *s);
122 
123 /**
124  Converts all occurrences of "\n" (LF) in @p s to "\r\n" (CRLF).
125 
126  This function is expensive and should be used only if the mail
127  will be transmitted as an RFC822 message later. All decode
128  functions can cope with and all encode functions can optionally
129  produce both line endings, which is much faster.
130 
131  @param s source string containing CRLF's
132 
133  @return the string with CRLF's substituted for LF's
134  @see CRLFtoLF(const QByteArray&) LFtoCRLF
135 */
136 KMIME_EXPORT extern QByteArray LFtoCRLF(const QByteArray &s);
137 
138 /**
139  Converts all occurrences of "\r" (CR) in @p s to "\n" (LF).
140 
141  This function is expensive and should be used only if the mail
142  will be stored locally. All decode functions can cope with both
143  line endings.
144 
145  @param s source string containing CR's
146 
147  @return the string with CR's substituted for LF's
148  @see CRtoLF(const QByteArray&) CRtoLF
149 */
150 KMIME_EXPORT extern QByteArray CRtoLF(const char *s);
151 
152 /**
153  Converts all occurrences of "\r" (CR) in @p s to "\n" (LF).
154 
155  This function is expensive and should be used only if the mail
156  will be transmitted as an RFC822 message later. All decode
157  functions can cope with and all encode functions can optionally
158  produce both line endings, which is much faster.
159 
160  @param s source string containing CR's
161 
162  @return the string with CR's substituted for LF's
163  @see CRtoLF(const QByteArray&) CRtoLF
164 */
165 KMIME_EXPORT extern QByteArray CRtoLF(const QByteArray &s);
166 
167 
168 /**
169  Removes quote (DQUOTE) characters and decodes "quoted-pairs"
170  (ie. backslash-escaped characters)
171 
172  @param str the string to work on.
173  @see addQuotes
174 */
175 KMIME_EXPORT extern void removeQuotes(QByteArray &str);
176 
177 /**
178  Removes quote (DQUOTE) characters and decodes "quoted-pairs"
179  (ie. backslash-escaped characters)
180 
181  @param str the string to work on.
182  @see addQuotes
183 */
184 KMIME_EXPORT extern void removeQuotes(QString &str);
185 
186 /**
187  Converts the given string into a quoted-string if the string contains
188  any special characters (ie. one of ()<>@,.;:[]=\").
189 
190  @param str us-ascii string to work on.
191  @param forceQuotes if @c true, always add quote characters.
192 */
193 KMIME_EXPORT extern void addQuotes(QByteArray &str, bool forceQuotes);
194 
195 /**
196  * Overloaded method, behaves same as the above.
197  * @param str us-ascii string to work on.
198  * @param forceQuotes if @c true, always add quote characters.
199  * @since 4.5
200  */
201 KMIME_EXPORT extern void addQuotes(QString &str, bool forceQuotes);
202 
203 /**
204  * Makes sure that the bidirectional state at the end of the string is the
205  * same as at the beginning of the string.
206  *
207  * This is useful so that Unicode control characters that can change the text
208  * direction can not spill over to following strings.
209  *
210  * As an example, consider a mailbox in the form "display name" <[email protected]>.
211  * If the display name here contains unbalanced control characters that change the
212  * text direction, it would also have an effect on the addrspec, which could lead to
213  * spoofing.
214  *
215  * By passing the display name to this function, one can make sure that no change of
216  * the bidi state can spill over to the next strings, in this case the addrspec.
217  *
218  * Example: The string "Hello <RLO>World" is unbalanced, as it contains a right-to-left
219  * override character, which is never followed by a <PDF>, the "pop directional
220  * formatting" character. This function adds the missing <PDF> at the end, and
221  * the output of this function would be "Hello <RLO>World<PDF>".
222  *
223  * Example of spoofing:
224  * Consider "Firstname Lastname<RLO>" <[email protected]>. Because of the RLO,
225  * it is displayed as "Firstname Lastname <[email protected]>", which spoofs the
226  * domain name.
227  * By passing "Firstname Lastname<RLO>" to this function, one can balance the <RLO>,
228  * leading to "Firstname Lastname<RLO><PDF>", so the whole mailbox is displayed
229  * correctly as "Firstname Lastname" <[email protected]> again.
230  *
231  * See https://unicode.org/reports/tr9 for more information on bidi control chars.
232  *
233  * @param input the display name of a mailbox, which is checked for unbalanced Unicode
234  * direction control characters
235  * @return the display name which now contains a balanced state of direction control
236  * characters
237  *
238  * Note that this function does not do any parsing related to mailboxes, it only works
239  * on plain strings. Therefore, passing the complete mailbox will not lead to any results,
240  * only the display name should be passed.
241  *
242  * @since 4.5
243  */
244 KMIME_EXPORT QString balanceBidiState(const QString &input);
245 
246 /**
247  * Similar to the above function. Instead of trying to balance the Bidi chars, it outright
248  * removes them from the string.
249  *
250  * @param input the display name of a mailbox, which is checked for unbalanced Unicode
251  * direction control characters
252  * Reason: KHTML seems to ignore the PDF character, so adding them doesn't fix things :(
253  */
254 KMIME_EXPORT QString removeBidiControlChars(const QString &input);
255 
256 /**
257  * Returns whether or not the given MIME node is an attachment part.
258  * @param content the MIME node to parse
259  * @see hasAttachment()
260  */
261 KMIME_EXPORT bool isAttachment(Content *content);
262 
263 /**
264  * Returns whether or not the given MIME node contains an attachment part. This function will
265  * recursively parse the MIME tree looking for a suitable attachment and return true if one is found.
266  * @param content the MIME node to parse
267  * @see isAttachment()
268  */
269 KMIME_EXPORT bool hasAttachment(Content *content);
270 
271 /**
272  * Returns whether or not the given MIME node contains an invitation part. This function will
273  * recursively parse the MIME tree looking for a suitable invitation and return true if one is found.
274  * @param content the MIME node to parse
275  * @since 4.14.6
276  */
277 KMIME_EXPORT bool hasInvitation(Content *content);
278 
279 /**
280  * Returns whether or not the given @p message is partly or fully signed.
281  *
282  * @param message the message to check for being signed
283  * @since 4.6
284  */
285 KMIME_EXPORT bool isSigned(Message *message);
286 
287 /**
288  * Returns whether or not the given @p message is partly or fully encrypted.
289  *
290  * @param message the message to check for being encrypted
291  * @since 4.6
292  */
293 KMIME_EXPORT bool isEncrypted(Message *message);
294 
295 /**
296  * Determines if the MIME part @p content is a crypto part.
297  * This is, is either an encrypted part or a signature part.
298  */
299 KMIME_EXPORT bool isCryptoPart(Content *content);
300 
301 /**
302  * Returns whether or not the given MIME @p content is an invitation
303  * message of the iTIP protocol.
304  *
305  * @since 4.6
306  */
307 KMIME_EXPORT bool isInvitation(Content *content);
308 
309 } // namespace KMime
310 
This file is part of the API for handling MIME data and defines the Content class.
This file is part of the API for handling MIME data and defines the various header classes: ...
contentEncoding
Various possible values for the "Content-Transfer-Encoding" header.
Definition: kmime_headers.h:59
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Sep 27 2021 23:15:57 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.