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 | |
42 | namespace 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 & ); |
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 & ); |
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 ( 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 ( 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) <addrSpec> |
314 | - displayName <addrSpec> |
315 | - comment <addrSpec> |
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 & = 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 | |