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