/*

* Copyright (c) 2002-2006 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:  Find Item API offers methods for parsing phone numbers, email 

*                addresses, URL addresses and URI addresses from given text.

*

*/

#ifndef FINDITEMENGINE_H

#define FINDITEMENGINE_H

//  INCLUDES

#include <e32base.h>

// CLASS DECLARATION

/**

* Class is used to parse phone numbers and email, URL and URI addresses from 

* given text. Find Item API offers methods for parsing phone numbers and 

* e-mail, URL and URI addresses from the given text. The API consist of the 

* CFindItemEngine class.

*

* Usage:

* 

* @code

*  #include <finditemengine.h>

*

*  // SFoundItem instance

*  CFindItemEngine::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 CFindItemEngine 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.

*  CFindItemEngine* singleSearch = CFindItemEngine::NewL(strSomeText, 

*                   CFindItemEngine::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 offers also 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 FindItemEngine and look for all possible 

*  // things (cases work as binary mask).

*  CFindItemEngine* multiSearch = CFindItemEngine::NewL(strSomeText,

*                   (CFindItemEngine::TFindItemSearchCase)

*                   (CFindItemEngine::EFindItemSearchPhoneNumberBin |           

*                   CFindItemEngine::EFindItemSearchURLBin | 

*                   CFindItemEngine::EFindItemSearchMailAddressBin | 

*                   CFindItemEngine::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

*

* @lib commonengine.lib

* @since S60 2.0

*/

class CFindItemEngine :public CBase

    {

    public:

        /**

        * Enumeration to define the search case. 

        * Multiple enumerations can be used as binary mask.

        */

        enum TFindItemSearchCase

            {

            /** 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 an item.

        */

        struct SFoundItem

            {

            /**Start position of the found item.

            */

            TInt iStartPos;

            /** Length of the found item (characters).

            */

            TInt iLength;

			/** Search case of the found item

			*/

            TFindItemSearchCase iItemType;

			};

    public:  // Constructors and destructor

        /**

        * Two-phase constructor method that is used to create a new instance

        * of the CFindItemEngine class. This instance can then be queried for

        * the items defined by the second parameter. The actual search is 

        * executed during construction.

        *

        * @param aText will be parsed.

        * @param aSearchCase identifies what items are we looking for: 

        * EFindItemSearchPhoneNumberBin

        * EFindItemSearchMailAddressBin

        * EFindItemSearchURLBin

        * EFindItemSearchScheme

        * Any combination of these flags can be given as a bit mask.

        * @return a pointer to an new instance of CFindItemEngine class.

        *

        * @panic ENoSearchCase in debug build if there is no valid search case.

        * @panic EItemOutOfDocumentRange in debug build if item's position 

        * and/or length is out of the document's range.

        * @leave one of the Symbian error codes.

        */

        IMPORT_C static CFindItemEngine* NewL( const TDesC& aText, 

                                               const TFindItemSearchCase aSearchCase );

        /**

        * Two-phase constructor method that is used to create a new instance

        * of the CFindItemEngine class. This instance can then be queried for

        * the items defined by the second parameter. The actual search is 

        * executed during construction.

        *

        * @param aText will be parsed.

        * @param aSearchCase identifies what items are we looking for: 

        * EFindItemSearchPhoneNumberBin

        * EFindItemSearchMailAddressBin

        * EFindItemSearchURLBin

        * EFindItemSearchScheme

        * Any combination of these flags can be given as a bit mask.

        * @param aMinNumbers defines minimun count of numbers in a string that 

        * the string is considered as a phone number when phone numbers are 

        * searched.

        * @return a pointer to an new instance of CFindItemEngine class.

        *

        * @panic ENoSearchCase in debug build if there is no valid search case.

        * @panic EItemOutOfDocumentRange in debug build if item's position 

        * and/or length is out of the document's range.

        * @leave one of the Symbian error codes.

        */

        IMPORT_C static CFindItemEngine* NewL( const TDesC& aText, 

                                               const TFindItemSearchCase aSearchCase,

                                               const TInt aMinNumbers );

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CFindItemEngine();

    public:

        /**

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

        *

        * @param aItem contains the currently selected item after returning.

        * @return ETrue if the item was found. EFalse if the item wasn't found.

        */

        IMPORT_C TBool Item( SFoundItem& aItem );

        /**

        * Gets the next found item relative to the currently selected item 

        * and moves the selection to point to the next item in the array of 

        * found items. 

        *

        * @param aItem contains the next item after returning.

        * @return ETrue if the item was found. EFalse if there's no next item.

        */

        IMPORT_C TBool NextItem( SFoundItem& aItem );

        /**

        * Gets the previous found item relative to the currently selected 

        * item and moves the selection to point to the previous item in the 

        * array of found items.. 

        *

        * @param aItem contains the previous item after returning.

        * @return ETrue if the item was found. EFalse if there's no previous item.

        */

        IMPORT_C TBool PrevItem( SFoundItem& aItem );

        /**

        * Gets the array of found items. Returns a constant pointer to the 

        * found items array of the CFindItemEngine instance. The items cannot

        * be modified through this pointer, only accessed. The ownership of 

        * the array stays with CFindItemEngine.

        *

        * @return a constant pointer to the array of found items. Ownership 

        * stays with CFindItemEngine.

        */

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

        /**

        * Gets the current position (or the position of the currently selected item) 

        * in the found items array.

        *

        * @return the current position in the found items array of the 

        * CFindItemEngine instance. If no items are in the array, zero is 

        * returned.

        */

		IMPORT_C TInt Position() const;	

        /**

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

        */

        IMPORT_C void ResetPosition();

        /**

        * Gets the number of items in the found items array.

        *

        * @return the number of items in the found items array. 

        */

		IMPORT_C TInt ItemCount() const;

        /**

        * Executes a new search with the already created CFindItemEngine 

        * instance. The position in the found items array is reset to the 

        * beginning of the array.

        *

        * @param aText will be parsed.

        * @param aSearchCase identifies what items are we looking for: 

        * EFindItemSearchPhoneNumberBin

        * EFindItemSearchMailAddressBin

        * EFindItemSearchURLBin

        * EFindItemSearchScheme

        * Any combination of these flags can be given as a bit mask.

        * @return number of found items.

        *

        * @panic ENoSearchCase in debug build if there is no valid search case.

        * @panic EItemOutOfDocumentRange in debug build if item's position 

        * and/or length is out of the document's range.

        * @leave one of the Symbian error codes.

        */

        IMPORT_C TInt DoNewSearchL( const TDesC& aText, const TFindItemSearchCase aSearchCase);

        /**

        * Executes a new search with the already created CFindItemEngine 

        * instance. The position in the found items array is reset to the 

        * beginning of the array.

        *

        * @param aText will be parsed.

        * @param aSearchCase identifies what items are we looking for: 

        * EFindItemSearchPhoneNumberBin

        * EFindItemSearchMailAddressBin

        * EFindItemSearchURLBin

        * EFindItemSearchScheme

        * Any combination of these flags can be given as a bit mask.

        * @param aMinNumbers defines minimun count of numbers in a string that 

        * the string is considered as a phone number when phone numbers are 

        * searched.

        * @return number of found items.

        *

        * @panic ENoSearchCase in debug build if there is no valid search case.

        * @panic EItemOutOfDocumentRange in debug build if item's position 

        * and/or length is out of the document's range.

        * @leave one of the Symbian error codes.

        */

        IMPORT_C TInt DoNewSearchL( const TDesC& aText, const TFindItemSearchCase aSearchCase, 

                                    const TInt aMinNumbers );

    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.

        *

        * @param aStartPos  Start position of the found item

        * @param aLength    Length of found item

        * @param aType      Type of the found item

        */

        void AddItemL( const TInt& aStartPos, const TInt& aLength, 

                       const TFindItemSearchCase& aType );

        /**

        * Search algorithm for searching phone numbers

        *

        * @param aText Text that will be parsed

        * @return Whether any items were found

        */

        TBool SearchPhoneNumberL( const TDesC& aText);  

        /**

        * Search algorithm for searching e-mail addresses

        *

        * @param aText Text that will be parsed

        * @return Whether any items were found

        */

        TBool SearchMailAddressL( const TDesC& aText);  

        /**

        * Search algorithm for searching generic URIs

        *

        * @param aText Text that will be parsed

        * @return Whether any items were found

        */

        TBool SearchGenericUriL( const TDesC& aText);

        /**

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

        *

        * @param aText Text that will be parsed

        * @param aFindFixedSchemas If true, will find old fixed schematic URLs also

        * @return Whether any items were found

        */

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

        /**

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

        *

        * @param aType  a Type of URL to seach, i.e.

        *                   www.

        *                   wap.

        *                   IP e.g.127.0.0.1

        * @param        aTokenPtr Pointer to token that will be parsed

        * @param        aTextOffset Offset of the token (start position in the whole text)

        * @return Whether any items were found

        */

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

        /**

        * Character information methods

        *

        * @param charac a Character to be investigated

        * @return Whether the parameter was a valid for:

        */

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

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

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

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

        /**

        * C++ default constructor.

        */

        CFindItemEngine();

        /**

        * Symbian OS constructor

        *

        * @param aText          Text that will be parsed

        * @param aSearchCase    Identifies what items are we looking for:

        *                           EFindItemSearchPhoneNumberBin

        *                           EFindItemSearchMailAddressBin

        *                           EFindItemSearchURLBin

        *                           EFindItemSearchScheme

        *                       Any combination of these flags can be given

        *                       as a bit mask.

        * @param aMinNumbers    Minimun count of numbers in a string when 

        *                       the string is considered as a phone number.

        */

        void ConstructL( const TDesC& aText, const TFindItemSearchCase aSearchCase, 

                         const TInt aMinNumbers );

        /**

        * Performs the search.

        * Uses search algorithms SearchGenericUriL(), SearchMailAddressL(), 

        * SearchUrlL() and SearchPhoneNumberL().

        *

        * @param aText Reference to the text to be parsed.

        * @param aSearchCase identifies what items are we looking for.

        */

		void PerformSearchL( const TDesC& aText , const TFindItemSearchCase aSearchCase );

        /**

        * Converts arabic numbers to western numbers. 

        * When returning the aBuf contains the modified text.

        *

        * @param aBuf A pointer to the buffer containing the text.

        */

		void ConvertArabicNumbersToWesternNumbers( HBufC* aBuf );

        /**

        * By default, prohibit copy constructor

        */

        CFindItemEngine( const CFindItemEngine& );

        /**

        * Prohibit assigment operator

        */

        CFindItemEngine& operator= ( const CFindItemEngine& );

    private:    // Data

        // Array of all found items.

        CArrayFixFlat<SFoundItem>* iItemArray;

		// Engine's position in the iItemArray and iItemTypeArray.

        TInt iPosition;

        // Minimum count of numbers in a phone number

        TInt iMinNumbers;

    };

#endif      // FINDITEMENGINE_H   

// End of File