Cutelyst::ValidatorEmail Class Reference

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 : int {   Valid , DNSWarn , DNSFailed , RFC5321 ,   CFWS , Deprecated , RFC5322 , Error }
	Validation category, used as threshold to define valid addresses. More...
enum	Diagnose : int {   ValidAddress , DnsWarnNoMxRecord , DnsMxDisabled , DnsNoRecordFound ,   DnsErrorTimeout , DnsError , RFC5321TLD , RFC5321TLDNumeric ,   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={}, const QString &defValKey={})
	~ValidatorEmail () override
Public Member Functions inherited from Cutelyst::ValidatorRule
	ValidatorRule (const QString &field, const ValidatorMessages &messages={}, const QString &defValKey={}, QByteArrayView validatorName=nullptr)
virtual	~ValidatorRule ()
	Deconstructs the ValidatorRule.

Static Public Member Functions
static Category	category (Diagnose diagnose)
static QString	categoryString (Context *c, Category category, const QString &label={})
static QString	categoryString (Context *c, Diagnose diagnose, const QString &label={})
static QString	diagnoseString (Context *c, Diagnose diagnose, const QString &label={})
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.
static void	validateCb (const QString &email, Category threshold, Options options, std::function< void(bool isValid, const QString &cleanedEmail, const QList< Diagnose > &diagnoses)> cb)
	Checks if the email is a valid address according to the Category given in the threshold.

Protected Member Functions
QString	genericValidationError (Context *c, const QVariant &errorData=QVariant()) const override
ValidatorReturnType	validate (Context *c, const ParamsMultiMap &params) const override
void	validateCb (Context *c, const ParamsMultiMap &params, ValidatorRtFn cb) const override
Protected Member Functions inherited from Cutelyst::ValidatorRule
	ValidatorRule (ValidatorRulePrivate &dd)
QString	debugString (const Context *c) const
void	defaultValue (Context *c, ValidatorReturnType *result) const
void	defaultValue (Context *c, ValidatorRtFn cb) const
QString	field () const noexcept
virtual QString	genericParsingError (Context *c, const QVariant &errorData={}) const
virtual QString	genericValidationDataError (Context *c, const QVariant &errorData={}) const
QString	label (const Context *c) const
QString	parsingError (Context *c, const QVariant &errorData={}) const
bool	trimBefore () const noexcept
QString	validationDataError (Context *c, const QVariant &errorData={}) const
QString	validationError (Context *c, const QVariant &errorData={}) const
QString	value (const ParamsMultiMap &params) const

Additional Inherited Members
Related Symbols inherited from Cutelyst::ValidatorRule
using	ValidatorRtFn = std::function< void(ValidatorReturnType &&result)>
	Void callback function for validator rules that processes the ValidatorReturnType.

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

Return type

On success, 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.

See also

Validator for general usage of validators.

Definition at line 46 of file validatoremail.h.

Member Enumeration Documentation

Category

enum Cutelyst::ValidatorEmail::Category : int

Enumerator
Valid	Address is completely valid.
DNSWarn	Address is valid but there are warnings about the DNS. Diagnose in this category is only returned if the ValidatorEmail::CheckDNS option is set.
DNSFailed	Address is valid but a DNS check was not successful. Diagnose in this category is only returned if the ValidatorEmail::CheckDNS option is set.
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. Using this as threshold, all addresses are valid.

Definition at line 153 of file validatoremail.h.

Diagnose

enum Cutelyst::ValidatorEmail::Diagnose : int

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. When a MX record is missing, an A/AAAA record is used as fallback. This is often misconfigured where there is no mail exchange running on the server that has the A/AAAA record. See also RFC 7505.
DnsMxDisabled	MX is explicitely disabled for this domain. See also RFC 7505.
DnsNoRecordFound	Could neither find a MX record nor an A record for this domain.
DnsErrorTimeout	Failed to resolve DNS records within timeout.
DnsError	Failed to resolve DNS records because of an error in the DNS resolution.
RFC5321TLD	Address is valid but at a Top Level Domain.
RFC5321TLDNumeric	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 53 of file validatoremail.h.

Option

enum Cutelyst::ValidatorEmail::Option : quint8

Enumerator
NoOption	No option enabled, the default.
CheckDNS	Enables a DNS lookup to check if there are MX records for the mail domain. Since Cutelyst 5.0.0 this only works on validateCb().
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 176 of file validatoremail.h.

Constructor & Destructor Documentation

ValidatorEmail()

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

explicit

Constructs a new ValidatorEmail object with the given parameters.

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 25 of file validatoremail.cpp.

~ValidatorEmail()

ValidatorEmail::~ValidatorEmail ( )

overridedefault

Destroys the ValidatorEmail object.

Member Function Documentation

category()

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

static

Returns the category the diagnose belongs to.

Parameters

diagnose

The Diagnose to get the Category for.

Returns

The Category the diagnose belongs to.

Definition at line 1736 of file validatoremail.cpp.

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

Referenced by categoryString(), and categoryString().

categoryString() [1/2]

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

static

Returns a descriptive and translated string for the category.

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 1671 of file validatoremail.cpp.

References QString::arg(), category(), CFWS, Deprecated, DNSFailed, DNSWarn, QString::isEmpty(), Cutelyst::ValidatorRule::label(), Cutelyst::Context::qtTrId(), RFC5321, RFC5322, and Valid.

Referenced by categoryString().

categoryString() [2/2]

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

static

Returns a descriptive and translated string for the Category the diagnose belongs to.

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 1761 of file validatoremail.cpp.

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

diagnoseString()

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

static

Returns a descriptive and translated string for the diagnose.

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 1261 of file validatoremail.cpp.

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

Referenced by genericValidationError().

genericValidationError()

QString ValidatorEmail::genericValidationError ( Context *  c, const QVariant &  errorData = QVariant()  ) const

overrideprotectedvirtual

Returns a generic error if validation failed.

Reimplemented from Cutelyst::ValidatorRule.

Definition at line 102 of file validatoremail.cpp.

References diagnoseString(), Cutelyst::ValidatorRule::label(), and QVariant::value().

validate()

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

overrideprotectedvirtual

Performs the validation on the input params and returns the result.

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.

Note

Since Cutelyst 5.0.0 this will not perform any DNS lookup, even if ValidatorEmail::CheckDNS has been set to the options. For DNS lookups use validateCb().

Implements Cutelyst::ValidatorRule.

Definition at line 36 of file validatoremail.cpp.

References CheckDNS, Cutelyst::ValidatorRule::defaultValue(), Cutelyst::ValidatorReturnType::errorMessage, Cutelyst::ValidatorReturnType::extra, QString::isEmpty(), QVariant::setValue(), Cutelyst::ValidatorRule::validationError(), Cutelyst::ValidatorReturnType::value, and Cutelyst::ValidatorRule::value().

validateCb()

void ValidatorEmail::validateCb ( Context *  c, const ParamsMultiMap &  params, ValidatorRtFn  cb  ) const

overrideprotectedvirtual

Performs the validation on the input params and calls the cb with the ValidatorReturnType as argument.

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.

Since

Cutelyst 5.0.0

Reimplemented from Cutelyst::ValidatorRule.

Definition at line 73 of file validatoremail.cpp.

References QString::isEmpty(), validateCb(), and Cutelyst::ValidatorRule::value().