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