/*

* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

#ifndef __TULADDRESSSTRINGTOKENIZER_H__

#define __TULADDRESSSTRINGTOKENIZER_H__

#include <e32base.h>

/**

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:

@code

 #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;

@endcode

@publishedAll

@released

*/

class CTulAddressStringTokenizer : public CBase

    {

public:

#define TFindItemSearchCase TTokenizerSearchCase	// For source compatibility with S60 only

    /**

    Enumeration to define the search case. 

    Multiple enumerations can be used as binary mask.

    */

    enum TTokenizerSearchCase

        {

        // Searches phone numbers.

		EFindItemSearchPhoneNumberBin = 4, 

        // Searches mail addresses.

        EFindItemSearchMailAddressBin = 8,

        // Searches fixed start URLs ("http://", "https://", "rtsp://"), "www.", "wap." and IPv4 addresses.

        EFindItemSearchURLBin  = 16,

        // Searches for all URIs containing a scheme.

        EFindItemSearchScheme  = 32

        };

    // Struct to contain a found item.

    struct SFoundItem

        {

        TInt iStartPos;	// Start position of the found item.

        TInt iLength;	// Length of the found item (characters).

        TTokenizerSearchCase iItemType;		// Search case of the found item

		};

public:  // Constructors and destructor

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

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

    IMPORT_C ~CTulAddressStringTokenizer();

public:

	IMPORT_C TInt ItemCount() const;

    IMPORT_C TBool Item( SFoundItem& aItem ) const;

    IMPORT_C TBool NextItem( SFoundItem& aItem );

    IMPORT_C TBool PrevItem( SFoundItem& aItem );

    IMPORT_C const CArrayFixFlat<SFoundItem>* ItemArray() const;

	IMPORT_C TInt Position() const;	

    IMPORT_C void ResetPosition();

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

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

private:

    CTulAddressStringTokenizer();

    void AddItemL( TInt aStartPos, TInt aLength, TTokenizerSearchCase aType );

    TBool SearchPhoneNumberL( const TDesC& aText );

    TBool SearchMailAddressL( const TDesC& aText );  

    TBool SearchGenericUriL( const TDesC& aText );

    TBool SearchUrlL( const TDesC& aText, TBool aFindFixedSchemas );

    TBool ParseUrlL( const TDesC& aType, const TPtrC& aTokenPtr, TInt aTextOffset );

    static TBool IsValidEmailChar(const TChar& charac); // Login part of the e-mail address

    static TBool IsValidEmailHostChar(const TChar& charac); // Host part of the e-mail address

    static TBool IsValidPhoneNumberChar(const TChar& charac); // Phone number

    static TBool IsValidUrlChar( const TChar& charac); // URL

    void ConstructL( const TDesC& aText, TInt aSearchCases, TInt aMinNumbers );

	void PerformSearchL( const TDesC& aText, TInt aSearchCases );

    CTulAddressStringTokenizer( const CTulAddressStringTokenizer& );	// Prohibit copy constructor

    CTulAddressStringTokenizer& operator= ( const CTulAddressStringTokenizer& );  // Prohibit assigment operator

private:

    CArrayFixFlat<SFoundItem>* iFoundItems;		// Array of all found items.

    TInt iPosition;		// Engine's position in the iFoundItems.

    TInt iMinNumbers;	// Minimum count of numbers in a phone number

    };

#endif      // __TULADDRESSSTRINGTOKENIZER_H__