Email Validation Functions

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

Functions
KCODECS_EXPORT QString	KEmailAddress::emailParseResultToString (EmailParseResult errorCode)
KCODECS_EXPORT EmailParseResult	KEmailAddress::isValidAddress (const QString &aStr)
KCODECS_EXPORT EmailParseResult	KEmailAddress::isValidAddressList (const QString &aStr, QString &badAddr)
KCODECS_EXPORT bool	KEmailAddress::isValidSimpleAddress (const QString &aStr)
KCODECS_EXPORT QString	KEmailAddress::simpleEmailAddressErrorMsg ()
KCODECS_EXPORT EmailParseResult	KEmailAddress::splitAddress (const QByteArray &address, QByteArray &displayName, QByteArray &addrSpec, QByteArray &comment)
KCODECS_EXPORT EmailParseResult	KEmailAddress::splitAddress (const QString &address, QString &displayName, QString &addrSpec, QString &comment)
KCODECS_EXPORT QStringList	KEmailAddress::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

EmailParseResult

enum KEmailAddress::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.
TooFewDots	Missing . in address

Definition at line 50 of file kemailaddress.h.

Function Documentation

emailParseResultToString()

QString KEmailAddress::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 499 of file kemailaddress.cpp.

isValidAddress()

EmailParseResult KEmailAddress::isValidAddress

(

const QString &

aStr

)

Validates an email address in the form of "Joe User" joe@e.nosp@m.xamp.nosp@m.le.or.nosp@m.g.

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.u.nosp@m.ser@.nosp@m.examp.nosp@m.le.o.nosp@m.rg

Returns

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

Definition at line 275 of file kemailaddress.cpp.

isValidAddressList()

KEmailAddress::EmailParseResult KEmailAddress::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 479 of file kemailaddress.cpp.

isValidSimpleAddress()

bool KEmailAddress::isValidSimpleAddress

(

const QString &

aStr

)

Validates an email address in the form of joe@e.nosp@m.xamp.nosp@m.le.or.nosp@m.g.

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.u.nosp@m.ser@.nosp@m.examp.nosp@m.le.o.nosp@m.rg

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 576 of file kemailaddress.cpp.

simpleEmailAddressErrorMsg()

QString KEmailAddress::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 630 of file kemailaddress.cpp.

splitAddress() [1/2]

EmailParseResult KEmailAddress::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.u.nosp@m.ser@.nosp@m.examp.nosp@m.le.o.nosp@m.rg (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 251 of file kemailaddress.cpp.

splitAddress() [2/2]

EmailParseResult KEmailAddress::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.u.nosp@m.ser@.nosp@m.examp.nosp@m.le.o.nosp@m.rg (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 257 of file kemailaddress.cpp.

splitAddressList()

QStringList KEmailAddress::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 16 of file kemailaddress.cpp.