1.1 --- a/epoc32/include/finditemengine.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/finditemengine.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,441 @@
1.4 -finditemengine.h
1.5 +/*
1.6 +* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Find Item API offers methods for parsing phone numbers, email
1.19 +* addresses, URL addresses and URI addresses from given text.
1.20 +*
1.21 +*/
1.22 +
1.23 +
1.24 +#ifndef FINDITEMENGINE_H
1.25 +#define FINDITEMENGINE_H
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32base.h>
1.29 +
1.30 +// CLASS DECLARATION
1.31 +
1.32 +/**
1.33 +* Class is used to parse phone numbers and email, URL and URI addresses from
1.34 +* given text. Find Item API offers methods for parsing phone numbers and
1.35 +* e-mail, URL and URI addresses from the given text. The API consist of the
1.36 +* CFindItemEngine class.
1.37 +*
1.38 +* Usage:
1.39 +*
1.40 +* @code
1.41 +* #include <finditemengine.h>
1.42 +*
1.43 +* // SFoundItem instance
1.44 +* CFindItemEngine::SFoundItem item;
1.45 +*
1.46 +* // Some text
1.47 +* TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567.
1.48 +* You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra."));
1.49 +*
1.50 +* // First the user has to create an instance of CFindItemEngine by using the
1.51 +* // factory method NewL(). The method takes two parameters. The first
1.52 +* // parameter defines the text to be searched from and the second parameter
1.53 +* // tells what exactly is being looked for.
1.54 +* CFindItemEngine* singleSearch = CFindItemEngine::NewL(strSomeText,
1.55 +* CFindItemEngine::EFindItemSearchMailAddressBin);
1.56 +*
1.57 +* // The passed text is parsed in construction, and found items can be fetched
1.58 +* // by using the ItemArray() method. It returns a constant array containing
1.59 +* // all the found items. The interface offers also helper functions for
1.60 +* // handling the item array by itself.
1.61 +*
1.62 +* // Get count of found items.
1.63 +* TInt count(singleSearch->ItemCount());
1.64 +*
1.65 +* // Get currently selected item (me@someplace.com) to the result1 variable.
1.66 +* singleSearch->Item(item);
1.67 +* TPtrC16 result1(strSomeText.Mid(item.iStartPos, item.iLength));
1.68 +*
1.69 +* // Deallocate memory
1.70 +* delete singleSearch;
1.71 +*
1.72 +* // Create an instance of FindItemEngine and look for all possible
1.73 +* // things (cases work as binary mask).
1.74 +* CFindItemEngine* multiSearch = CFindItemEngine::NewL(strSomeText,
1.75 +* (CFindItemEngine::TFindItemSearchCase)
1.76 +* (CFindItemEngine::EFindItemSearchPhoneNumberBin |
1.77 +* CFindItemEngine::EFindItemSearchURLBin |
1.78 +* CFindItemEngine::EFindItemSearchMailAddressBin |
1.79 +* CFindItemEngine::EFindItemSearchScheme));
1.80 +*
1.81 +* // Get count of found items.
1.82 +* TInt count2(multiSearch->ItemCount());
1.83 +*
1.84 +* // Get currently selected item to the result2 variable.
1.85 +* multiSearch->Item(item);
1.86 +*
1.87 +* // Debug print all items and their type.
1.88 +* for( TInt i=0; i<count2; i++)
1.89 +* {
1.90 +* TPtrC16 result2(strSomeText.Mid(item.iStartPos, item.iLength));
1.91 +* RDebug::Print(_L("Found type %d item:"), item.iItemType);
1.92 +* RDebug::Print(_L("%S"), &result2);
1.93 +* multiSearch->NextItem(item);
1.94 +* }
1.95 +*
1.96 +* // Deallocate memory
1.97 +* delete multiSearch;
1.98 +* @endcode
1.99 +*
1.100 +* @lib commonengine.lib
1.101 +* @since S60 2.0
1.102 +*/
1.103 +
1.104 +class CFindItemEngine :public CBase
1.105 + {
1.106 + public:
1.107 +
1.108 + /**
1.109 + * Enumeration to define the search case.
1.110 + * Multiple enumerations can be used as binary mask.
1.111 + */
1.112 + enum TFindItemSearchCase
1.113 + {
1.114 + /** Searches phone numbers.
1.115 + */
1.116 + EFindItemSearchPhoneNumberBin = 4,
1.117 + /** Searches mail addresses.
1.118 + */
1.119 + EFindItemSearchMailAddressBin = 8,
1.120 + /** Searches fixed start URLs ("http://", "https://", "rtsp://"), "www.", "wap." and IPv4 addresses.
1.121 + */
1.122 + EFindItemSearchURLBin = 16,
1.123 + /** Searches for all URIs containing a scheme.
1.124 + */
1.125 + EFindItemSearchScheme = 32
1.126 + };
1.127 +
1.128 + /**
1.129 + * Struct to contain an item.
1.130 + */
1.131 + struct SFoundItem
1.132 + {
1.133 + /**Start position of the found item.
1.134 + */
1.135 + TInt iStartPos;
1.136 + /** Length of the found item (characters).
1.137 + */
1.138 + TInt iLength;
1.139 + /** Search case of the found item
1.140 + */
1.141 + TFindItemSearchCase iItemType;
1.142 + };
1.143 +
1.144 + public: // Constructors and destructor
1.145 +
1.146 + /**
1.147 + * Two-phase constructor method that is used to create a new instance
1.148 + * of the CFindItemEngine class. This instance can then be queried for
1.149 + * the items defined by the second parameter. The actual search is
1.150 + * executed during construction.
1.151 + *
1.152 + * @param aText will be parsed.
1.153 + * @param aSearchCase identifies what items are we looking for:
1.154 + * EFindItemSearchPhoneNumberBin
1.155 + * EFindItemSearchMailAddressBin
1.156 + * EFindItemSearchURLBin
1.157 + * EFindItemSearchScheme
1.158 + * Any combination of these flags can be given as a bit mask.
1.159 + * @return a pointer to an new instance of CFindItemEngine class.
1.160 + *
1.161 + * @panic ENoSearchCase in debug build if there is no valid search case.
1.162 + * @panic EItemOutOfDocumentRange in debug build if item's position
1.163 + * and/or length is out of the document's range.
1.164 + * @leave one of the Symbian error codes.
1.165 + */
1.166 + IMPORT_C static CFindItemEngine* NewL( const TDesC& aText,
1.167 + const TFindItemSearchCase aSearchCase );
1.168 +
1.169 + /**
1.170 + * Two-phase constructor method that is used to create a new instance
1.171 + * of the CFindItemEngine class. This instance can then be queried for
1.172 + * the items defined by the second parameter. The actual search is
1.173 + * executed during construction.
1.174 + *
1.175 + * @param aText will be parsed.
1.176 + * @param aSearchCase identifies what items are we looking for:
1.177 + * EFindItemSearchPhoneNumberBin
1.178 + * EFindItemSearchMailAddressBin
1.179 + * EFindItemSearchURLBin
1.180 + * EFindItemSearchScheme
1.181 + * Any combination of these flags can be given as a bit mask.
1.182 + * @param aMinNumbers defines minimun count of numbers in a string that
1.183 + * the string is considered as a phone number when phone numbers are
1.184 + * searched.
1.185 + * @return a pointer to an new instance of CFindItemEngine class.
1.186 + *
1.187 + * @panic ENoSearchCase in debug build if there is no valid search case.
1.188 + * @panic EItemOutOfDocumentRange in debug build if item's position
1.189 + * and/or length is out of the document's range.
1.190 + * @leave one of the Symbian error codes.
1.191 + */
1.192 + IMPORT_C static CFindItemEngine* NewL( const TDesC& aText,
1.193 + const TFindItemSearchCase aSearchCase,
1.194 + const TInt aMinNumbers );
1.195 +
1.196 + /**
1.197 + * Destructor.
1.198 + */
1.199 + IMPORT_C virtual ~CFindItemEngine();
1.200 +
1.201 + public:
1.202 + /**
1.203 + * Gets the currently 'selected' item in the array of found items.
1.204 + *
1.205 + * @param aItem contains the currently selected item after returning.
1.206 + * @return ETrue if the item was found. EFalse if the item wasn't found.
1.207 + */
1.208 + IMPORT_C TBool Item( SFoundItem& aItem );
1.209 +
1.210 + /**
1.211 + * Gets the next found item relative to the currently selected item
1.212 + * and moves the selection to point to the next item in the array of
1.213 + * found items.
1.214 + *
1.215 + * @param aItem contains the next item after returning.
1.216 + * @return ETrue if the item was found. EFalse if there's no next item.
1.217 + */
1.218 + IMPORT_C TBool NextItem( SFoundItem& aItem );
1.219 +
1.220 + /**
1.221 + * Gets the previous found item relative to the currently selected
1.222 + * item and moves the selection to point to the previous item in the
1.223 + * array of found items..
1.224 + *
1.225 + * @param aItem contains the previous item after returning.
1.226 + * @return ETrue if the item was found. EFalse if there's no previous item.
1.227 + */
1.228 + IMPORT_C TBool PrevItem( SFoundItem& aItem );
1.229 +
1.230 + /**
1.231 + * Gets the array of found items. Returns a constant pointer to the
1.232 + * found items array of the CFindItemEngine instance. The items cannot
1.233 + * be modified through this pointer, only accessed. The ownership of
1.234 + * the array stays with CFindItemEngine.
1.235 + *
1.236 + * @return a constant pointer to the array of found items. Ownership
1.237 + * stays with CFindItemEngine.
1.238 + */
1.239 + IMPORT_C const CArrayFixFlat<SFoundItem>* ItemArray() const;
1.240 +
1.241 + /**
1.242 + * Gets the current position (or the position of the currently selected item)
1.243 + * in the found items array.
1.244 + *
1.245 + * @return the current position in the found items array of the
1.246 + * CFindItemEngine instance. If no items are in the array, zero is
1.247 + * returned.
1.248 + */
1.249 + IMPORT_C TInt Position() const;
1.250 +
1.251 + /**
1.252 + * Resets the position in item array to zero (beginning of the array).
1.253 + */
1.254 + IMPORT_C void ResetPosition();
1.255 +
1.256 + /**
1.257 + * Gets the number of items in the found items array.
1.258 + *
1.259 + * @return the number of items in the found items array.
1.260 + */
1.261 + IMPORT_C TInt ItemCount() const;
1.262 +
1.263 + /**
1.264 + * Executes a new search with the already created CFindItemEngine
1.265 + * instance. The position in the found items array is reset to the
1.266 + * beginning of the array.
1.267 + *
1.268 + * @param aText will be parsed.
1.269 + * @param aSearchCase identifies what items are we looking for:
1.270 + * EFindItemSearchPhoneNumberBin
1.271 + * EFindItemSearchMailAddressBin
1.272 + * EFindItemSearchURLBin
1.273 + * EFindItemSearchScheme
1.274 + * Any combination of these flags can be given as a bit mask.
1.275 + * @return number of found items.
1.276 + *
1.277 + * @panic ENoSearchCase in debug build if there is no valid search case.
1.278 + * @panic EItemOutOfDocumentRange in debug build if item's position
1.279 + * and/or length is out of the document's range.
1.280 + * @leave one of the Symbian error codes.
1.281 + */
1.282 + IMPORT_C TInt DoNewSearchL( const TDesC& aText, const TFindItemSearchCase aSearchCase);
1.283 +
1.284 + /**
1.285 + * Executes a new search with the already created CFindItemEngine
1.286 + * instance. The position in the found items array is reset to the
1.287 + * beginning of the array.
1.288 + *
1.289 + * @param aText will be parsed.
1.290 + * @param aSearchCase identifies what items are we looking for:
1.291 + * EFindItemSearchPhoneNumberBin
1.292 + * EFindItemSearchMailAddressBin
1.293 + * EFindItemSearchURLBin
1.294 + * EFindItemSearchScheme
1.295 + * Any combination of these flags can be given as a bit mask.
1.296 + * @param aMinNumbers defines minimun count of numbers in a string that
1.297 + * the string is considered as a phone number when phone numbers are
1.298 + * searched.
1.299 + * @return number of found items.
1.300 + *
1.301 + * @panic ENoSearchCase in debug build if there is no valid search case.
1.302 + * @panic EItemOutOfDocumentRange in debug build if item's position
1.303 + * and/or length is out of the document's range.
1.304 + * @leave one of the Symbian error codes.
1.305 + */
1.306 + IMPORT_C TInt DoNewSearchL( const TDesC& aText, const TFindItemSearchCase aSearchCase,
1.307 + const TInt aMinNumbers );
1.308 +
1.309 + private:
1.310 +
1.311 + /**
1.312 + * Adds item to search arrays. Adding is done so that arrays are always sorted.
1.313 + * If added element would overlap a previously found element, it is not added.
1.314 + *
1.315 + * @param aStartPos Start position of the found item
1.316 + * @param aLength Length of found item
1.317 + * @param aType Type of the found item
1.318 + */
1.319 + void AddItemL( const TInt& aStartPos, const TInt& aLength,
1.320 + const TFindItemSearchCase& aType );
1.321 +
1.322 + /**
1.323 + * Search algorithm for searching phone numbers
1.324 + *
1.325 + * @param aText Text that will be parsed
1.326 + * @return Whether any items were found
1.327 + */
1.328 + TBool SearchPhoneNumberL( const TDesC& aText);
1.329 +
1.330 + /**
1.331 + * Search algorithm for searching e-mail addresses
1.332 + *
1.333 + * @param aText Text that will be parsed
1.334 + * @return Whether any items were found
1.335 + */
1.336 + TBool SearchMailAddressL( const TDesC& aText);
1.337 +
1.338 + /**
1.339 + * Search algorithm for searching generic URIs
1.340 + *
1.341 + * @param aText Text that will be parsed
1.342 + * @return Whether any items were found
1.343 + */
1.344 + TBool SearchGenericUriL( const TDesC& aText);
1.345 +
1.346 + /**
1.347 + * Search fixed start URLs, i.e. URLs without schema (www., wap.).
1.348 + * Also finds IPv4 addresses (*.*.*.*).
1.349 + * As a special case, supports deprecated hardcoded schematic addresses finding
1.350 + * (http://, https://, rtsp://) to make sure deprecated search cases work
1.351 + * as they did previously.
1.352 + *
1.353 + * @param aText Text that will be parsed
1.354 + * @param aFindFixedSchemas If true, will find old fixed schematic URLs also
1.355 + * @return Whether any items were found
1.356 + */
1.357 + TBool SearchUrlL( const TDesC& aText, const TBool aFindFixedSchemas);
1.358 +
1.359 + /**
1.360 + * Parses URL from a token. Is used by SearchUrlL method and if a URL
1.361 + * was found it's appended to item array. Note that parsing for generic URIs
1.362 + * is done with SearchGenericUriL -method.
1.363 + *
1.364 + * @param aType a Type of URL to seach, i.e.
1.365 + * www.
1.366 + * wap.
1.367 + * IP e.g.127.0.0.1
1.368 + * @param aTokenPtr Pointer to token that will be parsed
1.369 + * @param aTextOffset Offset of the token (start position in the whole text)
1.370 + * @return Whether any items were found
1.371 + */
1.372 + TBool ParseUrlL( const TDesC& aType, const TPtrC& aTokenPtr, const TInt aTextOffset );
1.373 +
1.374 + /**
1.375 + * Character information methods
1.376 + *
1.377 + * @param charac a Character to be investigated
1.378 + * @return Whether the parameter was a valid for:
1.379 + */
1.380 + TBool IsValidEmailChar( const TChar& charac ) const; // Login part of the e-mail address
1.381 + TBool IsValidEmailHostChar( const TChar& charac ) const; // Host part of the e-mail address
1.382 + TBool IsValidPhoneNumberChar( const TChar& charac ) const; // Phone number
1.383 + TBool IsValidUrlChar( const TChar& charac ) const; // URL
1.384 +
1.385 + /**
1.386 + * C++ default constructor.
1.387 + */
1.388 + CFindItemEngine();
1.389 +
1.390 + /**
1.391 + * Symbian OS constructor
1.392 + *
1.393 + * @param aText Text that will be parsed
1.394 + * @param aSearchCase Identifies what items are we looking for:
1.395 + * EFindItemSearchPhoneNumberBin
1.396 + * EFindItemSearchMailAddressBin
1.397 + * EFindItemSearchURLBin
1.398 + * EFindItemSearchScheme
1.399 + * Any combination of these flags can be given
1.400 + * as a bit mask.
1.401 + * @param aMinNumbers Minimun count of numbers in a string when
1.402 + * the string is considered as a phone number.
1.403 + */
1.404 + void ConstructL( const TDesC& aText, const TFindItemSearchCase aSearchCase,
1.405 + const TInt aMinNumbers );
1.406 + /**
1.407 + * Performs the search.
1.408 + * Uses search algorithms SearchGenericUriL(), SearchMailAddressL(),
1.409 + * SearchUrlL() and SearchPhoneNumberL().
1.410 + *
1.411 + * @param aText Reference to the text to be parsed.
1.412 + * @param aSearchCase identifies what items are we looking for.
1.413 + */
1.414 + void PerformSearchL( const TDesC& aText , const TFindItemSearchCase aSearchCase );
1.415 +
1.416 +
1.417 + /**
1.418 + * Converts arabic numbers to western numbers.
1.419 + * When returning the aBuf contains the modified text.
1.420 + *
1.421 + * @param aBuf A pointer to the buffer containing the text.
1.422 + */
1.423 + void ConvertArabicNumbersToWesternNumbers( HBufC* aBuf );
1.424 +
1.425 + /**
1.426 + * By default, prohibit copy constructor
1.427 + */
1.428 + CFindItemEngine( const CFindItemEngine& );
1.429 + /**
1.430 + * Prohibit assigment operator
1.431 + */
1.432 + CFindItemEngine& operator= ( const CFindItemEngine& );
1.433 +
1.434 + private: // Data
1.435 + // Array of all found items.
1.436 + CArrayFixFlat<SFoundItem>* iItemArray;
1.437 + // Engine's position in the iItemArray and iItemTypeArray.
1.438 + TInt iPosition;
1.439 + // Minimum count of numbers in a phone number
1.440 + TInt iMinNumbers;
1.441 + };
1.442 +
1.443 +#endif // FINDITEMENGINE_H
1.444 +
1.445 +// End of File