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:

  • SIM card is not accessible on the emulator

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

API class structure

Class Diagram of Predictive Search Adapt...


Class Diagram of Predictive Search Adapters API

Related APIs
  • CPsDataPlugin
  • MDataStoreObserver
  • MStoreListObserver

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
  • GetSupportedDataStoresL
  • IsDataStoresSupportedL

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
  • GetSupportedDataFieldsL

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
  • MDataStoreObserver
  • MStoreListObserver
  • RequestForDataL()

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
  • AddDataStore

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
  • RemoveDataStore

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
  • AddData
  • CPsData
  • SetDataL()
  • 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
  • RemoveData

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
  • RemoveAll

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
  • UpdateCachingStatus

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

Error handling

None.

Memory overhead

None.

Extensions to the API

None.

Limitations of the API

None.

Glossary

Abbreviations

None.

Definitions

None.

References

None.