KCodecs

kemailaddress.h
Go to the documentation of this file.
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  */
29 namespace 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 */
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
73 from the original list
74 */
75 KCODECS_EXPORT
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 */
98 KCODECS_EXPORT
99 EmailParseResult 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 */
124 KCODECS_EXPORT
125 EmailParseResult 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 */
137 KCODECS_EXPORT
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 */
150 KCODECS_EXPORT
151 EmailParseResult 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 */
165 KCODECS_EXPORT
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 */
184 KCODECS_EXPORT
185 bool 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 
194 KCODECS_EXPORT
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 */
211 KCODECS_EXPORT
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 */
227 KCODECS_EXPORT
228 QByteArray 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 */
241 KCODECS_EXPORT
242 QString 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 
255 KCODECS_EXPORT
256 QString 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*/
268 KCODECS_EXPORT
269 QByteArray 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 
282 KCODECS_EXPORT
283 QByteArray 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 */
296 KCODECS_EXPORT
297 QString 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 */
312 KCODECS_EXPORT
313 QString 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 */
333 KCODECS_EXPORT
334 bool 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 */
347 KCODECS_EXPORT
348 bool 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 */
364 KCODECS_EXPORT
365 QString 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 */
379 KCODECS_EXPORT
380 QString 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 */
388 KCODECS_EXPORT
389 QString 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 */
397 KCODECS_EXPORT
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 */
407 KCODECS_EXPORT
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 */
420 KCODECS_EXPORT
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  */
429 KCODECS_EXPORT
430 QUrl 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  */
437 KCODECS_EXPORT
438 QString decodeMailtoUrl(const QUrl &mailtoUrl);
439 
440 } // namespace KEmailAddress
441 
442 #endif
KCODECS_EXPORT QByteArray extractEmailAddress(const QByteArray &address)
Returns the pure email address (addr-spec in RFC2822) of the given address (mailbox in RFC2822).
@ TooFewAts
Missing @ in address.
Definition: kemailaddress.h:60
KCODECS_EXPORT QString quoteNameIfNecessary(const QString &str)
@ MissingLocalPart
No address specified, only domain.
Definition: kemailaddress.h:61
@ UnbalancedQuote
Quotes (single or double) not matched.
Definition: kemailaddress.h:62
KCODECS_EXPORT EmailParseResult isValidAddressList(const QString &aStr, QString &badAddr)
Validates a list of email addresses, and also allow aliases and distribution lists to be expanded bef...
KCODECS_EXPORT QString emailParseResultToString(EmailParseResult errorCode)
Translate the enum errorcodes from emailParseResult into i18n'd strings that can be used for msg boxe...
@ AddressOk
Email is valid.
Definition: kemailaddress.h:51
KCODECS_EXPORT bool compareEmail(const QString &email1, const QString &email2, bool matchName)
Compare two email addresses.
@ TooManyAts
More than one @ in address.
Definition: kemailaddress.h:58
@ UnexpectedEnd
Something is unbalanced.
Definition: kemailaddress.h:53
KCODECS_EXPORT QStringList splitAddressList(const QString &aStr)
Split a comma separated list of email addresses.
@ AddressEmpty
The address is empty.
Definition: kemailaddress.h:52
KCODECS_EXPORT EmailParseResult splitAddress(const QByteArray &address, QByteArray &displayName, QByteArray &addrSpec, QByteArray &comment)
Splits the given address into display name, email address and comment.
KCODECS_EXPORT QString decodeMailtoUrl(const QUrl &mailtoUrl)
Extracts the mailbox out of the mailto: URL.
KCODECS_EXPORT bool extractEmailAddressAndName(const QString &aStr, QString &mail, QString &name)
Return email address and name from string.
KCODECS_EXPORT QByteArray firstEmailAddress(const QByteArray &addresses)
Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of address...
KCODECS_EXPORT QString toIdn(const QString &addrSpec)
Encodes the domain part of the given addr-spec in punycode if it's an IDN.
KCODECS_EXPORT QString normalizedAddress(const QString &displayName, const QString &addrSpec, const QString &comment=QString())
Returns a normalized address built from the given parts.
@ UnbalancedParens
Unbalanced ( )
Definition: kemailaddress.h:54
EmailParseResult
Email validation result.
Definition: kemailaddress.h:50
@ TooFewDots
Missing .
Definition: kemailaddress.h:66
KCODECS_EXPORT QString fromIdn(const QString &addrSpec)
Decodes the punycode domain part of the given addr-spec if it's an IDN.
KCODECS_EXPORT bool isValidSimpleAddress(const QString &aStr)
Validates an email address in the form of joe@example.org.
@ MissingDomainPart
No domain in address.
Definition: kemailaddress.h:55
@ UnopenedAngleAddr
> with no preceding <
Definition: kemailaddress.h:57
KCODECS_EXPORT QString simpleEmailAddressErrorMsg()
Returns a i18n string to be used in msgboxes.
KCODECS_EXPORT EmailParseResult isValidAddress(const QString &aStr)
Validates an email address in the form of "Joe User" joe@example.org.
@ DisallowedChar
An invalid character detected in address.
Definition: kemailaddress.h:64
@ UnclosedAngleAddr
< with no matching >
Definition: kemailaddress.h:56
@ UnexpectedComma
Comma not allowed here.
Definition: kemailaddress.h:59
KCODECS_EXPORT QString normalizeAddressesAndDecodeIdn(const QString &addresses)
Normalizes all email addresses in the given list and decodes all IDNs.
KCODECS_EXPORT QUrl encodeMailtoUrl(const QString &mailbox)
Creates a valid mailto: URL from the given mailbox.
KCODECS_EXPORT QString normalizeAddressesAndEncodeIdn(const QString &str)
Normalizes all email addresses in the given list and encodes all IDNs in punycode.
@ InvalidDisplayName
An invalid displayname detected in address.
Definition: kemailaddress.h:65
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 04:06:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.