• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • Sitemap
  • Contact Us
 

kpimutils

Email Validation Functions

This collection of methods that can validate email addresses as supplied by the user (typically, user input from a text box). More...


Enumerations

enum  KPIMUtils::EmailParseResult {
  KPIMUtils::AddressOk, KPIMUtils::AddressEmpty, KPIMUtils::UnexpectedEnd, KPIMUtils::UnbalancedParens,
  KPIMUtils::MissingDomainPart, KPIMUtils::UnclosedAngleAddr, KPIMUtils::UnopenedAngleAddr, KPIMUtils::TooManyAts,
  KPIMUtils::UnexpectedComma, KPIMUtils::TooFewAts, KPIMUtils::MissingLocalPart, KPIMUtils::UnbalancedQuote,
  NoAddressSpec, KPIMUtils::DisallowedChar, KPIMUtils::InvalidDisplayName
}

Functions

QString KPIMUtils::emailParseResultToString (EmailParseResult errorCode)
EmailParseResult KPIMUtils::isValidAddress (const QString &aStr)
EmailParseResult KPIMUtils::isValidAddressList (const QString &aStr, QString &badAddr)
bool KPIMUtils::isValidSimpleAddress (const QString &aStr)
QString KPIMUtils::simpleEmailAddressErrorMsg ()
EmailParseResult KPIMUtils::splitAddress (const QString &address, QString &displayName, QString &addrSpec, QString &comment)
EmailParseResult KPIMUtils::splitAddress (const QByteArray &address, QByteArray &displayName, QByteArray &addrSpec, QByteArray &comment)
QStringList KPIMUtils::splitAddressList (const QString &aStr)

Detailed Description

This collection of methods that can validate email addresses as supplied by the user (typically, user input from a text box).

There are also functions for splitting an RFC2822 address into its component parts.


Enumeration Type Documentation

enum KPIMUtils::EmailParseResult

Email validation result.

The only 'success' code in this enumeration is AddressOK; all the other values indicate some specific problem with the address which is being validated.

Result type for splitAddress(), isValidAddress() and isValidSimpleAddress().

Enumerator:
AddressOk  Email is valid.
AddressEmpty  The address is empty.
UnexpectedEnd  Something is unbalanced.
UnbalancedParens  Unbalanced ( ).
MissingDomainPart  No domain in address.
UnclosedAngleAddr  < with no matching >
UnopenedAngleAddr  > with no preceding <
TooManyAts  More than one @ in address.
UnexpectedComma  Comma not allowed here.
TooFewAts  Missing @ in address.
MissingLocalPart  No address specified, only domain.
UnbalancedQuote  Quotes (single or double) not matched.
DisallowedChar  An invalid character detected in address.
InvalidDisplayName  An invalid displayname detected in address.

Definition at line 61 of file email.h.


Function Documentation

QString KPIMUtils::emailParseResultToString ( EmailParseResult  errorCode  ) 

Translate the enum errorcodes from emailParseResult into i18n'd strings that can be used for msg boxes.

Parameters:
errorCode an error code returned from one of the email validation functions. Do not pass AddressOk as a value, since that will yield a misleading error message
Returns:
human-readable and already translated message describing the validation error.

Definition at line 523 of file email.cpp.

EmailParseResult KPIMUtils::isValidAddress ( const QString &  aStr  ) 

Validates an email address in the form of "Joe User" <joe@example.org>.

Returns AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

Parameters:
aStr a single email address, example: Joe User (comment1) <joe.user@example.org>
Returns:
AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

Definition at line 308 of file email.cpp.

KPIMUtils::EmailParseResult KPIMUtils::isValidAddressList ( const QString &  aStr,
QString &  badAddr 
)

Validates a list of email addresses, and also allow aliases and distribution lists to be expanded before validation.

Parameters:
aStr a string containing a list of email addresses.
badAddr a string to hold the address that was faulty.
Returns:
AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

Definition at line 501 of file email.cpp.

bool KPIMUtils::isValidSimpleAddress ( const QString &  aStr  ) 

Validates an email address in the form of joe@example.org.

Returns true if no error was encountered. This method should be used when the input field should not allow a "full" email address with comments and other special cases that normally are valid in an email address.

Parameters:
aStr a single email address, example: joe.user@example.org
Returns:
true if no error was encountered.
Note:
This method differs from calling isValidAddress() and checking that that returns AddressOk in two ways: it is faster, and it does not allow fancy addresses.

Definition at line 581 of file email.cpp.

QString KPIMUtils::simpleEmailAddressErrorMsg (  ) 

Returns a i18n string to be used in msgboxes.

This allows for error messages to be the same across the board.

Returns:
An i18n ready string for use in msgboxes.

Definition at line 629 of file email.cpp.

EmailParseResult KPIMUtils::splitAddress ( const QString &  address,
QString &  displayName,
QString &  addrSpec,
QString &  comment 
)

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

Splits the given address into display name, email address and comment. Returns AddressOk if no error was encountered. Otherwise an appropriate error code is returned. In case of an error the values of displayName, addrSpec and comment are undefined.

Parameters:
address a single email address, example: Joe User (comment1) <joe.user@example.org> (comment2)
displayName only out: the display-name of the email address, i.e. "Joe User" in the example; in case of an error the return value is undefined
addrSpec only out: the addr-spec, i.e. "joe.user@example.org" in the example; in case of an error the return value is undefined
comment only out: the space-separated comments, i.e. "comment1 comment2" in the example; in case of an error the return value is undefined
Returns:
AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

Definition at line 291 of file email.cpp.

EmailParseResult KPIMUtils::splitAddress ( const QByteArray &  address,
QByteArray &  displayName,
QByteArray &  addrSpec,
QByteArray &  comment 
)

Splits the given address into display name, email address and comment.

Returns AddressOk if no error was encountered. Otherwise an appropriate error code is returned. In case of an error the values of displayName, addrSpec and comment are undefined.

Parameters:
address a single email address, example: Joe User (comment1) <joe.user@example.org> (comment2)
displayName only out: the display-name of the email address, i.e. "Joe User" in the example; in case of an error the return value is undefined
addrSpec only out: the addr-spec, i.e. "joe.user@example.org" in the example; in case of an error the return value is undefined
comment only out: the space-separated comments, i.e. "comment1 comment2" in the example; in case of an error the return value is undefined
Returns:
AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

Definition at line 281 of file email.cpp.

QStringList KPIMUtils::splitAddressList ( const QString &  aStr  ) 

Split a comma separated list of email addresses.

Parameters:
aStr a single string representing a list of addresses
Returns:
a list of strings, where each string is one address from the original list

Definition at line 41 of file email.cpp.

kpimutils

Skip menu "kpimutils"
  • Main Page
  • Modules
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Class Members

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  • kabc
  • kblog
  • kcal
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  • kldap
  • kmime
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.5.8
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal