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