Purpose

The purpose of Predictive Search Client API is to provide the client side interface to the Predictive Search Server.

Constraints

This API is valid for all platforms running on Symbian 9.3 or later.

Classification and release information

This API is a domain API and was first published in S60 release 3.2. This document is valid from S60 release 3.2 onwards.

Emulator support

This API is supported in the WINS/WINSCW emulator environment with the following exception:

  • SIM card is not accessible on the emulator.

API description

Predictive Search Client API can be categorized as a Framework / Service API that offers functions for the clients to perform predictive search operations through its interfaces. This API exposes both normal method call interfaces and asynchronous interfaces. This API is the one step point where the clients gain access to the Predictive Search Engine.

Predictive Search Client API provides the client side interface for the Predictive Search Engine. The first step for any client to gain access to the Predictive Search Engine is to create an instance of the CPsRequestHandler object. All interaction with the Predictive Search Engine happen through this object. Some of the method call interfaces like search are asynchronous. In order for the clients to receive search results, errors and other statuses, it is expected that the clients register an observer implementing the MPsResultsObserver interface provided by this API.

A typical client interaction with the Predictive Search Engine is explained below in the diagram.

Predictive Search Client Interaction Flo...


Predictive Search Client Interaction Flow

Use cases

The most common use cases of the Predictive Search Client API are as listed below.

  • Creating an instance of Predictive Search request handler

  • Adding an observer to handle the search results

  • Removing an observer that handles the search results

  • Getting the caching status of the Predictive Search Engine

  • Checking if a language is supported by the Predictive Search Engine

  • Getting all contents of a data store

  • Setting the search parameters to the Predictive Search Engine

  • Performing a predictive search on a data store

  • Performing a predictive lookup on the input data

  • Performing a predictive lookup match on the input data

  • Performing a predictive search including marked data

  • Handling the search errors

  • Handling the search results

  • Retrieving the contact link for a searched result

  • Getting the order of data fields in the search results for a data store

  • Changing the sort order of search results for a data store

  • Getting the sort order of search results for a data store

  • Shutting down the Predictive Search Engine

  • Canceling ongoing search

API class structure

The API class structure of Predictive Search Client API is shown below.

Class Diagram of Predictive Search Clien...


Class Diagram of Predictive Search Client API

Related APIs
  • CPsRequestHandler
  • MPsResultsObserver

Using the Predictive Search Client API

Creating an instance of Predictive Search request handler

Code Snippet: Creation of request handler

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Use this handler instance to access the PS Engine

Adding an observer to handle search results

Code Snippet: Adding an observer to handle results

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Add the observer to handle results
// Assumption: This object implements the MPsResultsObserver interface
handler->AddObserverL(this);

Removing an observer that handles search results

Code Snippet: Removing a registered observer

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Add the observer to handle results
// Assumption: This object implements the MPsResultsObserver interface
handler->RemoveObserver(this);

Getting the caching status of the Predictive Search Engine

Code Snippet: Check the current caching status

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Add the observer to handle status
// Assumption: This object implements the MPsResultsObserver interface
handler->AddObserverL(this);

// Get the caching status synchronously
// 'status' has the caching status
// 'err' has KErrNone or any caching errors
TCachingStatus status;
TInt err = handler->GetCachingStatus(status);

Caching status Description

ECachingNotStarted (0)

Predictive Search Engine has not yet started caching.

ECahingInProgress (10)

Caching has started.

ECachingComplete (20)

Caching is complete without any errors.

ECachingCompleteWithErrors (30)

Caching is complete with errors.

Checking if a language is supported by the Predictive Search Engine

Code Snippet: Check if a language is supported for predictive search 

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Get the current language
TLanguage lang = User::Language();

// Check for language support
TBool supported = handler->IsLanguageSupported(lang);

if ( ! supported )
{
   // Language is not supported by PS Engine
}

// Cleanup

Language Identifiers

ELangJapanese

ELangPrcChinese

ELangHongKongChinese

ELangTaiwanChinese

Setting the search parameters to the Predictive Search Engine

Before a search request is issued, the Predictive Search Engine requires the clients to set the correct search configurations using the SetSearchSettingsL() method. The configuration settings include e.g. the data stores to be searched, fields to be searched, maximum number of results expected and sorting type. For more details on search settings, refer to the Predictive Search Utils API documentation.

Code Snippet: Set the data stores to be searched

// Required Includes
#include "CPsRequestHandler.h"
#include "CPsSettings.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Create predictive search settings
RPointerArray<TDesC> databases;
CPsSettings* searchSettings = CPsSettings::NewL();
HBufC* store1 = HBufC::NewLC(50);
store1->Des().Copy(_L("cntdb://c:contacts.cdb")); // To specify phone contacts store
databases.Append(store1);
searchSettings->SetSearchUrisL(databases);

// Set the new search settings
handler->SetSearchSettingsL(*searchSettings);

// Cleanup
CleanupStack::PopAndDestroy();  // store1

Related APIs
  • SetSearchSettingsL()

Getting all contents of a data store

The Predictive Search Engine supports the fetching of all contents cached for a particular data store. This is supported by the asynchronous method GetAllContentsL(). Results are sent through the MPsResultsObserver interface.

Code Snippet: Initiate request to get all contacts of phone memory

// Required Includes
#include "CPsRequestHandler.h"
#include "CPsSettings.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Create request handler for predictive search engine
CPSRequestHandler* handler = CPSRequestHandler::NewL();

// Add a results observer
handler->AddObserverL(this);

// Create predictive search settings
CPsSettings* searchSettings = CPsSettings::NewL();
HBufC* store1 = HBufC::NewLC(50);
store1->Des().Copy(_L("cntdb://c:contacts.cdb")); // To specify phone contacts store
databases.Append(store1);
searchSettings->SetSearchUrisL(databases);

// Set the new search settings
handler->SetSearchSettingsL(*searchSettings);

// Initiate request to get all contents
handler->GetAllContentsL();

// Cleanup
CleanupStack::PopAndDestroy();  // store1

// Handle resuls in observer interface

Related APIs
  • GetAllContentsL()
  • MPsResultsObserver

Performing a predictive search on a data store

The Predictive Search Engine supports the SearchL() method through which search requests can be sent. This is an asynchronous method. Results are sent through the MPsResultsObserver interface.

Code Snippet: Initiate a search request on the cached contents

// Required Includes
#include "CPsQuery.h"
#include "CPsQueryItem.h"
#include "CPsRequestHandler.h"
#include "CPcsDefs.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Assumptions:
// For details on how to create a search query please refer the sections in PS Utilities API documentation
// Assumption 1: Buffer (TBuf<KPsQueryMaxLen> buf) holds the query as received from the UI
// Assumption 2: CPsRequestHandler instance (handler) is already available and an observer is registered
// Assumotion 3: Required search settings are already configured

// Create a new PS Query object
CPsQuery* psQuery = CPsQuery::NewL();    

// Create one queryitem for every character in the query string and append it to the query object
// Every queryitem is filled with two fields : 
//  1) a character from the query string 
//  2) the keyboard mode using which the query was entered

for ( TInt i = 0; i < buf.Length(); i++ )
{    
   // Add a query item
   CPsQueryItem* item = CPsQueryItem::NewL();
   item->SetCharacter(buf[i]);   
   item->SetMode(EItut); // EItut refers to PS enabled search (normally when numeric keyboard is used)
                         // EQwerty refers to PS disabled search (normally when QWERTY keyboard is used)
   psQuery->AppendL(*item);
}

// Initiate a search request
handler->SearchL(*psQuery);

// Cleanup memory

// Handle resuls in observer interface

Related APIs
  • MPsResultsObserver
  • SearchL()

Performing a predictive lookup on the input data

The Predictive Search Engine supports the LookupL() method through which the search can be performed on an input string. This is a synchronous method. This method also returns the match patterns and the location of matches.

Code Snippet: Perform a predictive search on an input data ("Hello World" in this example)

// Required Includes
#include "CPsQuery.h"
#include "CPsQueryItem.h"
#include "CPsRequestHandler.h"
#include "CPcsDefs.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Assumptions:
// For details on how to create a search query please refer the sections in Ps_utils_API
// Assumption 1: Buffer (TBuf<KPsQueryMaxLen> buf) holds the query as received from the UI
// Assumption 2: CPsRequestHandler instance (handler) is already available

_LIT( val , " Hello World");
HBufC* tmp = HBufC::NewLC(KPsQueryMaxLen);
tmp->Des().Append(val);

RPointerArray <TDesC> matchSet;

// Create a new PS Query object
CPsQuery* psQuery = CPsQuery::NewL();    

// Create one queryitem for every character in the query string and append it to the query object
// Every queryitem is filled with two fields : 
//  1) a character from the query string 
//  2) the keyboard mode using which the query was entered

for ( int i = 0; i < buf.Length(); i++ )
{    
   // Add a query item
   CPsQueryItem* item = CPsQueryItem::NewL();
   item->SetCharacter(buf[i]);   
   item->SetMode(EItut); // Use EQwerty if PS is disabled or QWERTY keyboard is used
   psQuery->AppendL(*item);
}

// Send a search request
RPointerArray <TDesC> matchSet;          // Match patterns
RArray <TPsMatchLocation> matchLocation; // Location of matches
handler->LookupL(*psQuery, *tmp, matchSet, matchLocation);

// Cleanup memory

After the call to LookupL(), matchSet contains the list of matched sequences and matchLocation contains the location of the matches (as defined in the TPsMatchLocation structure).

Related APIs
  • LookupL()
  • TPsMatchLocation
  • matchLocation
  • matchSet

Performing a predictive lookup match on the input data

Predictive Search Engine supports the LookupMatchL() method through which the search can be performed on an input string. This is a synchronous method. This method returns the matched string from the contact data.

Code Snippet: Perform a predictive lookup match on an input data ("Hello World" in this example)

// Required Includes
#include "CPsQuery.h"
#include "CPsQueryItem.h"
#include "CPsRequestHandler.h"
#include "CPcsDefs.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Assumptions:
// For details on how to create a search query please refer the sections in Ps_utils_API
// Assumption 1: Buffer (TBuf<KPsQueryMaxLen> buf) holds the query as received from the UI
// Assumption 2: CPsRequestHandler instance (handler) is already available

_LIT( val , " Hello World");
HBufC* strData = HBufC::NewLC(KPsQueryMaxLen);
strData->Des().Append(val);

// Create a new PS Query object
CPsQuery* psQuery = CPsQuery::NewL();    

// Create one queryitem for every character in the query string and append it to the query object
// Every queryitem is filled with two fields : 
//  1) a character from the query string 
//  2) the keyboard mode using which the query was entered

for ( int i = 0; i < buf.Length(); i++ )
{    
   // Add a query item
   CPsQueryItem* item = CPsQueryItem::NewL();
   item->SetCharacter(buf[i]);   
   item->SetMode(EItut); // Use EQwerty if PS is disabled or QWERTY keyboard is used
   psQuery->AppendL(*item);
}

// Send a search request
TBuf <KPsQueryMaxLen> matchString; // Match string
handler->LookupMatchL(*psQuery, *strData, matchString);

// Cleanup memory

After the call to LookupMatchL(), matchString contains the string which matches to strData according to psQuery and keyboard mapping.

Related APIs
  • LookupMatchL()
  • matchString
  • psQuery
  • strData

Performing a predictive search including marked data

Predictive Search Engine supports the SearchL() method through which the search can be performed including marked data. Marked data refers to the result elements which the clients always expect at the top of the result set, independent of whether the marked data has matched the search query or not. Marked data is communicated to the Predictive Search Engine in the form of CPsClientData objects. If a marked data item also matches the search query, it is removed from the top of the result set. All CPsClientData objects that are marked have an attribute set to TRUE, accessed through IsMarked() in the CPsClientData objects. This is an asynchronous method. Results are sent through the MPsResultsObserver interface.

The clients are expected to fill CPsClientData objects as below:

For contacts in phone memory and groups:

  • ID is filled with Contact Identifier.

  • URI is filled as .cntdb://c:contacts.cdb.

  • ID is filled as -1.

  • URI is filled as one of sim://global_adn, sim://global_fdn or sim://global_sdn.

  • DataExtension has the contact linked packed.

Code Snippet: Perform a predictive search on including marked data

// Required Includes
#include "CPsQuery.h"
#include "CPsQueryItem.h"
#include "CPsRequestHandler.h"
#include "CPcsDefs.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Assumptions:
// For details on how to create a search query please refer the sections in Ps_utils_API
// Assumption 1: Buffer (TBuf<KPsQueryMaxLen> buf) holds the query as received from the UI
// Assumption 2: CPsRequestHandler instance (handler) is already available
// Assumption 3: An instance of contact manager is already available

// Create a new PS Query object
CPsQuery* psQuery = CPsQuery::NewL();    

// Create one queryitem for every character in the query string and append it to the query object
// Every queryitem is filled with two fields : 
//  1) a character from the query string 
//  2) the keyboard mode using which the query was entered

for ( int i = 0; i < buf.Length(); i++ )
{    
   // Add a query item
   CPsQueryItem* item = CPsQueryItem::NewL();
   item->SetCharacter(buf[i]);   
   item->SetMode(EItut); // Use EQwerty if PS is disabled or QWERTY keyboard is used
   psQuery->AppendL(*item);
}

// Construct marked data list
RPointerArray<CPsClientData> markedData;

// Construct a client data object
CPsClientData* markedData1 = CPsClientData::NewL();
markedData1->SetId(10);
markedData1->SetUri(_L("cntdb://c:contacts.cdb"));

markedData.Append(markedData1);

// Send a search request
handler->SearchL(*psQuery, markedData, contactManager);

// Cleanup memory

// Handle resuls in observer interface

Related APIs
  • CPsClientData
  • DataExtension
  • IsMarked()
  • MPsResultsObserver
  • SearchL()

Handling the search results

virtual void HandlePsResultsUpdateL(RPointerArray<CPsClientData>& searchResults, RPointerArray<CPsPattern>& searchSeqs) = 0; 

searchResults [OUT] contains the search results returned from the server in the form of CPsClientData objects. searchSeqs [OUT] is the list of matching character sequences and their first location in the search results array.

Code Snippet: Parse the first search result for displaying in the client

// Required Includes
#include "CPsClientData.h"
#include "CPsPattern.h"
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

void ClientClass::HandlePsResultsUpdateL(RPointerArray<CPsClientData>& searchResults, 
                                         RPointerArray<CPsPattern>& searchSeqs)
{
  // Take the first element in the searchResults and extract the details
  HBufC* data = HBufC::NewLC( 255 );
  _LIT( KSpace," " );

  // Parse the first search result
  CPsClientData* result = searchResults[0];
  for ( TInt dataIndex = 0; dataIndex < result->DataElementCount(); dataIndex++ )
  {
    data->Des().Append(result->Data(dataIndex)->Des());
    data->Des().Append(KSpace);
  } 

  // Example: data has "John Smith Nokia" if First Name, Last Name and Company Name are configured

  // Cleanup memory
}
Related APIs
  • CPsClientData

Handling the search errors

To handle errors during a search, the clients need to implement the MPsResultsObserver interface method HandlePsErrorL.

virtual void HandlePsErrorL(TInt aErrorCode) = 0;

aErrorCode [OUT] contains the search errors returned from the server.

Code Snippet: Handle any search errors at the client

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Interfaces to be Implemented
// MPsResultsObserver

void ClientClass::HandlePsErrorL(TInt aErrorCode)
{

// Display error dialog based on error code
CAknErrorNote* dialog1 = new (ELeave) CAknErrorNote(ETrue);
switch (aErrorCode)
{
  case KErrNotSupported:
    _LIT(KError, "PS not supported ...");
    dialog1->ExecuteLD(KError);
    break;
  default:
    _LIT(KSearchError, "Search error received ...");
    dialog1->ExecuteLD(KSearchError);
    break;
}

// Cleanup

}   
Related APIs
  • HandlePsErrorL
  • MPsResultsObserver

Retrieving the contact link for a searched result

Code Snippet: Fetch the contact link for a search result

// Required Includes
#include "CPsRequestHandler.h"
#include <mvpbkContactLink.h>

// Link Library
// PsServerClientAPI.lib
// VPbkEng.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Assumptions:
// Assumption1: Handler is already initialized
// Assumption2: Search results are available

// Get the contact link for the first search result
MVPbkContactLink* lnk  = handler->ConvertToVpbkLinkLC(*(searchResults[0]));

Getting the order of data fields in the search results for a data store

Data fields supported by the Predictive Search Engine are mapped to Virtual Phonebook identifiers. The Predictive Search Engine exposes an API to identify which data fields are currently used for a data store.

Code Snippet: Data fields supported for a data store

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Assumptions:
// Assumption1: Handler is already initialized

// Phone contacts store
HBufC* store1 = HBufC::NewLC(50);
store1->Des().Copy(_L("cntdb://c:contacts.cdb"));

// Get the data fields currently used
RArray<TInt> dataOrder;
handler->GetDataOrderL(store1, dataOrder);

// dataOrder has the supported virtual phonebook identifiers

// Cleanup

Getting the sort order of search results for a data store

The Predictive Search Engine exposes an API to identify the sort order of data fields currently used for a data store.

Code Snippet: Extract sort order supported for a data store

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Assumptions:
// Assumption1: Handler is already initialized

// Phone contacts store
HBufC* store1 = HBufC::NewLC(50);
store1->Des().Copy(_L("cntdb://c:contacts.cdb"));

// Get the sort order currently used
RArray<TInt> sortOrder;
handler->GetSortOrderL(store1, sortOrder);

// sortOrder has the virtual phonebook identifiers according to which the results are sorted

// Cleanup

Changing the sort order of search results for a data store

The Predictive Search Engine exposes an API to change the sort order of data fields for a data store. The new sort order is retained across reboots of the Predictive Search Engine. Changing the sort order involves re-caching all the contents of the data store, which takes a while.

Code Snippet: Set sort order for a data store

// Required Includes
#include "CPsRequestHandler.h"
#include <vpbkeng.rsg>

// Link Library
// PsServerClientAPI.lib

// Assumptions:
// Assumption1: Handler is already initialized

// Phone contacts store
HBufC* store1 = HBufC::NewLC(50);
store1->Des().Copy(_L("cntdb://c:contacts.cdb"));

// Set the new sort order of data fields
RArray<TInt> sortOrder;
sortOrder.Append(R_VPBK_FIELD_TYPE_COMPANYNAME);
sortOrder.Append(R_VPBK_FIELD_TYPE_LASTNAME);
sortOrder.Append(R_VPBK_FIELD_TYPE_FIRSTNAME);
handler->ChangeSortOrderL(store1, sortOrder);

// Results are sorted based on the new sort order specified.

// Cleanup

Shutting down the Predictive Search Engine

The Predictive Search Engine exposes an API for shutdown.

Code Snippet: Shutdown the PS Engine

// Required Includes
#include "CPsRequestHandler.h"

// Link Library
// PsServerClientAPI.lib

// Assumption: CPsRequestHandler instance (handler) is already available
handler->ShutdownServerL();

Canceling ongoing search

Predictive Search Engine supports the CancelSearch() method through which search requests can be canceled. This is a synchronous method. Results are sent through the MPsResultsObserver interface.

Code Snippet: Initiate a search request on the cached contents and cancel it

// Required Includes
#include "CPsQuery.h"
#include "CPsQueryItem.h"
#include "CPsRequestHandler.h"
#include "CPcsDefs.h"

// Link Library
// PsServerClientAPI.lib
// PcsUtils.lib

// Interfaces to be Implemented
// MPsResultsObserver

// Create a new PS Query object
CPsQuery* psQuery = CPsQuery::NewL();    

// Create one queryitem for every character in the query string and append it to the query object
// Every queryitem is filled with two fields : 
//  1) a character from the query string 
//  2) the keyboard mode using which the query was entered

for ( TInt i = 0; i < buf.Length(); i++ )
{    
   // Add a query item
   CPsQueryItem* item = CPsQueryItem::NewL();
   item->SetCharacter(buf[i]);   
   item->SetMode(EItut); // EItut refers to PS enabled search (normally when numeric keyboard is used)
                         // EQwerty refers to PS disabled search (normally when QWERTY keyboard is used)
   psQuery->AppendL(*item);
}

// Initiate a search request
handler->SearchL(*psQuery);
// ... some actions
// Cancel a search request
handler->CancelSearch();

// Cleanup memory

// Search is canceled

Related APIs
  • CancelSearch()
  • MPsResultsObserver

Error handling

None.

Memory overhead

None.

Extensions to the API

None.

Limitations of the API

None.

Glossary

Abbreviations

None.

Definitions

None.

References

None.