Predictive Search Utilities API
Changes in Predictive Search Utilities API documentation
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:
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:
Use cases
The most common use cases of the Predictive Search Utilities API are as
listed below:
API class structure
The API class structure of the Predictive Search Utilities API is shown
below.
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
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
Creating search query
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
Mixed mode (both ITU-T and QWERTY mode)
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
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
Parsing search pattern
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
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();
Extensions to the API
None.
Limitations of the API
None.
References
| Predictive Search Client API Specification |