diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/finditemengine.h --- a/epoc32/include/finditemengine.h Wed Mar 31 12:27:01 2010 +0100 +++ b/epoc32/include/finditemengine.h Wed Mar 31 12:33:34 2010 +0100 @@ -1,439 +1,66 @@ /* -* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). +* 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 +* under the terms of "Eclipse Public License v1.0" * which accompanies this distribution, and is available -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* at the URL "http://www.eclipse.org/legal/epl-v10.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. +* Description: * */ + #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 - }; +#include - /** - * 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 ); +class CFindItemEngine : public CBase +/** +@deprecated +@see CTulAddressStringTokenizer +@note For compatibility with S60 only +*/ + { +public: + enum TFindItemSearchCase + { + EFindItemSearchPhoneNumberBin = CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin, + EFindItemSearchMailAddressBin = CTulAddressStringTokenizer::EFindItemSearchMailAddressBin, + EFindItemSearchURLBin = CTulAddressStringTokenizer::EFindItemSearchURLBin, + EFindItemSearchScheme = CTulAddressStringTokenizer::EFindItemSearchScheme + }; - /** - * 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 ); + // Struct to contain a found item. + struct SFoundItem + { + TInt iStartPos; + TInt iLength; + TFindItemSearchCase iItemType; + }; - /** - * 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; + IMPORT_C static CFindItemEngine* NewL( const TDesC& aText, CFindItemEngine::TFindItemSearchCase aSearchCase ); + IMPORT_C static CFindItemEngine* NewL( const TDesC& aText, CFindItemEngine::TFindItemSearchCase aSearchCase, TInt aMinNumbers ); + IMPORT_C ~CFindItemEngine(); + IMPORT_C TBool Item( CFindItemEngine::SFoundItem& aItem ); + IMPORT_C TBool NextItem( CFindItemEngine::SFoundItem& aItem ); + IMPORT_C TBool PrevItem( CFindItemEngine::SFoundItem& aItem ); + IMPORT_C const CArrayFixFlat* ItemArray() const; + IMPORT_C TInt Position() const; + IMPORT_C void ResetPosition(); + IMPORT_C TInt ItemCount() const; + IMPORT_C TInt DoNewSearchL( const TDesC& aText, CFindItemEngine::TFindItemSearchCase aSearchCase); + IMPORT_C TInt DoNewSearchL( const TDesC& aText, CFindItemEngine::TFindItemSearchCase aSearchCase, TInt aMinNumbers ); +private: + CFindItemEngine(); }; #endif // FINDITEMENGINE_H