1/*
2 SPDX-FileCopyrightText: 2004 Matt Douhan <matt@fruitsalad.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KCODECS_EMAILADDRESS_H
8#define KCODECS_EMAILADDRESS_H
9
10#include <QUrl>
11
12#include <QByteArray>
13#include <QStringList>
14
15#include <kcodecs_export.h>
16
17/*!
18 * \namespace KEmailAddress
19 * \inmodule KCodecs
20 *
21 * \since 5.5
22 */
23namespace KEmailAddress
24{
25
26/*!
27 \enum KEmailAddress::EmailParseResult
28
29 Email validation result. The only 'success' code in
30 this enumeration is AddressOK; all the other values
31 indicate some specific problem with the address which
32 is being validated.
33
34 Result type for splitAddress(), isValidAddress()
35 and isValidSimpleAddress().
36
37 \value AddressOk Email is valid
38 \value AddressEmpty The address is empty
39 \value UnexpectedEnd Something is unbalanced
40 \value UnbalancedParens Unbalanced ( )
41 \value MissingDomainPart No domain in address
42 \value UnclosedAngleAddr \< with no matching \>
43 \value UnopenedAngleAddr \> with no preceding \<
44 \value TooManyAts More than one \@ in address
45 \value UnexpectedComma Comma not allowed here
46 \value TooFewAts Missing \@ in address
47 \value MissingLocalPart No address specified, only domain
48 \value UnbalancedQuote Quotes (single or double) not matched
49 \value NoAddressSpec
50 \value DisallowedChar An invalid character detected in address
51 \value InvalidDisplayName An invalid displayname detected in address
52 \value TooFewDots Missing \. in address
53*/
54enum EmailParseResult {
55 AddressOk,
56 AddressEmpty,
57 UnexpectedEnd,
58 UnbalancedParens,
59 MissingDomainPart,
60 UnclosedAngleAddr,
61 UnopenedAngleAddr,
62 TooManyAts,
63 UnexpectedComma,
64 TooFewAts,
65 MissingLocalPart,
66 UnbalancedQuote,
67 NoAddressSpec,
68 DisallowedChar,
69 InvalidDisplayName,
70 TooFewDots,
71};
72
73/*! Split a comma separated list of email addresses.
74
75\a aStr a single string representing a list of addresses
76
77Returns a list of strings, where each string is one address
78from the original list
79*/
80KCODECS_EXPORT
81QStringList splitAddressList(const QString &aStr);
82
83/*!
84 Splits the given address into display name, email address and comment.
85 Returns AddressOk if no error was encountered. Otherwise an appropriate
86 error code is returned. In case of an error the values of displayName,
87 addrSpec and comment are undefined.
88
89 \a address a single email address,
90 example: Joe User (comment1) <joe.user@example.org> (comment2)
91
92 \a displayName only out: the display-name of the email address, i.e.
93 "Joe User" in the example; in case of an error the
94 return value is undefined
95
96 \a addrSpec only out: the addr-spec, i.e. "joe.user@example.org"
97 in the example; in case of an error the return value is undefined
98
99 \a comment only out: the space-separated comments, i.e.
100 "comment1 comment2" in the example; in case of an
101 error the return value is undefined
102
103 Returns AddressOk if no error was encountered. Otherwise an
104 appropriate error code is returned.
105*/
106KCODECS_EXPORT
107EmailParseResult splitAddress(const QByteArray &address, QByteArray &displayName, QByteArray &addrSpec, QByteArray &comment);
108
109/*!
110 This is an overloaded member function, provided for convenience.
111 It behaves essentially like the above function.
112
113 Splits the given address into display name, email address and comment.
114 Returns AddressOk if no error was encountered. Otherwise an appropriate
115 error code is returned. In case of an error the values of displayName,
116 addrSpec and comment are undefined.
117
118 \a address a single email address,
119 example: Joe User (comment1) <joe.user@example.org> (comment2)
120
121 \a displayName only out: the display-name of the email address, i.e.
122 "Joe User" in the example; in case of an error the
123 return value is undefined
124
125 \a addrSpec only out: the addr-spec, i.e. "joe.user@example.org"
126 in the example; in case of an error the return value is undefined
127
128 \a comment only out: the space-separated comments, i.e.
129 "comment1 comment2" in the example; in case of an
130 error the return value is undefined
131
132 Returns AddressOk if no error was encountered. Otherwise an
133 appropriate error code is returned.
134*/
135KCODECS_EXPORT
136EmailParseResult splitAddress(const QString &address, QString &displayName, QString &addrSpec, QString &comment);
137
138/*!
139 Validates an email address in the form of "Joe User" <joe@example.org>.
140 Returns AddressOk if no error was encountered. Otherwise an appropriate
141 error code is returned.
142
143 \a aStr a single email address,
144 example: Joe User (comment1) <joe.user@example.org>
145
146 Returns AddressOk if no error was encountered. Otherwise an
147 appropriate error code is returned.
148*/
149KCODECS_EXPORT
150EmailParseResult isValidAddress(const QString &aStr);
151
152/*!
153 Validates a list of email addresses, and also allow aliases and
154 distribution lists to be expanded before validation.
155
156 \a aStr a string containing a list of email addresses.
157
158 \a badAddr a string to hold the address that was faulty.
159
160 Returns AddressOk if no error was encountered. Otherwise an
161 appropriate error code is returned.
162*/
163KCODECS_EXPORT
164EmailParseResult isValidAddressList(const QString &aStr, QString &badAddr);
165
166/*!
167 Translate the enum errorcodes from emailParseResult
168 into i18n'd strings that can be used for msg boxes.
169
170 \a errorCode an error code returned from one of the
171 email validation functions. Do not pass
172 AddressOk as a value, since that will yield
173 a misleading error message
174
175 Returns human-readable and already translated message describing
176 the validation error.
177*/
178KCODECS_EXPORT
179QString emailParseResultToString(EmailParseResult errorCode);
180
181/*!
182 Validates an email address in the form of joe@example.org.
183 Returns true if no error was encountered.
184 This method should be used when the input field should not
185 allow a "full" email address with comments and other special
186 cases that normally are valid in an email address.
187
188 \a aStr a single email address,
189 example: joe.user@example.org
190
191 Returns true if no error was encountered.
192
193 \note This method differs from calling isValidAddress()
194 and checking that that returns AddressOk in two ways:
195 it is faster, and it does not allow fancy addresses.
196*/
197KCODECS_EXPORT
198bool isValidSimpleAddress(const QString &aStr);
199
200/*!
201 Returns a i18n string to be used in msgboxes. This allows for error
202 messages to be the same across the board.
203
204 Returns An i18n ready string for use in msgboxes.
205*/
206KCODECS_EXPORT
207QString simpleEmailAddressErrorMsg();
208
209/*!
210 Returns the pure email address (addr-spec in RFC2822) of the given address
211 (mailbox in RFC2822).
212
213 \a address an email address, e.g. "Joe User <joe.user@example.org>"
214
215 Returns the addr-spec of \a address, i.e. joe.user@example.org
216 in the example
217*/
218KCODECS_EXPORT
219QByteArray extractEmailAddress(const QByteArray &address);
220
221/*KF6 merge with above*/
222
223/*!
224 Returns the pure email address (addr-spec in RFC2822) of the given address
225 (mailbox in RFC2822).
226
227 \a address an email address, e.g. "Joe User <joe.user@example.org>"
228
229 \a errorMessage return error message when we can't parse email
230
231 Returns the addr-spec of \a address, i.e. joe.user@example.org
232 in the example
233 \since 5.11.0
234
235*/
236KCODECS_EXPORT
237QByteArray extractEmailAddress(const QByteArray &address, QString &errorMessage);
238
239/*!
240 This is an overloaded member function, provided for convenience.
241 It behaves essentially like the above function.
242
243 Returns the pure email address (addr-spec in RFC2822) of the given
244 address (mailbox in RFC2822).
245
246 \a address an email address, e.g. "Joe User <joe.user@example.org>"
247
248 Returns the addr-spec of \a address, i.e. joe.user@example.org
249 in the example
250*/
251KCODECS_EXPORT
252QString extractEmailAddress(const QString &address);
253
254/*!
255 Returns the pure email address (addr-spec in RFC2822) of the first
256 email address of a list of addresses.
257
258 \a address an email address, e.g. "Joe User <joe.user@example.org>"
259
260 \a errorMessage return error message when we can't parse email
261
262 Returns the addr-spec of \a address, i.e. joe.user@example.org
263 in the example
264 \since 5.11
265*/
266KCODECS_EXPORT
267QString extractEmailAddress(const QString &address, QString &errorMessage);
268
269/*KF6 merge with above*/
270/*!
271 Returns the pure email address (addr-spec in RFC2822) of the first
272 email address of a list of addresses.
273
274 \a addresses an email address, e.g. "Joe User <joe.user@example.org>"
275
276 Returns the addr-spec of \a addresses, i.e. joe.user@example.org
277 in the example
278*/
279KCODECS_EXPORT
280QByteArray firstEmailAddress(const QByteArray &addresses);
281
282/*!
283 Returns the pure email address (addr-spec in RFC2822) of the first
284 email address of a list of addresses.
285
286 \a addresses an email address, e.g. "Joe User <joe.user@example.org>"
287
288 \a errorMessage return error message when we can't parse email
289
290 Returns the addr-spec of \a addresses, i.e. joe.user@example.org
291 in the example
292 \since 5.11.0
293*/
294
295KCODECS_EXPORT
296QByteArray firstEmailAddress(const QByteArray &addresses, QString &errorMessage);
297
298/*!
299 This is an overloaded member function, provided for convenience.
300 It behaves essentially like the above function.
301
302 Returns the pure email address (addr-spec in RFC2822) of the first
303 email address of a list of addresses.
304
305 \a addresses an email address, e.g. "Joe User <joe.user@example.org>"
306
307 Returns the addr-spec of \a addresses, i.e. joe.user@example.org
308 in the example
309*/
310KCODECS_EXPORT
311QString firstEmailAddress(const QString &addresses);
312
313/*!
314 This is an overloaded member function, provided for convenience.
315 It behaves essentially like the above function.
316
317 Returns the pure email address (addr-spec in RFC2822) of the first
318 email address of a list of addresses.
319
320 \a addresses an email address, e.g. "Joe User <joe.user@example.org>"
321
322 \a errorMessage return error message when we can't parse email
323
324 Returns the addr-spec of \a addresses, i.e. joe.user@example.org
325 in the example
326 \since 5.11.0
327*/
328KCODECS_EXPORT
329QString firstEmailAddress(const QString &addresses, QString &errorMessage);
330
331/*!
332 Return email address and name from string.
333 Examples:
334 "Stefan Taferner <taferner@example.org>" returns "taferner@example.org"
335 and "Stefan Taferner". "joe@example.com" returns "joe@example.com"
336 and "". Note that this only returns the first address.
337
338 Also note that the return value is true if both the name and the
339 mail are not empty: this does NOT tell you if mail contains a
340 valid email address or just some rubbish.
341
342 \a aStr an email address, e.g "Joe User <joe.user@example.org>"
343
344 \a name only out: returns the displayname, "Joe User" in the example
345
346 \a mail only out: returns the email address "joe.user@example.org"
347 in the example
348
349 Returns true if both name and email address are not empty
350*/
351KCODECS_EXPORT
352bool extractEmailAddressAndName(const QString &aStr, QString &mail, QString &name);
353
354/*!
355 Compare two email addresses. If matchName is false, it just checks
356 the email address, and returns true if this matches. If matchName
357 is true, both the name and the email must be the same.
358
359 \a email1 the first email address to use for comparison
360
361 \a email2 the second email address to use for comparison
362
363 \a matchName if set to true email address and displayname must match
364
365 Returns true if the comparison matches true in all other cases
366*/
367KCODECS_EXPORT
368bool compareEmail(const QString &email1, const QString &email2, bool matchName);
369
370/*!
371 Returns a normalized address built from the given parts. The normalized
372 address is of one the following forms:
373 - displayName (comment) &lt;addrSpec&gt;
374 - displayName &lt;addrSpec&gt;
375 - comment &lt;addrSpec&gt;
376 - addrSpec
377
378 \a displayName the display name of the address
379
380 \a addrSpec the actual email address (addr-spec in RFC 2822)
381
382 \a comment a comment
383
384 Returns a normalized address built from the given parts
385*/
386KCODECS_EXPORT
387QString normalizedAddress(const QString &displayName, const QString &addrSpec, const QString &comment = QString());
388
389/*!
390 Decodes the punycode domain part of the given addr-spec if it's an IDN.
391
392 \a addrSpec a pure 7-bit email address (addr-spec in RFC2822)
393
394 Returns the email address with Unicode domain
395*/
396KCODECS_EXPORT
397QString fromIdn(const QString &addrSpec);
398
399/*!
400 Encodes the domain part of the given addr-spec in punycode if it's an IDN.
401
402 \a addrSpec a pure email address with Unicode domain
403
404 Returns the email address with domain in punycode
405*/
406KCODECS_EXPORT
407QString toIdn(const QString &addrSpec);
408
409/*!
410 Normalizes all email addresses in the given list and decodes all IDNs.
411
412 \a addresses a list of email addresses with punycoded IDNs
413
414 Returns the email addresses in normalized form with Unicode IDNs
415*/
416KCODECS_EXPORT
417QString normalizeAddressesAndDecodeIdn(const QString &addresses);
418
419/*!
420 Normalizes all email addresses in the given list and encodes all IDNs
421 in punycode.
422
423 \a str a list of email addresses
424
425 Returns the email addresses in normalized form
426*/
427KCODECS_EXPORT
428QString normalizeAddressesAndEncodeIdn(const QString &str);
429
430/*!
431 Add quote characters around the given string if it contains a
432 character that makes that necessary, in an email name, such as ",".
433
434 \a str a string that may need quoting
435
436 Returns the string quoted if necessary
437*/
438KCODECS_EXPORT
439QString quoteNameIfNecessary(const QString &str);
440
441/*!
442 * Creates a valid mailto: URL from the given mailbox.
443 *
444 * \a mailbox The mailbox, which means the display name and the address specification, for
445 * example "Thomas McGuire" <thomas@domain.com>. The display name is optional.
446 *
447 * Returns a valid mailto: URL for the given mailbox.
448 */
449KCODECS_EXPORT
450QUrl encodeMailtoUrl(const QString &mailbox);
451
452/*!
453 * Extracts the mailbox out of the mailto: URL.
454 *
455 * \a mailtoUrl the URL with the mailto protocol, which contains the mailbox to be extracted
456 *
457 * Returns the mailbox, which means the display name and the address specification.
458 */
459KCODECS_EXPORT
460QString decodeMailtoUrl(const QUrl &mailtoUrl);
461
462} // namespace KEmailAddress
463
464#endif
465

source code of kcodecs/src/kemailaddress.h