Collapse all Symbian^3 Product Developer Library

CTulAddressStringTokenizer Class Reference

class CTulAddressStringTokenizer : public CBase

Address String Tokenizer API offers methods for parsing phone numbers and e-mail, URL and URI addresses from the given text. The API consists of the CTulAddressStringTokenizer class.

Usage:

 #include <tuladdressstringtokenizer.h>

 // SFoundItem instance
 CTulAddressStringTokenizer::SFoundItem item;

 // Some text
 TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567. 
 You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra."));
	
 // First the user has to create an instance of CTulAddressStringTokenizer by using the
 // factory method NewL(). The method takes two parameters. The first 
 // parameter defines the text to be searched from and the second parameter 
 // tells what exactly is being looked for.
 CTulAddressStringTokenizer singleSearch = CTulAddressStringTokenizer::NewL(strSomeText, 
                  CTulAddressStringTokenizer::EFindItemSearchMailAddressBin);

 // The passed text is parsed in construction, and found items can be fetched 
 // by using the ItemArray() method. It returns a constant array containing 
 // all the found items. The interface also offers helper functions for 
 // handling the item array by itself. 

 // Get count of found items.
 TInt count(singleSearch->ItemCount());

 // Get currently selected item (me@someplace.com) to the result1 variable.
 singleSearch->Item(item);
 TPtrC16 result1(strSomeText.Mid(item.iStartPos, item.iLength));

 // Deallocate memory
 delete singleSearch;

 // Create an instance of CTulAddressStringTokenizer and look for all possible 
 // things (cases work as binary mask).
 CTulAddressStringTokenizer* multiSearch = CTulAddressStringTokenizer::NewL(strSomeText,
                  (CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin |           
                  CTulAddressStringTokenizer::EFindItemSearchURLBin | 
                  CTulAddressStringTokenizer::EFindItemSearchMailAddressBin | 
                  CTulAddressStringTokenizer::EFindItemSearchScheme));

 // Get count of found items.
 TInt count2(multiSearch->ItemCount());

 // Get currently selected item to the result2 variable.
 multiSearch->Item(item);

 // Debug print all items and their type.
 for( TInt i=0; i<count2; i++)
     {
     TPtrC16 result2(strSomeText.Mid(item.iStartPos, item.iLength));
     RDebug::Print(_L("Found type %d item:"), item.iItemType);
     RDebug::Print(_L("%S"), &result2);
     multiSearch->NextItem(item);
     }

 // Deallocate memory
 delete multiSearch;

Inherits from

CTulAddressStringTokenizer
- CBase

Nested Classes and Structures

CTulAddressStringTokenizer::SFoundItem

Public Member Functions
	~CTulAddressStringTokenizer()
IMPORT_C TInt	DoNewSearchL(const TDesC &, TInt)
IMPORT_C TInt	DoNewSearchL(const TDesC &, TInt, TInt)
IMPORT_C TBool	Item(SFoundItem &)
IMPORT_C const CArrayFixFlat< SFoundItem > *	ItemArray()
IMPORT_C TInt	ItemCount()
IMPORT_C CTulAddressStringTokenizer *	NewL(const TDesC &, TInt)
IMPORT_C CTulAddressStringTokenizer *	NewL(const TDesC &, TInt, TInt)
IMPORT_C TBool	NextItem(SFoundItem &)
IMPORT_C TInt	Position()
IMPORT_C TBool	PrevItem(SFoundItem &)
IMPORT_C void	ResetPosition()

Private Member Functions
	CTulAddressStringTokenizer()
	CTulAddressStringTokenizer(const CTulAddressStringTokenizer &)
void	AddItemL(TInt, TInt, TTokenizerSearchCase)
void	ConstructL(const TDesC &, TInt, TInt)
TBool	IsValidEmailChar(const TChar &)
TBool	IsValidEmailHostChar(const TChar &)
TBool	IsValidPhoneNumberChar(const TChar &)
TBool	IsValidUrlChar(const TChar &)
TBool	ParseUrlL(const TDesC &, const TPtrC &, TInt)
void	PerformSearchL(const TDesC &, TInt)
TBool	SearchGenericUriL(const TDesC &)
TBool	SearchMailAddressL(const TDesC &)
TBool	SearchPhoneNumberL(const TDesC &)
TBool	SearchUrlL(const TDesC &, TBool)
CTulAddressStringTokenizer &	operator=(const CTulAddressStringTokenizer &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	TTokenizerSearchCase { EFindItemSearchPhoneNumberBin = 4, EFindItemSearchMailAddressBin = 8, EFindItemSearchURLBin = 16, EFindItemSearchScheme = 32 }

Private Attributes
CArrayFixFlat< SFoundItem > *	iFoundItems
TInt	iMinNumbers
TInt	iPosition

Constructor & Destructor Documentation

CTulAddressStringTokenizer()

CTulAddressStringTokenizer

(

)

[private]

C++ default constructor.

CTulAddressStringTokenizer(const CTulAddressStringTokenizer &)

CTulAddressStringTokenizer

(

const CTulAddressStringTokenizer &

)

[private]

Parameters

const CTulAddressStringTokenizer &

~CTulAddressStringTokenizer()

IMPORT_C

~CTulAddressStringTokenizer

(

)

Destructor.

Member Functions Documentation

AddItemL(TInt, TInt, TTokenizerSearchCase)

void	AddItemL	(	TInt	aStartPos,
			TInt	aLength,
			TTokenizerSearchCase	aType
		)	[private]

Adds item to search arrays. Adding is done so that arrays are always sorted. If added element would overlap a previously found element, it is not added.

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

Parameters

TInt aStartPos	Start position of the found item
TInt aLength	Length of found item
TTokenizerSearchCase aType	Type of the found item

ConstructL(const TDesC &, TInt, TInt)

void	ConstructL	(	const TDesC &	aText,
			TInt	aSearchCases,
			TInt	aMinNumbers
		)	[private]

Symbian OS constructor

Parameters

const TDesC & aText	Text that will be parsed
TInt aSearchCases	Identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
TInt aMinNumbers	Minimum count of numbers in a string when the string is considered as a phone number.

DoNewSearchL(const TDesC &, TInt)

IMPORT_C TInt	DoNewSearchL	(	const TDesC &	aText,
			TInt	aSearchCases
		)

Executes a new search with the already created CTulAddressStringTokenizer instance. The position in the found items array is reset to the beginning of the array.

panic: ETulPanicInvalidTokenizerSearchCase in debug build if there is no valid search case.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

leave: one of the Symbian error codes.

Parameters

const TDesC & aText	will be parsed.
TInt aSearchCases	identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.

DoNewSearchL(const TDesC &, TInt, TInt)

IMPORT_C TInt	DoNewSearchL	(	const TDesC &	aText,
			TInt	aSearchCases,
			TInt	aMinNumbers
		)

Executes a new search with the already created CTulAddressStringTokenizer instance. The position in the found items array is reset to the beginning of the array.

panic: ETulPanicInvalidTokenizerSearchCase in debug build if there is no valid search case.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

Parameters

const TDesC & aText	will be parsed.
TInt aSearchCases	identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
TInt aMinNumbers	defines a minimum count of numbers in a phone number string, during a phone number search.

IsValidEmailChar(const TChar &)

TBool

IsValidEmailChar

(

const TChar &

charac

)

[private, static]

Character information methods

Parameters

const TChar & charac

a Character to be investigated

IsValidEmailHostChar(const TChar &)

TBool

IsValidEmailHostChar

(

const TChar &

charac

)

[private, static]

Character information methods

Parameters

const TChar & charac

a Character to be investigated

IsValidPhoneNumberChar(const TChar &)

TBool

IsValidPhoneNumberChar

(

const TChar &

charac

)

[private, static]

Character information methods

Parameters

const TChar & charac

a Character to be investigated

IsValidUrlChar(const TChar &)

TBool

IsValidUrlChar

(

const TChar &

charac

)

[private, static]

Character information methods

Parameters

const TChar & charac

a Character to be investigated

Item(SFoundItem &)

IMPORT_C TBool

Item

(

SFoundItem &

aItem

)

const

Gets the currently 'selected' item in the array of found items.

Parameters

SFoundItem & aItem

contains the currently selected item after returning.

ItemArray()

IMPORT_C const CArrayFixFlat< SFoundItem > *

ItemArray

(

)

const

Gets the array of found items. Returns a constant pointer to the found items array of the CTulAddressStringTokenizer instance. The items cannot be modified through this pointer, only accessed. The ownership of the array stays with CTulAddressStringTokenizer.

ItemCount()

IMPORT_C TInt

ItemCount

(

)

const

Gets the number of items in the found items array.

NewL(const TDesC &, TInt)

IMPORT_C CTulAddressStringTokenizer *	NewL	(	const TDesC &	aText,
			TInt	aSearchCases
		)	[static]

Two-phase constructor method that is used to create a new instance of the CTulAddressStringTokenizer class. This instance can then be queried for the items defined by the second parameter. The actual search is executed during construction.

panic: ETulPanicInvalidTokenizerSearchCase in debug build if there is no valid search case.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

Parameters

const TDesC & aText	will be parsed.
TInt aSearchCases	identifies what items we are looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.

NewL(const TDesC &, TInt, TInt)

IMPORT_C CTulAddressStringTokenizer *	NewL	(	const TDesC &	aText,
			TInt	aSearchCases,
			TInt	aMinNumbers
		)	[static]

panic: ETulPanicInvalidTokenizerSearchCase in debug build if there is no valid search case.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

Parameters

const TDesC & aText	will be parsed.
TInt aSearchCases	identifies what items we are looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
TInt aMinNumbers	defines a minimum count of numbers in a phone number string, during a phone number search.

NextItem(SFoundItem &)

IMPORT_C TBool

NextItem

(

SFoundItem &

aItem

)

Gets the next found item relative to the currently selected item. Moves the selection to point to the next item in the array of found items.

Parameters

SFoundItem & aItem

contains the next item after returning.

ParseUrlL(const TDesC &, const TPtrC &, TInt)

TBool	ParseUrlL	(	const TDesC &	aType,
			const TPtrC &	aTokenPtr,
			TInt	aTextOffset
		)	[private]

Parses URL from a token. Is used by SearchUrlL method and if a URL was found it's appended to item array. Note that parsing for generic URIs is done with SearchGenericUriL -method.

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

Parameters

const TDesC & aType	a Type of URL to seach, i.e. www. wap. IP e.g.127.0.0.1
const TPtrC & aTokenPtr	Pointer to token that will be parsed
TInt aTextOffset	Offset of the token (start position in the whole text)

PerformSearchL(const TDesC &, TInt)

void	PerformSearchL	(	const TDesC &	aText,
			TInt	aSearchCases
		)	[private]

Performs the search. Uses search algorithms SearchGenericUriL(), SearchMailAddressL(), SearchUrlL() and SearchPhoneNumberL().

Parameters

const TDesC & aText
TInt aSearchCases

Position()

IMPORT_C TInt

Position

(

)

const

Gets the current position (or the position of the currently selected item) in the found items array.

PrevItem(SFoundItem &)

IMPORT_C TBool

PrevItem

(

SFoundItem &

aItem

)

Gets the previous found item relative to the currently selected item. Moves the selection to point to the previous item in the array of found items..

Parameters

SFoundItem & aItem

contains the previous item after returning.

ResetPosition()

IMPORT_C void

ResetPosition

(

)

Resets the position in item array to zero (beginning of the array).

SearchGenericUriL(const TDesC &)

TBool

SearchGenericUriL

(

const TDesC &

aText

)

[private]

Search algorithm for searching generic URIs

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

Parameters

const TDesC & aText

Text that will be parsed

SearchMailAddressL(const TDesC &)

TBool

SearchMailAddressL

(

const TDesC &

aText

)

[private]

Search algorithm for searching e-mail addresses

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

Parameters

const TDesC & aText

Text that will be parsed

SearchPhoneNumberL(const TDesC &)

TBool

SearchPhoneNumberL

(

const TDesC &

aText

)

[private]

Search algorithm for searching phone numbers

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

Parameters

const TDesC & aText

Text that will be parsed

SearchUrlL(const TDesC &, TBool)

TBool	SearchUrlL	(	const TDesC &	aText,
			TBool	aFindFixedSchemas
		)	[private]

Search fixed start URLs, i.e. URLs without schema (www., wap.). Also finds IPv4 addresses (*.*.*.*). As a special case, supports deprecated hardcoded schematic addresses finding (http://, https://, rtsp://) to make sure deprecated search cases work as they did previously.

leave: KErrNone, if successful; otherwise one of the other system-wide error codes.

panic: ETulPanicDescriptorLength in debug build if item's position and/or length is out of the document's range.

Parameters

const TDesC & aText	Text that will be parsed
TBool aFindFixedSchemas	If true, will find old fixed schematic URLs also

operator=(const CTulAddressStringTokenizer &)

CTulAddressStringTokenizer &

operator=

(

const CTulAddressStringTokenizer &

)

[private]

Parameters

const CTulAddressStringTokenizer &

Member Enumerations Documentation

Enum TTokenizerSearchCase

Enumeration to define the search case. Multiple enumerations can be used as binary mask.

Enumerators

EFindItemSearchPhoneNumberBin = 4
EFindItemSearchMailAddressBin = 8
EFindItemSearchURLBin = 16
EFindItemSearchScheme = 32

Member Data Documentation

CArrayFixFlat< SFoundItem > * iFoundItems

CArrayFixFlat< SFoundItem > *

iFoundItems

[private]

TInt iMinNumbers

TInt

iMinNumbers

[private]

TInt iPosition

TInt

iPosition

[private]