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.
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.
Related APIs
CPsRequestHandlerMPsResultsObserver
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
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
MPsResultsObserverSearchL()
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()TPsMatchLocationmatchLocationmatchSet
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()matchStringpsQuerystrData
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 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
CPsClientDataDataExtensionIsMarked()MPsResultsObserverSearchL()
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
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
HandlePsErrorLMPsResultsObserver
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
Extensions to the API
None.
Limitations of the API
None.