CFindItemEngine Class Reference

API published in: S60 3rd Ed

Link against: commonengine.lib

Capability Information

Required Capabilities

None

#include <finditemengine.h>

Detailed Description

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: 

  #include <finditemengine.h>

  // SFoundItem instance
  CFindItemEngine::SFoundItem item;

  // Some text
  TBufC<256> strSomeText(_L("Mail to [email protected] 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 ([email protected]) 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;

Public Types
enum   TFindItemSearchCase { EFindItemSearchPhoneNumberBin = 4, EFindItemSearchMailAddressBin = 8, EFindItemSearchURLBin = 16, EFindItemSearchScheme = 32 }
  Enumeration to define the search case. More...

Public Member Functions
virtual IMPORT_C  ~CFindItemEngine ()
  Destructor.
IMPORT_C TBool  Item (SFoundItem &aItem)
  Gets the currently 'selected' item in the array of found items.
IMPORT_C TBool  NextItem (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.
IMPORT_C TBool  PrevItem (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.
IMPORT_C const CArrayFixFlat<
SFoundItem > *  		ItemArray () const
  Gets the array of found items.
IMPORT_C TInt  Position () const
  Gets the current position (or the position of the currently selected item) in the found items array.
IMPORT_C void  ResetPosition ()
  Resets the position in item array to zero (beginning of the array).
IMPORT_C TInt  ItemCount () const
  Gets the number of items in the found items array.
IMPORT_C TInt  DoNewSearchL (const TDesC &aText, const TFindItemSearchCase aSearchCase)
  Executes a new search with the already created CFindItemEngine instance.
IMPORT_C TInt  DoNewSearchL (const TDesC &aText, const TFindItemSearchCase aSearchCase, const TInt aMinNumbers)
  Executes a new search with the already created CFindItemEngine instance.

Static Public Member Functions
static IMPORT_C CFindItemEngine *  NewL (const TDesC &aText, const TFindItemSearchCase aSearchCase)
  Two-phase constructor method that is used to create a new instance of the CFindItemEngine class.
static IMPORT_C CFindItemEngine *  NewL (const TDesC &aText, const TFindItemSearchCase aSearchCase, const TInt aMinNumbers)
  Two-phase constructor method that is used to create a new instance of the CFindItemEngine class.

Data Structures
struct   SFoundItem
  Struct to contain an item. More...

Member Enumeration Documentation

enum CFindItemEngine::TFindItemSearchCase
 

Enumeration to define the search case.

Multiple enumerations can be used as binary mask.

Enumerator:
EFindItemSearchPhoneNumberBin  Searches phone numbers.
EFindItemSearchMailAddressBin  Searches mail addresses.
EFindItemSearchURLBin  Searches fixed start URLs ("http://", "https://", "rtsp://"), "www.", "wap." and IPv4 addresses.
EFindItemSearchScheme  Searches for all URIs containing a scheme.

Constructor & Destructor Documentation

virtual IMPORT_C CFindItemEngine::~CFindItemEngine (   )  [virtual]
 

Destructor.

Member Function Documentation

IMPORT_C TInt CFindItemEngine::DoNewSearchL (  const TDesC &  aText,
const TFindItemSearchCase  aSearchCase,
const TInt  aMinNumbers
) 
 

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.

Parameters:
aText  will be parsed.
aSearchCase  identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
aMinNumbers  defines minimun count of numbers in a string that the string is considered as a phone number when phone numbers are searched.
Returns:
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 CFindItemEngine::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.

Parameters:
aText  will be parsed.
aSearchCase  identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
Returns:
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 TBool CFindItemEngine::Item (  SFoundItem &  aItem  ) 
 

Gets the currently 'selected' item in the array of found items.

Parameters:
aItem  contains the currently selected item after returning.
Returns:
ETrue if the item was found. EFalse if the item wasn't found.
IMPORT_C const CArrayFixFlat<SFoundItem>* CFindItemEngine::ItemArray (   )  const
 

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.

Returns:
a constant pointer to the array of found items. Ownership stays with CFindItemEngine.
IMPORT_C TInt CFindItemEngine::ItemCount (   )  const
 

Gets the number of items in the found items array.

Returns:
the number of items in the found items array.
static IMPORT_C CFindItemEngine* CFindItemEngine::NewL (  const TDesC &  aText,
const TFindItemSearchCase  aSearchCase,
const TInt  aMinNumbers
)  [static]
 

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.

Parameters:
aText  will be parsed.
aSearchCase  identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
aMinNumbers  defines minimun count of numbers in a string that the string is considered as a phone number when phone numbers are searched.
Returns:
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.
static IMPORT_C CFindItemEngine* CFindItemEngine::NewL (  const TDesC &  aText,
const TFindItemSearchCase  aSearchCase
)  [static]
 

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.

Parameters:
aText  will be parsed.
aSearchCase  identifies what items are we looking for: EFindItemSearchPhoneNumberBin EFindItemSearchMailAddressBin EFindItemSearchURLBin EFindItemSearchScheme Any combination of these flags can be given as a bit mask.
Returns:
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 TBool CFindItemEngine::NextItem (  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.

Parameters:
aItem  contains the next item after returning.
Returns:
ETrue if the item was found. EFalse if there's no next item.
IMPORT_C TInt CFindItemEngine::Position (   )  const
 

Gets the current position (or the position of the currently selected item) in the found items array.

Returns:
the current position in the found items array of the CFindItemEngine instance. If no items are in the array, zero is returned.
IMPORT_C TBool CFindItemEngine::PrevItem (  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.

Parameters:
aItem  contains the previous item after returning.
Returns:
ETrue if the item was found. EFalse if there's no previous item.
IMPORT_C void CFindItemEngine::ResetPosition (   ) 
 

Resets the position in item array to zero (beginning of the array).

The documentation for this class was generated from the following file:
Copyright © Nokia Corporation 2001-2008
Back to top