S60 3rd Edition API Reference: CFindItemEngine Class Reference

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

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. Public since 3rd Ed FP1

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. Public since 3rd Ed FP1

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-2007
Back to top