KEmailAddress Namespace
| Header: | #include <KEmailAddress> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS Codecs)target_link_libraries(mytarget PRIVATE KF6::Codecs) |
| Since: | 5.5 |
Types
| enum | EmailParseResult { AddressOk, AddressEmpty, UnexpectedEnd, UnbalancedParens, MissingDomainPart, …, TooFewDots } |
Functions
| bool | compareEmail(const QString &email1, const QString &email2, bool matchName) |
| QString | decodeMailtoUrl(const QUrl &mailtoUrl) |
| QString | emailParseResultToString(KEmailAddress::EmailParseResult errorCode) |
| QUrl | encodeMailtoUrl(const QString &mailbox) |
| QByteArray | extractEmailAddress(const QByteArray &address) |
| QString | extractEmailAddress(const QString &address) |
(since 5.11.0) QByteArray | extractEmailAddress(const QByteArray &address, QString &errorMessage) |
(since 5.11) QString | extractEmailAddress(const QString &address, QString &errorMessage) |
| bool | extractEmailAddressAndName(const QString &aStr, QString &mail, QString &name) |
| QByteArray | firstEmailAddress(const QByteArray &addresses) |
| QString | firstEmailAddress(const QString &addresses) |
(since 5.11.0) QByteArray | firstEmailAddress(const QByteArray &addresses, QString &errorMessage) |
(since 5.11.0) QString | firstEmailAddress(const QString &addresses, QString &errorMessage) |
| QString | fromIdn(const QString &addrSpec) |
| KEmailAddress::EmailParseResult | isValidAddress(const QString &aStr) |
| KEmailAddress::EmailParseResult | isValidAddressList(const QString &aStr, QString &badAddr) |
| bool | isValidSimpleAddress(const QString &aStr) |
| QString | normalizeAddressesAndDecodeIdn(const QString &addresses) |
| QString | normalizeAddressesAndEncodeIdn(const QString &str) |
| QString | normalizedAddress(const QString &displayName, const QString &addrSpec, const QString &comment = QString()) |
| QString | quoteNameIfNecessary(const QString &str) |
| QString | simpleEmailAddressErrorMsg() |
| KEmailAddress::EmailParseResult | splitAddress(const QByteArray &address, QByteArray &displayName, QByteArray &addrSpec, QByteArray &comment) |
| KEmailAddress::EmailParseResult | splitAddress(const QString &address, QString &displayName, QString &addrSpec, QString &comment) |
| QStringList | splitAddressList(const QString &aStr) |
| QString | toIdn(const QString &addrSpec) |
Detailed Description
Type Documentation
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().
| Constant | Value | Description |
|---|---|---|
KEmailAddress::AddressOk | 0 | Email is valid |
KEmailAddress::AddressEmpty | 1 | The address is empty |
KEmailAddress::UnexpectedEnd | 2 | Something is unbalanced |
KEmailAddress::UnbalancedParens | 3 | Unbalanced ( ) |
KEmailAddress::MissingDomainPart | 4 | No domain in address |
KEmailAddress::UnclosedAngleAddr | 5 | < with no matching > |
KEmailAddress::UnopenedAngleAddr | 6 | > with no preceding < |
KEmailAddress::TooManyAts | 7 | More than one @ in address |
KEmailAddress::UnexpectedComma | 8 | Comma not allowed here |
KEmailAddress::TooFewAts | 9 | Missing @ in address |
KEmailAddress::MissingLocalPart | 10 | No address specified, only domain |
KEmailAddress::UnbalancedQuote | 11 | Quotes (single or double) not matched |
KEmailAddress::NoAddressSpec | 12 | |
KEmailAddress::DisallowedChar | 13 | An invalid character detected in address |
KEmailAddress::InvalidDisplayName | 14 | An invalid displayname detected in address |
KEmailAddress::TooFewDots | 15 | Missing . in address |
Function Documentation
bool KEmailAddress::compareEmail(const QString &email1, const QString &email2, bool matchName)
Compare two email addresses. If matchName is false, it just checks the email address, and returns true if this matches. If matchName is true, both the name and the email must be the same.
email1 the first email address to use for comparison
email2 the second email address to use for comparison
matchName if set to true email address and displayname must match
Returns true if the comparison matches true in all other cases
QString KEmailAddress::decodeMailtoUrl(const QUrl &mailtoUrl)
Extracts the mailbox out of the mailto: URL.
mailtoUrl the URL with the mailto protocol, which contains the mailbox to be extracted
Returns the mailbox, which means the display name and the address specification.
QString KEmailAddress::emailParseResultToString(KEmailAddress::EmailParseResult errorCode)
Translate the enum errorcodes from emailParseResult into i18n'd strings that can be used for msg boxes.
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.
QUrl KEmailAddress::encodeMailtoUrl(const QString &mailbox)
Creates a valid mailto: URL from the given mailbox.
mailbox The mailbox, which means the display name and the address specification, for example "Thomas McGuire" <thomas@domain.com>. The display name is optional.
Returns a valid mailto: URL for the given mailbox.
QByteArray KEmailAddress::extractEmailAddress(const QByteArray &address)
Returns the pure email address (addr-spec in RFC2822) of the given address (mailbox in RFC2822).
address an email address, e.g. "Joe User <joe.user@example.org>"
Returns the addr-spec of address, i.e. joe.user@example.org in the example
QString KEmailAddress::extractEmailAddress(const QString &address)
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns the pure email address (addr-spec in RFC2822) of the given address (mailbox in RFC2822).
address an email address, e.g. "Joe User <joe.user@example.org>"
Returns the addr-spec of address, i.e. joe.user@example.org in the example
[since 5.11.0] QByteArray KEmailAddress::extractEmailAddress(const QByteArray &address, QString &errorMessage)
Returns the pure email address (addr-spec in RFC2822) of the given address (mailbox in RFC2822).
address an email address, e.g. "Joe User <joe.user@example.org>"
errorMessage return error message when we can't parse email
Returns the addr-spec of address, i.e. joe.user@example.org in the example
This function was introduced in 5.11.0.
[since 5.11] QString KEmailAddress::extractEmailAddress(const QString &address, QString &errorMessage)
Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of addresses.
address an email address, e.g. "Joe User <joe.user@example.org>"
errorMessage return error message when we can't parse email
Returns the addr-spec of address, i.e. joe.user@example.org in the example
This function was introduced in 5.11.
bool KEmailAddress::extractEmailAddressAndName(const QString &aStr, QString &mail, QString &name)
Return email address and name from string. Examples: "Stefan Taferner <taferner@example.org>" returns "taferner@example.org" and "Stefan Taferner". "joe@example.com" returns "joe@example.com" and "". Note that this only returns the first address.
Also note that the return value is true if both the name and the mail are not empty: this does NOT tell you if mail contains a valid email address or just some rubbish.
aStr an email address, e.g "Joe User <joe.user@example.org>"
name only out: returns the displayname, "Joe User" in the example
mail only out: returns the email address "joe.user@example.org" in the example
Returns true if both name and email address are not empty
QByteArray KEmailAddress::firstEmailAddress(const QByteArray &addresses)
Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of addresses.
addresses an email address, e.g. "Joe User <joe.user@example.org>"
Returns the addr-spec of addresses, i.e. joe.user@example.org in the example
QString KEmailAddress::firstEmailAddress(const QString &addresses)
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of addresses.
addresses an email address, e.g. "Joe User <joe.user@example.org>"
Returns the addr-spec of addresses, i.e. joe.user@example.org in the example
[since 5.11.0] QByteArray KEmailAddress::firstEmailAddress(const QByteArray &addresses, QString &errorMessage)
Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of addresses.
addresses an email address, e.g. "Joe User <joe.user@example.org>"
errorMessage return error message when we can't parse email
Returns the addr-spec of addresses, i.e. joe.user@example.org in the example
This function was introduced in 5.11.0.
[since 5.11.0] QString KEmailAddress::firstEmailAddress(const QString &addresses, QString &errorMessage)
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of addresses.
addresses an email address, e.g. "Joe User <joe.user@example.org>"
errorMessage return error message when we can't parse email
Returns the addr-spec of addresses, i.e. joe.user@example.org in the example
This function was introduced in 5.11.0.
QString KEmailAddress::fromIdn(const QString &addrSpec)
Decodes the punycode domain part of the given addr-spec if it's an IDN.
addrSpec a pure 7-bit email address (addr-spec in RFC2822)
Returns the email address with Unicode domain
KEmailAddress::EmailParseResult KEmailAddress::isValidAddress(const QString &aStr)
Validates an email address in the form of "Joe User" <joe@example.org>. Returns AddressOk if no error was encountered. Otherwise an appropriate error code is returned.
aStr a single email address, example: Joe User (comment1) <joe.user@example.org>
Returns AddressOk if no error was encountered. Otherwise an appropriate error code is returned.
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.
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.
bool KEmailAddress::isValidSimpleAddress(const QString &aStr)
Validates an email address in the form of joe@example.org. 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.
aStr a single email address, example: joe.user@example.org
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.
QString KEmailAddress::normalizeAddressesAndDecodeIdn(const QString &addresses)
Normalizes all email addresses in the given list and decodes all IDNs.
addresses a list of email addresses with punycoded IDNs
Returns the email addresses in normalized form with Unicode IDNs
QString KEmailAddress::normalizeAddressesAndEncodeIdn(const QString &str)
Normalizes all email addresses in the given list and encodes all IDNs in punycode.
str a list of email addresses
Returns the email addresses in normalized form
QString KEmailAddress::normalizedAddress(const QString &displayName, const QString &addrSpec, const QString &comment = QString())
Returns a normalized address built from the given parts. The normalized address is of one the following forms: - displayName (comment) <addrSpec> - displayName <addrSpec> - comment <addrSpec> - addrSpec
displayName the display name of the address
addrSpec the actual email address (addr-spec in RFC 2822)
comment a comment
Returns a normalized address built from the given parts
QString KEmailAddress::quoteNameIfNecessary(const QString &str)
Add quote characters around the given string if it contains a character that makes that necessary, in an email name, such as ",".
str a string that may need quoting
Returns the string quoted if necessary
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.
KEmailAddress::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.
address a single email address, example: Joe User (comment1) <joe.user@example.org> (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.
KEmailAddress::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.
address a single email address, example: Joe User (comment1) <joe.user@example.org> (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.
QStringList KEmailAddress::splitAddressList(const QString &aStr)
Split a comma separated list of email addresses.
aStr a single string representing a list of addresses
Returns a list of strings, where each string is one address from the original list
QString KEmailAddress::toIdn(const QString &addrSpec)
Encodes the domain part of the given addr-spec in punycode if it's an IDN.
addrSpec a pure email address with Unicode domain
Returns the email address with domain in punycode