Checks if the value is a valid email address according to specific RFCs. More...

#include <Cutelyst/Plugins/Utils/validatoremail.h>

Inheritance diagram for Cutelyst::ValidatorEmail:

Public Types
enum	Category : quint8 { Valid, DNSWarn, RFC5321, CFWS, Deprecated, RFC5322, Error }
	Validation category, used as threshold to define valid addresses. More...

enum	Diagnose : quint8 { ValidAddress, DnsWarnNoMxRecord, DnsWarnNoRecord, RFC5321TLD, RFC5321TLDNumberic, RFC5321QuotedString, RFC5321AddressLiteral, RFC5321IPv6Deprecated, CFWSComment, CFWSFWS, DeprecatedLocalpart, DeprecatedFWS, DeprecatedQText, DeprecatedQP, DeprecatedComment, DeprecatedCText, DeprecatedCFWSNearAt, RFC5322Domain, RFC5322TooLong, RFC5322LocalTooLong, RFC5322DomainTooLong, RFC5322LabelTooLong, RFC5322DomainLiteral, RFC5322DomLitOBSDText, RFC5322IPv6GroupCount, RFC5322IPv62x2xColon, RFC5322IPv6BadChar, RFC5322IPv6MaxGroups, RFC5322IPv6ColonStart, RFC5322IPv6ColonEnd, ErrorExpectingDText, ErrorNoLocalPart, ErrorNoDomain, ErrorConsecutiveDots, ErrorATextAfterCFWS, ErrorATextAfterQS, ErrorATextAfterDomLit, ErrorExpectingQpair, ErrorExpectingAText, ErrorExpectingQText, ErrorExpectingCText, ErrorBackslashEnd, ErrorDotStart, ErrorDotEnd, ErrorDomainHyphenStart, ErrorDomainHyphenEnd, ErrorUnclosedQuotedStr, ErrorUnclosedComment, ErrorUnclosedDomLiteral, ErrorFWSCRLFx2, ErrorFWSCRLFEnd, ErrorCRnoLF, ErrorFatal }
	Single diagnose values that show why an address is not valid. More...

enum	Option : quint8 { NoOption, CheckDNS, UTF8Local, AllowIDN, AllowUTF8 }

Public Member Functions
	ValidatorEmail (const QString &field, Category threshold=RFC5321, Options options=NoOption, const ValidatorMessages &messages=ValidatorMessages(), const QString &defValKey=QString())
	Constructs a new email validator. More...

	~ValidatorEmail () override
	Deconstructs the email validator.

Public Member Functions inherited from Cutelyst::ValidatorRule
	ValidatorRule (const QString &field, const ValidatorMessages &messages=ValidatorMessages(), const QString &defValKey=QString())
	Constructs a new ValidatorRule with the given parameters. More...

virtual	~ValidatorRule ()
	Deconstructs the ValidatorRule.

Static Public Member Functions
static Category	category (Diagnose diagnose)
	Returns the category the diagnose belongs to. More...

static QString	categoryString (Context *c, Category category, const QString &label=QString())
	Returns a descriptive and translated string for the category. More...

static QString	categoryString (Context *c, Diagnose diagnose, const QString &label=QString())
	Returns a descriptive and translated string for the Category the diagnose belongs to. More...

static QString	diagnoseString (Context *c, Diagnose diagnose, const QString &label=QString())
	Returns a descriptive and translated string for the diagnose. More...

static bool	validate (const QString &email, Category threshold=RFC5321, Options options=NoOption, QList< Diagnose > *diagnoses=nullptr)
	Returns `true` if email is a valid address according to the Category given in the threshold. More...

Protected Member Functions
QString	genericValidationError (Context *c, const QVariant &errorData=QVariant()) const override
	Returns a generic error if validation failed.

ValidatorReturnType	validate (Context *c, const ParamsMultiMap &params) const override
	Performs the validation and returns the result. More...

Protected Member Functions inherited from Cutelyst::ValidatorRule
	ValidatorRule (ValidatorRulePrivate &dd)
	Constructs a new ValidatorRule object with the given private class. More...

void	defaultValue (Context c, ValidatorReturnType result, const char *validatorName) const
	I a defValKey has been set in the constructor, this will try to get the default value from the stash and put it into the result. More...

QString	field () const
	Returns the name of the field to validate. More...

virtual QString	genericParsingError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a generic error message if an error occures while parsing input. More...

virtual QString	genericValidationDataError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a generic error message if any validation data is missing or invalid. More...

QString	label (Context *c) const
	Returns the human readable field label used for generic error messages. More...

QString	parsingError (Context *c, const QVariant &errorData=QVariant()) const
	Returns an error message if an error occured while parsing input. More...

bool	trimBefore () const
	Returns true if the field value should be trimmed before validation. More...

QString	validationDataError (Context *c, const QVariant &errorData=QVariant()) const
	Returns an error message if any validation data is missing or invalid. More...

QString	validationError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a descriptive error message if validation failed. More...

QString	value (const ParamsMultiMap &params) const
	Returns the value of the field from the input params.

Detailed Description

You can use a Category as threshold to define which level of compliance you accpet as valid. The default threshold RFC5321 for example will only allow email addresses that can be sent without modification through SMTP. If the address would contain comments like (main address)test@example.com, it would not be valid because the CFWSComment diagnose is above the threshold. If it would contain a quoted string like "main test address"@example.com it would be valid because the RFC5321QuotedString diagnose is under the threshold.

The parser used to validate the email address is a reimplementation of Dominic Sayers’ isemail PHP parser.

Note: Unless validation is started with NoTrimming, whitespaces will be removed from the beginning and the end of the input value before validation. If the field's value is empty or if the field is missing in the input data, the validation will succeed without performing the validation itself. Use one of the required validators to require the field to be present and not empty.

See also: Validator for general usage of validators.

Definition at line 49 of file validatoremail.h.

Member Enumeration Documentation

◆ Category

enum Cutelyst::ValidatorEmail::Category : quint8

Enumerator
Valid	Address is completely valid.
DNSWarn	Address is valid but a DNS check was not successful. Diagnose in this category is only returned if checkDns ist set to `true`.
RFC5321	Address is valid for SMTP according to RFC 5321 but has unusual Elements.
CFWS	Address is valid within the message but can not be used unmodified for the envelope.
Deprecated	Address contains deprecated elements but may still be valid in restricted contexts.
RFC5322	Address is only valid according to the broad definition of RFC 5322. It is otherwise invalid.
Error	Address is invalid for any purpose.

Definition at line 56 of file validatoremail.h.

◆ Diagnose

enum Cutelyst::ValidatorEmail::Diagnose : quint8

Enumerator
ValidAddress	Address is valid. Please note that this does not mean the address actually exists, nor even that the domain actually exists. This address could be issued by the domain owner without breaking the rules of any RFCs.
DnsWarnNoMxRecord	Couldn't find a MX record for this domain but an A-record does exist.
DnsWarnNoRecord	Could neither find a MX record nor an A-record for this domain.
RFC5321TLD	Address is valid but at a Top Level Domain.
RFC5321TLDNumberic	Address is valid but the Top Level Domain begins with a number.
RFC5321QuotedString	Address is valid but contains a quoted string.
RFC5321AddressLiteral	Address is valid but a literal address not a domain.
RFC5321IPv6Deprecated	Address is valid but contains a :: that only elides one zero group. All implementations must accept and be able to handle any legitimate RFC 4291 format.
CFWSComment	Address contains comments.
CFWSFWS	Address contains Folding White Space.
DeprecatedLocalpart	The local part is in a deprecated form.
DeprecatedFWS	Address contains an obsolete form of Folding White Space.
DeprecatedQText	A quoted string contains a deprecated character.
DeprecatedQP	A quoted pair contains a deprecated character.
DeprecatedComment	Address contains a comment in a position that is deprecated.
DeprecatedCText	A comment contains a deprecated character.
DeprecatedCFWSNearAt	Address contains a comment or Folding White Space around the @ sign.
RFC5322Domain	Address is RFC 5322 compliant but contains domain characters that are not allowed by DNS.
RFC5322TooLong	Address is too long.
RFC5322LocalTooLong	The local part of the address is too long.
RFC5322DomainTooLong	The domain part is too long.
RFC5322LabelTooLong	The domain part contains an element that is too long.
RFC5322DomainLiteral	The domain literal is not a valid RFC 5321 address literal.
RFC5322DomLitOBSDText	The domain literal is not a valid RFC 5321 address literal and it contains obsolete characters.
RFC5322IPv6GroupCount	The IPv6 literal address contains the wrong number of groups.
RFC5322IPv62x2xColon	The IPv6 literal address contains too many :: sequences.
RFC5322IPv6BadChar	The IPv6 address contains an illegal group of characters.
RFC5322IPv6MaxGroups	The IPv6 address has too many groups.
RFC5322IPv6ColonStart	IPv6 address starts with a single colon.
RFC5322IPv6ColonEnd	IPv6 address ends with a single colon.
ErrorExpectingDText	A domain literal contains a character that is not allowed.
ErrorNoLocalPart	Address has no local part.
ErrorNoDomain	Address has no domain part.
ErrorConsecutiveDots	The address may not contain consecutive dots.
ErrorATextAfterCFWS	Address contains text after a comment or Folding White Space.
ErrorATextAfterQS	Address contains text after a quoted string.
ErrorATextAfterDomLit	Extra characters were found after the end of the domain literal.
ErrorExpectingQpair	The address contains a character that is not allowed in a quoted pair.
ErrorExpectingAText	Address contains a character that is not allowed.
ErrorExpectingQText	A quoted string contains a character that is not allowed.
ErrorExpectingCText	A comment contains a character that is not allowed.
ErrorBackslashEnd	The address can't end with a backslash.
ErrorDotStart	Neither part of the address may begin with a dot.
ErrorDotEnd	Neither part of the address may end with a dot.
ErrorDomainHyphenStart	A domain or subdomain cannot begin with a hyphen.
ErrorDomainHyphenEnd	A domain or subdomain cannot end with a hyphen.
ErrorUnclosedQuotedStr	Unclosed quoted string.
ErrorUnclosedComment	Unclosed comment.
ErrorUnclosedDomLiteral	Domain literal is missing its closing bracket.
ErrorFWSCRLFx2	Folding White Space contains consecutive CRLF sequences.
ErrorFWSCRLFEnd	Folding White Space ends with a CRLF sequence.
ErrorCRnoLF	Address contains a carriage return that is not followed by a line feed.
ErrorFatal	Fatal internal error while validating the address.

Definition at line 70 of file validatoremail.h.

◆ Option

enum Cutelyst::ValidatorEmail::Option : quint8

Enumerator
NoOption	No option enabled, the default.
CheckDNS	Enabled a DNS lookup to check if there are MX records for the mail domain.
UTF8Local	Allows UTF8 characters in the email address local part.
AllowIDN	Allows internationalized domain names (IDN).
AllowUTF8	Allows UTF8 characters in the email local part and internationalized domain names (IDN).

Definition at line 134 of file validatoremail.h.

Constructor & Destructor Documentation

◆ ValidatorEmail()

ValidatorEmail::ValidatorEmail	(	const QString &	field,
		Category	threshold = `RFC5321`,
		Options	options = `NoOption`,
		const ValidatorMessages &	messages = `ValidatorMessages()`,
		const QString &	defValKey = `QString()`
	)

Parameters

field	Name of the input field to validate.
options	Options for the validation process.
messages	Custom error messages if validation fails.
defValKey	Stash key containing a default value if input field is empty. This value will NOT be validated.

Definition at line 30 of file validatoremail.cpp.

Member Function Documentation

◆ category()

Cutelyst::ValidatorEmail::Category ValidatorEmail::category ( Diagnose diagnose )

static

Parameters

diagnose The Diagnose to get the Category for.

Returns: The Category the diagnose belongs to.

Definition at line 1563 of file validatoremail.cpp.

References CFWS, Deprecated, DNSWarn, Error, RFC5321, RFC5322, and Valid.

Referenced by categoryString().

◆ categoryString() [1/2]

QString ValidatorEmail::categoryString	(	Context *	c,
		Category	category,
		const QString &	label = `QString()`
	)

static

Parameters

c	The current Context, used for translation.
category	The Category to return the descriptive string for.
label	Optional label used in the category string.

Returns: Descriptive and translated string for the category.

Definition at line 1508 of file validatoremail.cpp.

References category(), CFWS, Deprecated, DNSWarn, Cutelyst::ValidatorRule::label(), RFC5321, RFC5322, Cutelyst::Context::translate(), and Valid.

Referenced by categoryString().

◆ categoryString() [2/2]

QString ValidatorEmail::categoryString	(	Context *	c,
		Diagnose	diagnose,
		const QString &	label = `QString()`
	)

static

Parameters

c	The current context, used for translation.
diagnose	The Diagnose to return the descriptive Category string for.
label	Optional label used in the category string.

Returns: Descriptive and translated string for the Category the diagnose belongs to.

Definition at line 1586 of file validatoremail.cpp.

References category(), categoryString(), and Cutelyst::ValidatorRule::label().

◆ diagnoseString()

QString ValidatorEmail::diagnoseString	(	Context *	c,
		Diagnose	diagnose,
		const QString &	label = `QString()`
	)

static

Parameters

c	The current Context, used for translation.
diagnose	The Diagnose to return the descriptive string for.
label	Optional label used in the diagnose string.

Returns: Descriptive and translated string for the diagnose.

Definition at line 1167 of file validatoremail.cpp.

References CFWSComment, CFWSFWS, DeprecatedCFWSNearAt, DeprecatedComment, DeprecatedCText, DeprecatedFWS, DeprecatedLocalpart, DeprecatedQP, DeprecatedQText, DnsWarnNoMxRecord, DnsWarnNoRecord, ErrorATextAfterCFWS, ErrorATextAfterDomLit, ErrorATextAfterQS, ErrorBackslashEnd, ErrorConsecutiveDots, ErrorCRnoLF, ErrorDomainHyphenEnd, ErrorDomainHyphenStart, ErrorDotEnd, ErrorDotStart, ErrorExpectingAText, ErrorExpectingCText, ErrorExpectingDText, ErrorExpectingQpair, ErrorExpectingQText, ErrorFatal, ErrorFWSCRLFEnd, ErrorFWSCRLFx2, ErrorNoDomain, ErrorNoLocalPart, ErrorUnclosedComment, ErrorUnclosedDomLiteral, ErrorUnclosedQuotedStr, Cutelyst::ValidatorRule::label(), RFC5321AddressLiteral, RFC5321IPv6Deprecated, RFC5321QuotedString, RFC5321TLD, RFC5321TLDNumberic, RFC5322Domain, RFC5322DomainLiteral, RFC5322DomainTooLong, RFC5322DomLitOBSDText, RFC5322IPv62x2xColon, RFC5322IPv6BadChar, RFC5322IPv6ColonEnd, RFC5322IPv6ColonStart, RFC5322IPv6GroupCount, RFC5322IPv6MaxGroups, RFC5322LabelTooLong, RFC5322LocalTooLong, RFC5322TooLong, Cutelyst::Context::translate(), and ValidAddress.

Referenced by genericValidationError().

◆ validate()

ValidatorReturnType ValidatorEmail::validate	(	Context *	c,
		const ParamsMultiMap &	params
	)		const

overrideprotectedvirtual

If validation succeeded, ValidatorReturnType::value will contain the cleaned up email address without any comments as QString. ValidatorReturnType::extra will contain a QList<Diagnose> list containing all issues found in the checked email, ordered from the highest to the lowest.

Implements Cutelyst::ValidatorRule.

Definition at line 39 of file validatoremail.cpp.

References Cutelyst::ValidatorRule::defaultValue(), Cutelyst::ValidatorReturnType::errorMessage, Cutelyst::ValidatorReturnType::extra, Cutelyst::ValidatorRule::validationError(), Cutelyst::ValidatorReturnType::value, and Cutelyst::ValidatorRule::value().

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Category

◆ Diagnose

◆ Option

Constructor & Destructor Documentation

◆ ValidatorEmail()

Member Function Documentation

◆ category()

◆ categoryString() [1/2]

◆ categoryString() [2/2]

◆ diagnoseString()

◆ validate()