KCodecs 5.109.0
Enumerations | Functions
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  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
}
 Email validation result. More...
 

Functions

QString KEmailAddress::emailParseResultToString (EmailParseResult errorCode)
 Translate the enum errorcodes from emailParseResult into i18n'd strings that can be used for msg boxes.
 
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.
 
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.
 
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.
 
QString KEmailAddress::simpleEmailAddressErrorMsg ()
 Returns a i18n string to be used in msgboxes.
 
EmailParseResult KEmailAddress::splitAddress (const QByteArray &address, QByteArray &displayName, QByteArray &addrSpec, QByteArray &comment)
 Splits the given address into display name, email address and comment.
 
EmailParseResult KEmailAddress::splitAddress (const QString &address, QString &displayName, QString &addrSpec, QString &comment)
 This is an overloaded member function, provided for convenience.
 
QStringList KEmailAddress::splitAddressList (const QString &aStr)
 Split a comma separated list of email addresses.
 

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

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

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
errorCodean 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.

◆ 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
aStra 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.

◆ isValidAddressList()

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
aStra string containing a list of email addresses.
badAddra string to hold the address that was faulty.
Returns
AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

◆ 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
aStra 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.

◆ 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.

◆ 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
addressa single email address, example: Joe User (comment1) joe.u.nosp@m.ser@.nosp@m.examp.nosp@m.le.o.nosp@m.rg (comment2)
displayNameonly 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
addrSpeconly out: the addr-spec, i.e. "joe.user@example.org" in the example; in case of an error the return value is undefined
commentonly 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.

◆ 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
addressa single email address, example: Joe User (comment1) joe.u.nosp@m.ser@.nosp@m.examp.nosp@m.le.o.nosp@m.rg (comment2)
displayNameonly 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
addrSpeconly out: the addr-spec, i.e. "joe.user@example.org" in the example; in case of an error the return value is undefined
commentonly 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.

◆ splitAddressList()

QStringList KEmailAddress::splitAddressList ( const QString &  aStr)

Split a comma separated list of email addresses.

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