1 finditemengine.h

     1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Find Item API offers methods for parsing phone numbers, email 

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

    16 *

    17 */

    18 

    19 

    20 #ifndef FINDITEMENGINE_H

    21 #define FINDITEMENGINE_H

    22 

    23 //  INCLUDES

    24 #include <e32base.h>

    25 

    26 // CLASS DECLARATION

    27 

    28 /**

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

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

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

    32 * CFindItemEngine class.

    33 *

    34 * Usage:

    35 * 

    36 * @code

    37 *  #include <finditemengine.h>

    38 *

    39 *  // SFoundItem instance

    40 *  CFindItemEngine::SFoundItem item;

    41 *

    42 *  // Some text

    43 *  TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567. 

    44 *  You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra."));

    45 *	

    46 *  // First the user has to create an instance of CFindItemEngine by using the

    47 *  // factory method NewL(). The method takes two parameters. The first 

    48 *  // parameter defines the text to be searched from and the second parameter 

    49 *  // tells what exactly is being looked for.

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

    51 *                   CFindItemEngine::EFindItemSearchMailAddressBin);

    52 *

    53 *  // The passed text is parsed in construction, and found items can be fetched 

    54 *  // by using the ItemArray() method. It returns a constant array containing 

    55 *  // all the found items. The interface offers also helper functions for 

    56 *  // handling the item array by itself. 

    57 *

    58 *  // Get count of found items.

    59 *  TInt count(singleSearch->ItemCount());

    60 *

    61 *  // Get currently selected item (me@someplace.com) to the result1 variable.

    62 *  singleSearch->Item(item);

    63 *  TPtrC16 result1(strSomeText.Mid(item.iStartPos, item.iLength));

    64 *

    65 *  // Deallocate memory

    66 *  delete singleSearch;

    67 *

    68 *  // Create an instance of FindItemEngine and look for all possible 

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

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

    71 *                   (CFindItemEngine::TFindItemSearchCase)

    72 *                   (CFindItemEngine::EFindItemSearchPhoneNumberBin |           

    73 *                   CFindItemEngine::EFindItemSearchURLBin | 

    74 *                   CFindItemEngine::EFindItemSearchMailAddressBin | 

    75 *                   CFindItemEngine::EFindItemSearchScheme));

    76 *

    77 *  // Get count of found items.

    78 *  TInt count2(multiSearch->ItemCount());

    79 *

    80 *  // Get currently selected item to the result2 variable.

    81 *  multiSearch->Item(item);

    82 *

    83 *  // Debug print all items and their type.

    84 *  for( TInt i=0; i<count2; i++)

    85 *      {

    86 *      TPtrC16 result2(strSomeText.Mid(item.iStartPos, item.iLength));

    87 *      RDebug::Print(_L("Found type %d item:"), item.iItemType);

    88 *      RDebug::Print(_L("%S"), &result2);

    89 *      multiSearch->NextItem(item);

    90 *      }

    91 *

    92 *  // Deallocate memory

    93 *  delete multiSearch;

    94 * @endcode

    95 *

    96 * @lib commonengine.lib

    97 * @since S60 2.0

    98 */

    99 

   100 class CFindItemEngine :public CBase

   101     {

   102     public:

   103 

   104         /**

   105         * Enumeration to define the search case. 

   106         * Multiple enumerations can be used as binary mask.

   107         */

   108         enum TFindItemSearchCase

   109             {

   110             /** Searches phone numbers.

   111             */

   112 			EFindItemSearchPhoneNumberBin = 4, 

   113             /** Searches mail addresses.

   114             */

   115             EFindItemSearchMailAddressBin = 8,

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

   117             */

   118             EFindItemSearchURLBin  = 16,

   119             /** Searches for all URIs containing a scheme.

   120             */

   121             EFindItemSearchScheme  = 32

   122             };

   123 

   124         /** 

   125         * Struct to contain an item.

   126         */

   127         struct SFoundItem

   128             {

   129             /**Start position of the found item.

   130             */

   131             TInt iStartPos;

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

   133             */

   134             TInt iLength;

   135 			/** Search case of the found item

   136 			*/

   137             TFindItemSearchCase iItemType;

   138 			};

   139 

   140     public:  // Constructors and destructor

   141         

   142         /**

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

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

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

   146         * executed during construction.

   147         *

   148         * @param aText will be parsed.

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

   150         * EFindItemSearchPhoneNumberBin

   151         * EFindItemSearchMailAddressBin

   152         * EFindItemSearchURLBin

   153         * EFindItemSearchScheme

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

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

   156         *

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

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

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

   160         * @leave one of the Symbian error codes.

   161         */

   162         IMPORT_C static CFindItemEngine* NewL( const TDesC& aText, 

   163                                                const TFindItemSearchCase aSearchCase );

   164 

   165         /**

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

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

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

   169         * executed during construction.

   170         *

   171         * @param aText will be parsed.

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

   173         * EFindItemSearchPhoneNumberBin

   174         * EFindItemSearchMailAddressBin

   175         * EFindItemSearchURLBin

   176         * EFindItemSearchScheme

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

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

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

   180         * searched.

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

   182         *

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

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

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

   186         * @leave one of the Symbian error codes.

   187         */

   188         IMPORT_C static CFindItemEngine* NewL( const TDesC& aText, 

   189                                                const TFindItemSearchCase aSearchCase,

   190                                                const TInt aMinNumbers );

   191 

   192         /**

   193         * Destructor.

   194         */

   195         IMPORT_C virtual ~CFindItemEngine();

   196 

   197     public:

   198         /**

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

   200         *

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

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

   203         */

   204         IMPORT_C TBool Item( SFoundItem& aItem );

   205 

   206         /**

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

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

   209         * found items. 

   210         *

   211         * @param aItem contains the next item after returning.

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

   213         */

   214         IMPORT_C TBool NextItem( SFoundItem& aItem );

   215 

   216         /**

   217         * Gets the previous found item relative to the currently selected 

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

   219         * array of found items.. 

   220         *

   221         * @param aItem contains the previous item after returning.

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

   223         */

   224         IMPORT_C TBool PrevItem( SFoundItem& aItem );

   225 		

   226         /**

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

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

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

   230         * the array stays with CFindItemEngine.

   231         *

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

   233         * stays with CFindItemEngine.

   234         */

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

   236 

   237         /**

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

   239         * in the found items array.

   240         *

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

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

   243         * returned.

   244         */

   245 		IMPORT_C TInt Position() const;	

   246 	

   247         /**

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

   249         */

   250         IMPORT_C void ResetPosition();

   251 

   252         /**

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

   254         *

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

   256         */

   257 		IMPORT_C TInt ItemCount() const;

   258 		

   259         /**

   260         * Executes a new search with the already created CFindItemEngine 

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

   262         * beginning of the array.

   263         *

   264         * @param aText will be parsed.

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

   266         * EFindItemSearchPhoneNumberBin

   267         * EFindItemSearchMailAddressBin

   268         * EFindItemSearchURLBin

   269         * EFindItemSearchScheme

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

   271         * @return number of found items.

   272         *

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

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

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

   276         * @leave one of the Symbian error codes.

   277         */

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

   279 

   280         /**

   281         * Executes a new search with the already created CFindItemEngine 

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

   283         * beginning of the array.

   284         *

   285         * @param aText will be parsed.

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

   287         * EFindItemSearchPhoneNumberBin

   288         * EFindItemSearchMailAddressBin

   289         * EFindItemSearchURLBin

   290         * EFindItemSearchScheme

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

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

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

   294         * searched.

   295         * @return number of found items.

   296         *

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

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

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

   300         * @leave one of the Symbian error codes.

   301         */

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

   303                                     const TInt aMinNumbers );

   304 

   305     private:

   306         

   307         /**

   308         * Adds item to search arrays. Adding is done so that arrays are always sorted.

   309         * If added element would overlap a previously found element, it is not added.

   310         *

   311         * @param aStartPos  Start position of the found item

   312         * @param aLength    Length of found item

   313         * @param aType      Type of the found item

   314         */

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

   316                        const TFindItemSearchCase& aType );

   317 

   318         /**

   319         * Search algorithm for searching phone numbers

   320         *

   321         * @param aText Text that will be parsed

   322         * @return Whether any items were found

   323         */

   324         TBool SearchPhoneNumberL( const TDesC& aText);  

   325 

   326         /**

   327         * Search algorithm for searching e-mail addresses

   328         *

   329         * @param aText Text that will be parsed

   330         * @return Whether any items were found

   331         */

   332         TBool SearchMailAddressL( const TDesC& aText);  

   333 

   334         /**

   335         * Search algorithm for searching generic URIs

   336         *

   337         * @param aText Text that will be parsed

   338         * @return Whether any items were found

   339         */

   340         TBool SearchGenericUriL( const TDesC& aText);

   341 

   342         /**

   343         * Search fixed start URLs, i.e. URLs without schema (www., wap.).

   344         * Also finds IPv4 addresses (*.*.*.*).

   345         * As a special case, supports deprecated hardcoded schematic addresses finding 

   346         * (http://, https://, rtsp://) to make sure deprecated search cases work 

   347         * as they did previously.

   348         *

   349         * @param aText Text that will be parsed

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

   351         * @return Whether any items were found

   352         */

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

   354 

   355         /**

   356         * Parses URL from a token. Is used by SearchUrlL method and if a URL

   357         * was found it's appended to item array. Note that parsing for generic URIs 

   358         * is done with SearchGenericUriL -method.

   359         *

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

   361         *                   www.

   362         *                   wap.

   363         *                   IP e.g.127.0.0.1

   364         * @param        aTokenPtr Pointer to token that will be parsed

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

   366         * @return Whether any items were found

   367         */

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

   369 

   370         /**

   371         * Character information methods

   372         *

   373         * @param charac a Character to be investigated

   374         * @return Whether the parameter was a valid for:

   375         */

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

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

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

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

   380 

   381         /**

   382         * C++ default constructor.

   383         */

   384         CFindItemEngine();

   385 

   386         /**

   387         * Symbian OS constructor

   388         *

   389         * @param aText          Text that will be parsed

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

   391         *                           EFindItemSearchPhoneNumberBin

   392         *                           EFindItemSearchMailAddressBin

   393         *                           EFindItemSearchURLBin

   394         *                           EFindItemSearchScheme

   395         *                       Any combination of these flags can be given

   396         *                       as a bit mask.

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

   398         *                       the string is considered as a phone number.

   399         */

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

   401                          const TInt aMinNumbers );

   402         /**

   403         * Performs the search.

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

   405         * SearchUrlL() and SearchPhoneNumberL().

   406         *

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

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

   409         */

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

   411 

   412 

   413         /**

   414         * Converts arabic numbers to western numbers. 

   415         * When returning the aBuf contains the modified text.

   416         *

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

   418         */

   419 		void ConvertArabicNumbersToWesternNumbers( HBufC* aBuf );

   420 

   421         /**

   422         * By default, prohibit copy constructor

   423         */

   424         CFindItemEngine( const CFindItemEngine& );

   425         /**

   426         * Prohibit assigment operator

   427         */

   428         CFindItemEngine& operator= ( const CFindItemEngine& );

   429 

   430     private:    // Data

   431         // Array of all found items.

   432         CArrayFixFlat<SFoundItem>* iItemArray;

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

   434         TInt iPosition;

   435         // Minimum count of numbers in a phone number

   436         TInt iMinNumbers;

   437     };

   438 

   439 #endif      // FINDITEMENGINE_H   

   440             

   441 // End of File