Changes

No changes in the header files.

Purpose

The purpose of the Predictive Search Utilities API is to provide interfaces to access helper objects used in performing predictive search and in interpretation of search results.

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 exceptions:

  • SIM card is not accessible on the emulator

API description

The Predictive Search Utilities API can be categorized as a library/settings API, and it offers common functions used in Predictive Search, such as:

  • Setting the search configuration

  • Creating search query

  • Parsing search results

Use cases

The most common use cases of the Predictive Search Utilities API are as listed below:

  • Setting the search configuration

    • Setting the search data stores

    • Setting the search data fields

    • Setting the maximum search results

    • Setting the sort type

  • Creating search query

    • ITU-T mode, or Predictive Search Enabled mode

    • QWERTY mode, or Predictive Search Disabled mode

    • Mixed mode; i.e. devices that support both ITU-T and QWERTY keyboards, or search query composed of Predictive Search enabled and disabled items

  • Parsing search results

    • Parsing search data

    • Parsing search pattern

    • Getting the originating data store of a result

    • Getting the identifier of a result

API class structure

The API class structure of the Predictive Search Utilities API is shown below.

Class diagram of the Predictive Search U...


Class diagram of the Predictive Search Utilities API

Using the Predictive Search Utilities API

Setting the search configuration

The following sections explain how various search configurations can be performed.

Setting the search data stores

Code Snippet: Set the data store to be searched as contacts in phone memory

// Required includes
#include "CPsSettings.h"

// Link Library
// PcsUtils.lib

// Create the store URI and append to an array
RPointerArray<TDesC> dataStores;
HBufC* store1 = HBufC::NewLC(50);
store1->Des().Copy(_L("cntdb:://c:contatcs.cdb")); // URI for phone memory 
dataStores.Append(store1);
CleanupStack::Pop();

// Create a settings object and set the data stores
CPsSettings* psSettings = CPsSettings::NewL();
psSettings->SetSearchUrisL(dataStores);

// Cleanup 

// Send the new settings to the PS Engine. Refer to PS Client API documentation

Contact Type

URI

Contacts in Phone Memory

cntdb://c:contacts.cdb

Contacts in SIM ADN

sim://global_adn

Contacts in SIM FDN

sim://global_fdn

Contacts in SIM SDN

sim://global_sdn

Groups

cntdb://c:contacts.gdb

Group with identity 100

cntdb://c:contacts.gdb?id=100

Setting the search data fields

Code Snippet: Set the data fields to be searched as first name and last name

// Required includes
#include <vpbkeng.rsg>
#include "CPsSettings.h"

// Link Library
// PcsUtils.lib

// Include First Name, Last Name in the search
RArray<TInt> displayFields;
displayFields.Append(R_VPBK_FIELD_TYPE_FIRSTNAME); // VPbk identifier for Firstname
displayFields.Append(R_VPBK_FIELD_TYPE_LASTNAME); // VPbk identifier for Lastname

// Create a settings object and set the search fields
CPsSettings* psSettings = CPsSettings::NewL();
psSettings->SetDisplayFieldsL(displayFields);

//Cleanup 

// Send the new settings to the PS Engine. Refer to PS Client API documentation

Setting the maximum search results

Code Snippet: To set only top 100 search results are required

// Required Includes
#include "CPsSettings.h"

// Link Library
// PcsUtils.lib

// Create the setting object
CPsSettings* psSettings = CPsSettings::NewL();
psSettings->SetMaxResults(100);

// Cleanup memory

// Send the new settings to the PS Engine. Refer to PS Client API documentation

Setting the sort type

EAlphabeticalEPatternBased
Code Snippet: Set the sort type for search results

// Required includes
#include "CPsSettings.h"

// Link Library
// PcsUtils.lib

// Create a settings object and set the sort type as alphabetical
CPsSettings* psSettings = CPsSettings::NewL();
psSettings->SetSortType(EAlphabetical);

// Cleanup 

// Send the new settings to the PS Engine. Refer to PS Client API documentation
Related APIs
  • EAlphabetical
  • EPatternBased

Creating search query

CPsQuery. Each CPsQuery comprises of multiple CpsQueryItems. Each query item has the search character and the keyboard mode (one of EItut, EQwerty).

Code Snippet: Create a predictive search query for ITU-T mode

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

// Link Library
// PcsUtils.lib

// Assumption: Buffer (TBuf<KPsQueryMaxLen> buf) holds the query as received from the UI

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

// Create one query item 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);
}

//Cleanup memory

ITU-T mode

EItut while creating the search query.

Related APIs
  • EItut

QWERTY mode

EQwerty.

Related APIs
  • EQwerty

Mixed mode (both ITU-T and QWERTY mode)

EQwerty or EItut for each character query item.

Related APIs
  • EItut
  • EQwerty
Related APIs
  • CPsQuery
  • CpsQueryItem
  • EItut
  • EQwerty

Parsing search results

This section explains how the Predictive Search results returned by the engine can be parsed and interpreted for the client use.

Parsing search data

CPsClientData objects and through the MPsResultsObserver interface. Each CPsClientData object contains the identifier of the result, the data store identifier and the actual data.

Code Snippet: Extract the data from the search results

// Required Includes
#include "CPsClientData.h"

// Link Library
// PcsUtils.lib

// For storing  the search results
RPointerArray<CPsData> searchResults;

// Perform a search here

// Results are received through MPsResultsObserver interface

// Assumption: searchResults is already filled

for( TInt counter = 0 ; counter < searchResults.Count(); counter++)
{
    HBufC* data = HBufC::NewLC(255);
    CPsClientData* result = searchResults[counter];
    
    // Parse and append the data elements
    for ( int dataIndex = 0; dataIndex < result->DataElementCount(); dataIndex++ )
    {
        data->Des().Append(result->Data(dataIndex)->Des());
        data->Des().Append(KSpace);                  
    } 
    
    // "data" has the "FirstName LastName"
    
    // Cleanup
}

// Cleanup
Related APIs
  • CPsClientData
  • MPsResultsObserver

Parsing search pattern

CPsPattern objects and through the MPsResultsObserver interface. Each CPsPattern object contains the matching pattern (for example AA, AB, AC etc.) and the location of the first occurrence of each pattern in the results array. The first occurrence is a valid number only if the sort type specified by the client is EPatternBased.

Code Snippet: Parse search patterns from the results

// Required Includes
#include "CPsPattern.h"

// Link Library
// PcsUtils.lib

// For storing  the search patterns
RPointerArray<CPsPattern> searchPatterns;

// Perform a search here

// Results are received through MPsResultsObserver interface

// Assumption: searchPatterns is already filled

for( TInt counter = 0 ; counter < searchPatterns.Count(); counter++)
{   
    CPsPattern* pattern = searchPatterns[counter];
    
    // First occurrence of this pattern in the search results array
    TInt firstIndex = pattern->FirstIndex();

    // Get the pattern string
    TPtrC patterStr = pattern->Pattern();
}

// Cleanup
Related APIs
  • CPsPattern
  • EPatternBased
  • MPsResultsObserver

Getting the originating data store of a result

Code Snippet: Get the orginating data store for a search result

// Required Includes
#include "CPsClientData.h"

// Link Library
// PcsUtils.lib

// Assumption: Predictive search is already performed
// RPointerArray<CPsClientData> searchResults  hold the search results as returned by the PS Engine

// Get the first result
CPsClientData* data = searchResults[0];

// Get the data store uri
TPtrC uri = data->Uri();

Getting the identifier of a result

Code Snippet: Get the identifier for a search result

// Required Includes
#include "CPsClientData.h"

// Link Library
// PcsUtils.lib

// Assumption: Predictive search is already performed
// RPointerArray<CPsClientData> searchResults  hold the search results as returned by the PS Engine

// Get the first result
CPsClientData* data = searchResults[0];

// Get the result Id
TInt resultId = data->Id();

Error handling

None.

Memory overhead

None.

Extensions to the API

None.

Limitations of the API

None.

Glossary

Abbreviations

None.

Definitions

None.

References

Predictive Search Client API Specification