diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/finditemengine.h --- a/epoc32/include/finditemengine.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/finditemengine.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,441 @@ -finditemengine.h +/* +* 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 + +// 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 +* +* // 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; iNextItem(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* 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* 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