KPIM Namespace Reference

KPIM holds all kinds of functions specific to KDE PIM. More...

Classes

class IdMapper
An Id Mapper maps Ids. More...
class NetworkStatus
This is a class for monitoring network status -- basically, the machine KDE is running on going from "online" mode to offline. More...

Enumerations

enum EmailParseResult {
  AddressOk, AddressEmpty, UnexpectedEnd, UnbalancedParens,
  MissingDomainPart, UnclosedAngleAddr, UnopenedAngleAddr, TooManyAts,
  UnexpectedComma, TooFewAts, MissingLocalPart, UnbalancedQuote,
  NoAddressSpec, DisallowedChar
}

Functions

KDE_EXPORT QStringList splitEmailAddrList (const QString &aStr)
KDE_EXPORT EmailParseResult splitAddress (const QCString &address, QCString &displayName, QCString &addrSpec, QCString &comment)
KDE_EXPORT EmailParseResult splitAddress (const QString &address, QString &displayName, QString &addrSpec, QString &comment)
KDE_EXPORT EmailParseResult isValidEmailAddress (const QString &aStr)
KDE_EXPORT QString emailParseResultToString (EmailParseResult errorCode)
KDE_EXPORT bool isValidSimpleEmailAddress (const QString &aStr)
KDE_EXPORT QString simpleEmailAddressErrorMsg ()
KDE_EXPORT QCString getEmailAddress (const QCString &address)
KDE_EXPORT QString getEmailAddress (const QString &address)
KDE_EXPORT QCString getFirstEmailAddress (const QCString &addresses)
KDE_EXPORT QString getFirstEmailAddress (const QString &addresses)
KDE_EXPORT bool getNameAndMail (const QString &aStr, QString &name, QString &mail)
KDE_EXPORT bool compareEmail (const QString &email1, const QString &email2, bool matchName)
KDE_EXPORT QString normalizedAddress (const QString &displayName, const QString &addrSpec, const QString &comment)
KDE_EXPORT QString decodeIDN (const QString &addrSpec)
KDE_EXPORT QString encodeIDN (const QString &addrSpec)
KDE_EXPORT QString normalizeAddressesAndDecodeIDNs (const QString &addresses)
KDE_EXPORT QString normalizeAddressesAndEncodeIDNs (const QString &str)
KDE_EXPORT QString quoteNameIfNecessary (const QString &str)
static unsigned char ASCIIToLower (unsigned char ch)
char * kAsciiToLower (char *s)
static unsigned char ASCIIToUpper (unsigned char ch)
char * kAsciiToUpper (char *s)

Detailed Description

KPIM holds all kinds of functions specific to KDE PIM.

The KPIM namespace hides away functions, enums, and other things that are KDE PIM specific and that we don't want to have polluting the global namespace.

Enumeration Type Documentation

enum EmailParseResult

Result type for splitAddress.

Function Documentation

QStringList KPIM::splitEmailAddrList

(

const QString &

aStr

)

Split a comma separated list of email addresses.

KPIM::EmailParseResult KPIM::splitAddress	(	const QCString &	address,
		QCString &	displayName,
		QCString &	addrSpec,
		QCString &	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:

	address	a single email address, example: Joe User (comment1) <joe.user@kde.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@kde.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.

KPIM::EmailParseResult KPIM::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:

	address	a single email address, example: Joe User (comment1) <joe.user@kde.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@kde.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.

KPIM::EmailParseResult KPIM::isValidEmailAddress

(

const QString &

aStr

)

Validates an email address in the form of "Joe User" <joe@kde.org>.

Returns AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

Parameters:

aStr

a single email address, example: Joe User (comment1) <joe.user@kde.org>

Returns:: AddressOk if no error was encountered. Otherwise an appropriate error code is returned.

QString KPIM::emailParseResultToString

(

EmailParseResult

errorCode

)

Translate the enum errorcodes from emailParseResult into i18n'd strings that can be used for msg boxes.

bool KPIM::isValidSimpleEmailAddress

(

const QString &

aStr

)

Validates an email address in the form of joe@kde.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.

Parameters:

aStr

a single email address, example: joe.user@kde.org

Returns:: true if no error was encountered.

QString KPIM::simpleEmailAddressErrorMsg

(

)

Returns a i18n string to be used in msgboxes this allows for error messages to be the same across the board.

QCString KPIM::getEmailAddress

(

const QCString &

address

)

Returns the pure email address (addr-spec in RFC2822) of the given address (mailbox in RFC2822).

Parameters:

address

an email address, e.g. "Joe User <joe.user@kde.org>"

Returns:: the addr-spec of address, i.e. joe.user@kde.org in the example

QString KPIM::getEmailAddress

(

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

Parameters:

address

an email address, e.g. "Joe User <joe.user@kde.org>"

Returns:: the addr-spec of address, i.e. joe.user@kde.org in the example

QCString KPIM::getFirstEmailAddress

(

const QCString &

addresses

)

Returns the pure email address (addr-spec in RFC2822) of the first email address of a list of addresses.

Parameters:

addresses

an email address, e.g. "Joe User <joe.user@kde.org>"

Returns:: the addr-spec of addresses, i.e. joe.user@kde.org in the example

QString KPIM::getFirstEmailAddress

(

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.

Parameters:

addresses

an email address, e.g. "Joe User <joe.user@kde.org>"

Returns:: the addr-spec of addresses, i.e. joe.user@kde.org in the example

bool KPIM::getNameAndMail	(	const QString &	aStr,
		QString &	name,
		QString &	mail
	)

Return email address and name from string.

Examples: "Stefan Taferner <taferner@kde.org>" returns "taferner@kde.org" and "Stefan Taferner". "joe@nowhere.com" returns "joe@nowhere.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.

bool KPIM::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.

QString KPIM::normalizedAddress	(	const QString &	displayName,
		const QString &	addrSpec,
		const QString &	comment
	)

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

Parameters:

	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 KPIM::decodeIDN

(

const QString &

addrSpec

)

Decodes the punycode domain part of the given addr-spec if it's an IDN.

Parameters:

addrSpec

a pure 7-bit email address (addr-spec in RFC2822)

Returns:: the email address with Unicode domain

QString KPIM::encodeIDN

(

const QString &

addrSpec

)

Encodes the domain part of the given addr-spec in punycode if it's an IDN.

Parameters:

addrSpec

a pure email address with Unicode domain

Returns:: the email address with domain in punycode

QString KPIM::normalizeAddressesAndDecodeIDNs

(

const QString &

addresses

)

Normalizes all email addresses in the given list and decodes all IDNs.

Parameters:

addresses

a list of email addresses with punycoded IDNs

Returns:: the email addresses in normalized form with Unicode IDNs

QString KPIM::normalizeAddressesAndEncodeIDNs

(

const QString &

str

)

Normalizes all email addresses in the given list and encodes all IDNs in punycode.

QString KPIM::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 ",".

char * KPIM::kAsciiToLower

(

char *

str

)

Locale-independent function to convert ASCII strings to lower case ASCII strings.

Parameters:

str

pointer to the string which should be converted to lower case

Returns:: pointer to the converted string (same as str)

char * KPIM::kAsciiToUpper

(

char *

str

)

Locale-independent function to convert ASCII strings to upper case ASCII strings.

Parameters:

str

pointer to the string which should be converted to upper case

Returns:: pointer to the converted string (same as str)

libemailfunctions

API Docs

KPIM Namespace Reference

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation