Cutelyst  2.5.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
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:
Inheritance graph
[legend]

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 ()
 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...
 
 ~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

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

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

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
fieldName of the input field to validate.
optionsOptions for the validation process.
messagesCustom error messages if validation fails.
defValKeyStash 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
diagnoseThe Diagnose to get the Category for.
Returns
The Category the diagnose belongs to.

Definition at line 1565 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
cThe current Context, used for translation.
categoryThe Category to return the descriptive string for.
labelOptional label used in the category string.
Returns
Descriptive and translated string for the category.

Definition at line 1510 of file validatoremail.cpp.

References CFWS, Deprecated, DNSWarn, 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
cThe current context, used for translation.
diagnoseThe Diagnose to return the descriptive Category string for.
labelOptional label used in the category string.
Returns
Descriptive and translated string for the Category the diagnose belongs to.

Definition at line 1588 of file validatoremail.cpp.

References category(), categoryString(), and validate().

◆ diagnoseString()

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

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