Class TImMessageField

class TImMessageField;

Description

Parses email message header fields for valid Internet email addresses, comments and aliases.

A comment is a string surrounded by parentheses, as defined in RFC822, 3.1.4.

An alias is defined as any substring which appears to the left of a legal email address: for example, the string "this is an alias" in "this is an alias <[email protected]>".

For email addresses, the string being parsed: 1) must contain an @ character, surrounded by valid address characters; 2) may not contain more than one address or @ character; 3) may contain aliases and comments.

Note the following about the implementation of this class:

1. Functions that test subject lines, ValidSubjectLine(), and alias names, ValidAliasName(), were initially written to test that the strings did not contain characters outside a limited ASCII range. Unicode characters are now allowed, so these functions now always return true.

2. Of the four overloads of GetValidInternetEmailAddressFromString(), only the first has a meaningful implementation.

Members

Defined in TImMessageField:
GetValidAlias(), GetValidAlias(), GetValidComment(), GetValidComment(), GetValidInternetEmailAddressFromString(), GetValidInternetEmailAddressFromString(), GetValidInternetEmailAddressFromString(), GetValidInternetEmailAddressFromString(), ValidAliasName(), ValidAliasName(), ValidInternetEmailAddress(), ValidInternetEmailAddress(), ValidInternetEmailAddress(), ValidInternetEmailAddress(), ValidInternetEmailAddressChar(), ValidSubjectLine(), ValidSubjectLine(), ValidSubjectLineChar()

IMPORT_C TBool ValidInternetEmailAddress(const TDesC16 &aAddress);

Description

Tests if the specified string contains a valid email address.

Parameters

const TDesC16 &aAddress String to test

Return value

TBool ETrue if aAddress contains one valid email address. The email address can contain aliases and comments. EFalse otherwise.

IMPORT_C TBool ValidInternetEmailAddress(const TDesC16 &aAddress, TInt &rFirstBadCharPos);

Description

Tests if the specified string contains a valid email address.

Parameters

const TDesC16 &aAddress String to test TInt &rFirstBadCharPos On return, if the test has succeeded, the character position in aAddress where the email address begins. If the test fails, the position of the character that caused the test to fail.

Return value

TBool ETrue if aAddress contains one valid email address; EFalse otherwise.

IMPORT_C TBool ValidInternetEmailAddress(const TDesC16 &aAddress, TInt &rFirstChar, TInt &rLastChar);

Description

Tests if the specified string contains a valid email address.

Parameters

const TDesC16 &aAddress String to test TInt &rFirstChar On return, if the test has succeeded, the character position in aAddress where the email address begins. If the test fails, the position of the character that caused the test to fail. TInt &rLastChar On return, if the test has succeeded, the character position in aAddress where the email address ends.

Return value

TBool ETrue if aAddress contains one valid email address; EFalse otherwise.

IMPORT_C TBool ValidInternetEmailAddress(const TDesC16 &aAddress, TInt &rFirstChar, TInt &rLastChar, TInt &rFirstBadCharPos);

Description

Tests if the specified string contains a valid email address.

Parameters

const TDesC16 &aAddress String to test TInt &rFirstChar On return, if the test has succeeded, the character position in aAddress where the email address begins. If the test fails, the position of the character that caused the test to fail. TInt &rLastChar On return, if the test has succeeded, the character position in aAddress where the email address ends. TInt &rFirstBadCharPos On return, if the test has succeeded, KErrNotFound. If the test fails, the position of the character that caused the test to fail.

Return value

TBool ETrue if aAddress contains one valid email address; EFalse otherwise.

IMPORT_C TBool ValidInternetEmailAddressChar(const TChar &aChar);

Description

Tests if the specified character is valid (in ASCII range 32-127) for use in an email address.

Parameters

const TChar &aChar Character to test

Return value

TBool ETrue if test succeeds; EFalse otherwise.

IMPORT_C TBool ValidSubjectLine(const TDesC16 &aSubjectLine);

Description

This function always returns true, so can be ignored.

Parameters

const TDesC16 &aSubjectLine Unused

Return value

TBool Always ETrue

IMPORT_C TBool ValidSubjectLine(const TDesC16 &aSubjectLine, TInt &rFirstBadCharPos);

Description

This function always returns true, so can be ignored.

Parameters

const TDesC16 &aSubjectLine Unused TInt &rFirstBadCharPos Unused

Return value

TBool Always ETrue

IMPORT_C TBool ValidSubjectLineChar(const TChar &aChar);

Description

This function always returns true, so can be ignored.

Parameters

const TChar &aChar Unused

Return value

TBool Always ETrue

IMPORT_C TBool ValidAliasName(const TDesC16 &aAliasName);

Description

This function always returns true, so can be ignored.

Parameters

const TDesC16 &aAliasName Unused

Return value

TBool Always ETrue

IMPORT_C TBool ValidAliasName(const TDesC16 &aAliasName, TInt &rFirstBadCharPos);

Description

This function always returns true, so can be ignored.

Parameters

const TDesC16 &aAliasName Unused TInt &rFirstBadCharPos Unused

Return value

TBool Always ETrue

IMPORT_C TPtrC16 GetValidInternetEmailAddressFromString(const TDesC16 &aAddress);

Description

Gets a valid email address, if one exists, from the specified string.

Parameters

const TDesC16 &aAddress String to parse

Return value

TPtrC16 If a valid email address was found in aAddress, a pointer descriptor to the address part (without surrounding aliases or comments). If an address could not be found, the whole of the original aAddress string is returned.

IMPORT_C TPtrC16 GetValidInternetEmailAddressFromString(const TDesC16 &aAddress, TInt &rError);

Description

Gets a valid email address, if one exists, from the specified string.

This does not differ in functionality from the other overload of GetValidInternetEmailAddressFromString().

Parameters

const TDesC16 &aAddress String to parse TInt &rError On return, always KErrNone

Return value

TPtrC16 If a valid email address was found in aAddress, a pointer descriptor to the address substring (without surrounding aliases or comments). If an address could not be found, the whole of the original aAddress string is returned.

IMPORT_C TPtrC16 GetValidInternetEmailAddressFromString(const TDesC16 &aAddress, TInt &rFirstChar, TInt &rLastChar);

Description

This function overload is not implemented.

Parameters

const TDesC16 &aAddress String to parse TInt &rFirstChar Unused TInt &rLastChar Unused

Return value

TPtrC16 Original aAddress string

IMPORT_C TPtrC16 GetValidInternetEmailAddressFromString(const TDesC16 &aAddress, TInt &rFirstChar, TInt &rLastChar, TInt &rError);

Description

This function overload is not implemented.

Parameters

const TDesC16 &aAddress String to parse TInt &rFirstChar Unused TInt &rLastChar Unused TInt &rError Unused

Return value

TPtrC16 Original aAddress string

IMPORT_C TPtrC16 GetValidAlias(const TDesC16 &aAddress);

Description

Gets a valid alias, if one exists, from the specified string.

A valid alias is defined here as being any substring that appears to the left of a legal email address.

Parameters

const TDesC16 &aAddress String to parse

Return value

TPtrC16 If a valid alias was found in aAddress, a pointer descriptor to the alias substring. If a valid alias could not be found, the whole of the original aAddress string is returned.

IMPORT_C TPtrC16 GetValidAlias(const TDesC16 &aAddress, TInt &rError);

Description

Gets a valid alias, if one exists, from the specified string.

A valid alias is defined here as being any substring that appears to the left of a legal email address.

This overload supplies an error code in rError if an alias was not found.

Parameters

const TDesC16 &aAddress String to parse TInt &rError On return, KErrNone if a valid alias was found; otherwise, KErrNotFound.

Return value

TPtrC16 If a valid alias was found in aAddress, a pointer descriptor to the alias substring. If a valid alias could not be found, the whole of the original aAddress string is returned.

IMPORT_C TPtrC16 GetValidComment(const TDesC16 &aAddress);

Description

Gets a valid comment, if one exists, from the specified string.

A valid comment is found if the string contains both: 1) a legal email address; and 2) a comment (text surrounded by parentheses).

Parameters

const TDesC16 &aAddress String to parse

Return value

TPtrC16 If a valid comment was found in aAddress, a pointer descriptor to the comment substring. If a valid comment could not be found, the whole of the original aAddress string is returned.

IMPORT_C TPtrC16 GetValidComment(const TDesC16 &aAddress, TInt &rError);

Description

Gets a valid comment, if one exists, from the specified string.

A valid comment is found if the string contains both: 1) a legal email address; and 2) a comment (text surrounded by parentheses).

This overload supplies an error code in rError if a comment was not found.

Parameters

const TDesC16 &aAddress String to parse TInt &rError On return, KErrNone if a valid alias was found; otherwise, KErrNotFound.

Return value

TPtrC16 If a valid comment was found in aAddress, a pointer descriptor to the comment substring. If a valid comment could not be found, the whole of the original aAddress string is returned.