libemailfunctions

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, InvalidDisplayName
}

Functions

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

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

Result type for splitAddress, isValidEmailAddress.

Definition at line 44 of file email.h.


Function Documentation

bool KPIM::compareEmail ( const TQString &  email1,
const TQString &  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.

Definition at line 795 of file email.cpp.

TQString KPIM::decodeIDN ( const TQString &  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

Definition at line 833 of file email.cpp.

TQString KPIM::emailParseResultToString ( EmailParseResult  errorCode  ) 

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

Parameters:
errorCode the errorCode from isValidEmailEmailAddress().
Returns:
An i18n ready string for use in msgboxes.

Definition at line 461 of file email.cpp.

TQString KPIM::encodeIDN ( const TQString &  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

Definition at line 848 of file email.cpp.

TQCString KPIM::getEmailAddress ( const TQCString &  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@example.org>"
Returns:
the addr-spec of address, i.e. joe.user@example.org in the example

Definition at line 571 of file email.cpp.

TQString KPIM::getEmailAddress ( const TQString &  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@example.org>"
Returns:
the addr-spec of address, i.e. joe.user@example.org in the example

Definition at line 589 of file email.cpp.

TQCString KPIM::getFirstEmailAddress ( const TQCString &  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@example.org>"
Returns:
the addr-spec of addresses, i.e. joe.user@example.org in the example

Definition at line 596 of file email.cpp.

TQString KPIM::getFirstEmailAddress ( const TQString &  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@example.org>"
Returns:
the addr-spec of addresses, i.e. joe.user@example.org in the example

Definition at line 614 of file email.cpp.

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

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.

Definition at line 621 of file email.cpp.

KPIM::EmailParseResult KPIM::isValidEmailAddress ( const TQString &  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.

Parameters:
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.

Definition at line 286 of file email.cpp.

bool KPIM::isValidSimpleEmailAddress ( const TQString &  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.

Parameters:
aStr a single email address, example: joe.user@example.org
Returns:
true if no error was encountered.

Definition at line 519 of file email.cpp.

char * KPIM::kAsciiToLower ( char *  str  ) 

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

This means that it affects only the ASCII characters A-Z.

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.

This means that it affects only the ASCII characters a-z.

Parameters:
str pointer to the string which should be converted to upper case
Returns:
pointer to the converted string (same as str)
TQString KPIM::normalizeAddressesAndDecodeIDNs ( const TQString &  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

Definition at line 863 of file email.cpp.

TQString KPIM::normalizeAddressesAndEncodeIDNs ( const TQString &  str  ) 

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

Definition at line 904 of file email.cpp.

TQString KPIM::normalizedAddress ( const TQString &  displayName,
const TQString &  addrSpec,
const TQString &  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

Definition at line 809 of file email.cpp.

TQString KPIM::quoteNameIfNecessary ( const TQString &  str  ) 

Add quote characters around the given string if it contains a character that makes that necessary, in an email name, such as ",".

Definition at line 973 of file email.cpp.

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

Definition at line 564 of file email.cpp.

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

Definition at line 258 of file email.cpp.

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

Definition at line 269 of file email.cpp.

TQStringList KPIM::splitEmailAddrList ( const TQString &  aStr  ) 

Split a comma separated list of email addresses.

Definition at line 31 of file email.cpp.