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

source code of kcodecs/src/kemailaddress.h