--- 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 <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
- };
+#include <tuladdressstringtokenizer.h>
- /**
- * 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<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;
+ 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<CFindItemEngine::SFoundItem>* 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