Predictive Search Adapters API
Changes in Predictive Search documentation
| Version |
Date |
Status |
|
1.0
|
21.09.2009
|
Approved
|
Purpose
Predictive Search Adapters API enables the adding of new data adapters
to the Predictive Search framework.
Constraints
This API is valid for all platforms running on Symbian OS 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
Predictive Search Adapters API enables the adding of new data adapters
to the Predictive Search framework. Each data adapter is implemented as an
ECOM plug-in and needs to be compliant to the interface definition of
CPsDataPlugin.
The data adapters also need to implement the observers MDataStoreObserver for
adding/ removing of data and MStoreListObserver for adding/
removing data stores.
A prerequisite for any data adapter is that it has an URI to identify itself
and each data item provided by the adapter has a unique identifier.
Use cases
-
Supported URIs
-
Supported data fields
-
Supported data fetch
-
Adding a new data store
-
Removing a data store
-
Adding a data element to the cache
-
Removing a data element from the cache
-
Removing all the data elements from the cache
-
Updating the caching status
Related APIs
CPsDataPluginMDataStoreObserverMStoreListObserver
Using the Predictive Search Adapters API
Supported URIs
Each data adapter added to the Predictive Search framework can support
one or more data stores. Each data store needs to be identified by a unique
URI. The data adapter needs to provide an implementation for the API
GetSupportedDataStoresL that
returns all the data store URIs supported. Internally the framework uses this
list to reserve a memory cache to hold the data.
An implementation needs to be provided also for the API
IsDataStoresSupportedL that
checks if the URI is a valid data store supported by this adapter. This shall
return TRUE if it is a valid URI for this data adapter.
Related APIs
GetSupportedDataStoresLIsDataStoresSupportedL
Supported data fields
The data adapter implementation needs to support an API
GetSupportedDataFieldsL which
returns the list of all data field identifiers supported within this adapter.
Ideally this list is expected to be mapped to Virtual Phonebook identifiers.
Related APIs
Supported data fetch
This Predictive Search framework at any time may request for data to be
cached from the adapter through the
RequestForDataL() API.
The framework also provides an observer instance of MDataStoreObserver and MStoreListObserver through
which adapters can add/ remove data to the cache and dynamically add/ remove
data stores respectively.
Related APIs
MDataStoreObserverMStoreListObserverRequestForDataL()
Adding a new data store
The data adapter can dynamically add a new data store any time using the
AddDataStore method
of the store list observer.
Related APIs
Removing a data store
The data adapter can dynamically remove a new data store any time using
the
RemoveDataStore method of the store list observer. Based
on this call, the framework removes the memory cache and all its contents.
Related APIs
Adding a data element to the cache
The data adapter can add a searchable element to the cache using the
AddData method
of the data store observer. This requires the data to be formatted in the
form of CPsData objects. The mandatory elements that need
to be filled in the CPsData objects are the item ID
to uniquely identify this data element using the SetId() method
and the actual content using the SetDataL() methods.
Related APIs
AddDataCPsDataSetDataL()SetId()
Removing a data element from the cache
The data adapter can remove a searchable element from the cache using the
RemoveData method
of the data store observer. Data is removed based on the item ID set during
the addition of this element.
Related APIs
Removing all data elements from the cache
The data adapter can clear all the contents of a particular memory cache
using the
RemoveAll method of the data store observer.
Related APIs
Updating the caching status
The data adapter needs to update the caching status (such as in-progress,
complete, or errors) using the
UpdateCachingStatus method.
Related APIs
Creating a data adapter
An example implementation of a data adapter is available in
searchengines\psengine\internal\MruAdapter_Dummy.
Refer to this for more implementation specific details.
Example of a data adapter ECOM Resource File
#include <ecom/RegistryInfo.rh>
RESOURCE REGISTRY_INFO theInfo
{
// UID for the DLL
dll_uid = 0x2000B5C3;
// Declare array of interface info
interfaces =
{
INTERFACE_INFO
{
// UID of PS Algorithm interface
interface_uid = 0x2000B5C0;
implementations =
{
// Info for all implementations
IMPLEMENTATION_INFO
{
implementation_uid = 0x2000B5C4;
version_no = 1;
display_name = "PS-Example-Adapter";
default_data = "";
opaque_data = "";
}
};
}
};
};
Example of a data adapter header
#ifndef C_PS_EXAMPLE_ADAPTER_H
#define C_PS_EXAMPLE_ADAPTER_H
// INCLUDES
#include "CPsDataPlugin.h"
class CPsExampleAdapter : public CPsDataPlugin
{
public:
/**
* Two phase construction
*/
static CPsExampleAdapter* NewL(TAny* aPsPluginParams);
// Extract MDataStoreObserver and MStoreListObserver from aPsPluginParams
/**
* Destructor
*/
virtual ~CPsExampleAdapter();
public:
// Implement CPsDataPlugin interface
/**
* Requests for data from this store
* @param aDataStoreURI The data store for which data is requested
*/
void RequestForDataL ( TDesC& aDataStoreURI );
/**
* Gets the supported data stores URIs
* @param aDataStores supported data stores URIs
*/
void GetSupportedDataStoresL( RPointerArray<TDesC> &aDataStores );
/**
* Checks if the given data store is supported.
* @param aDataStoreURI data store
* @return True if this store is supported
*/
TBool IsDataStoresSupportedL( TDesC& aDataStoreURI ) ;
/**
* Gets the supported data fields for specific stores URIs
* @param aDataFields supported data fields for aStoreURI
*/
void GetSupportedDataFieldsL( RArray<TInt> &aDataFields );
private:
/**
* Constructor
*/
CPsExampleAdapter();
/**
* 2nd phase construtor
*/
void ConstructL();
};
#endif // C_PS_EXAMPLE_ADAPTER_H
Extensions to the API
None.
Limitations of the API
None.