Phonebook 2 xSP Extension Manager API

Changes in Phonebook 2 xSP Extension Manager API documentation

Version Date Status

1.0

22.05.2007

Approved

Changes in Phonebook 2 xSP Extension Manager API

Version Description

1.0

First version

Purpose

The purpose of Phonebook 2 xSP Extension Manager API is to provide third party service providers the means to create UI extensions for Phonebook 2. This document is valid from S60 release 3.2 onwards.

Constraints

Phonebook 2 xSP Extension Manager API can be used only in platforms that contain xSP Extension Manager, i.e. platforms that have the feature flag __XSP_EXTENSION_MANAGER (feature ID KFeatureIdXspExtensionManager) switched on.

API description

Phonebook 2 xSP Extension Manager API is a framework API that enables service providers to create their own UI extensions on top of Phonebook 2. UI extensions created using this API are called xSP extensions, and are not pure Phonebook 2 UI extensions. Instead, they are managed by a component called xSP Extension Manager, which itself is a pure Phonebook 2 UI extension. Technically, both xSP extensions and Phonebook 2 UI extensions are ECOM plug-ins. xSP Extension Manager API provides a limited sandbox of operations for xSP extensions, so that Phonebook 2 itself does not have to open its UI extension interfaces for third party service providers. xSP Extension Manager also provides some additional functionality in the form of xSP extension sorting and view and command ID mapping, so service providers do not have to worry about duplicate view or command IDs between xSP extensions. This API provides a method call interface.

Use cases

There exists in practise only one main use case for xSP Extension Manager API, and that is creating a new xSP extension. That can be divided into sub-cases, such as creating a tabbed or non-tabbed view, creating options menu extension to Phonebook 2's Names List view, and using Extension Manager provided utility classes during those creation operations.

API class structure

The Phonebook 2 xSP Extension Manager API class structure is presented below. Classes shown as grey are or Phonebook 2 base classes that this API or its user derives from. Green classes are the API itself, and the yellow classes are the user of this API, in this case a component called SimpleExample. The first figure shows the structure of extension factory class. Each xSP extension must have a factory that is derived from CxSPFactory, which itself is a CBase derived class, and also deriving from the MxSFactory interface. MxSPFactory is the abstract factory interface for creating Phonebook 2 xSP extensions, while CxSPFactory contains the minimal ECOM session implementation.

Extension factory inheritance


Extension factory inheritance

xSP Extension should also have view classes, so their inheritance structure is shown in the second figure. The views are derived from the API's CxSPBaseView class, which uses other API interfaces and Phonebook 2 base classes. CxSPBaseView is a base class for xSP views that contains some functionality common to all xSP views, and e.g. references to theMxSPContactManager and MxSPViewMapper utilities. MxSPContactManager is an interface through which Extension Manager implemented contact managing/mapping functionality can be accessed. Likewise, MxSPViewMapper is an interface through which Extension Manager implemented view mapping functionality can be accessed. It must be noted that the xSP view classes are not themselves CAknView derived. Instead, they are using a CPbk2UIExtensionView class instance for CAknViewrelated operations.

Extension view inheritance


Extension view inheritance

The third figure shows the class structure of an optional Names List extension class. It needs to be implemented only if xSP wants to extend Phonebook 2's Names List view. Names List extension classes are derived from MxSPView, which is an abstract interface for Phonebook 2 xSP view extensions, i.e. xSPs can extend Phonebook 2 views by implementing a class derived from it. Currently only Names List view extending is supported. MxSPBase is a base interface for other Extension Manager interfaces. Names List extension also needs a reference to MxSPCommandMapper, which is an interface through which Extension Manager implemented command mapping functionality can be accessed.

Optional Names List extension inheritanc...


Optional Names List extension inheritance

Related APIs
  • CAknView
  • CBase
  • CPbk2UIExtensionView
  • CxSPBaseView
  • CxSPFactory
  • MxSFactory
  • MxSPBase
  • MxSPCommandMapper
  • MxSPContactManager
  • MxSPFactory
  • MxSPView
  • MxSPViewMapper

Using xSP Extension Manager API

xSP Extension Manager API is used for creating an xSP extension. For that, classes derived from the API's CxSPFactory, CxSPBaseView, and optionally MxSPView must be implemented. These API classes provide also handles for using the Extension Manager's utility classes through interfaces such as MxSPContactManager, MxSPViewMapper and MxSPCommandMapper.

Example use case: xSP extension creation

Creating an xSP extension takes several implementation steps, and some of the most important ones are described below as use cases. xSP extension is basically an ECOM plug-in which additionally implements some interfaces defined in xSP Extension Manager API, described in previous chapters.

Creating a tabbed xSP view

By following the four steps below, a new tab view is created to Phonebook 2:

1. xSP Extension Manager is told about the new views by defining a new xSP_VIEW_INFO resource. For a tabbed view, the following fields are to be defined:

  • oldId: original view ID chosen by the xSP developer.

  • tabView: Boolean flag whether this is a tab view.

  • tabIconId: icon ID for tab icon to be shown in the UI (in tab header).

  • tabIconMaskId: mask ID for tab icon to be shown in the UI (in tab header).

  • tabIconFile: icon MBM file path without drive.

  • name: name of the view. If you have same service tab in CCA view, and you want the service tab orders in CCA follows the orders of service tabs in phonebook, this name must not be empty and must be identical to the display_name of corresponding service tab plug-in in CCA. display_name of the plug-in is described in cca_view_plugin_api documentation.

RESOURCE XSP_VIEW_INFO_ARRAY r_example_view_info  
    {
    items =
        {
        XSP_VIEW_INFO
            {
            oldId = EExampleTabbedViewId;
            tabView = 1;
            tabIconId = qgn_example_tab;
            tabMaskId = qgn_example_tab_mask;
            tabIconFile = "\\resource\\example.mbm";
            name = "view name";
            },
        XSP_VIEW_INFO
            {
            oldId = EExampleDetailsViewId;
            name = "view name";
            }
        };
    }
TInt CExampleExtensionFactory::ViewInfoResource() const
    {
    return R_EXAMPLE_VIEW_INFO;
    }

2. The CreateViewL method is implemented to the factory class (CExampleExtensionFactory). It should be noted that the MxSPViewMapper utility is used to map the view ID that this method is called with to the original view ID, EExampleTabbedViewId, that was set in the resource in the previous step. xSP Extension Manager keeps track of unique view IDs via MxSPViewMapper so that xSP extensions do not need to worry about duplicate view IDs between extensions.

CxSPBaseView* CExampleExtensionFactory::CreateViewL( TUid aViewId, CPbk2UIExtensionView& aView )
    {
    CxSPBaseView* view = NULL;

    TInt oldView;
    TInt err = iMapper->GetOldView( KEXAMPLEIMPLEMENTATIONUID, aViewId.iUid, oldView );

    if( !err )
        {
        switch( oldView )
            {
            // Two additional views in this example, "tabbed view" and "details view"
            case EExampleTabbedViewId:
                {
                view = CExampleTabbedView::NewL( *iMapper, *iContactManager, aView );
                break;
                }
            case EExampleDetailsViewId:
                {
                view = CExampleDetailsView::NewL( *iMapper, *iContactManager, aView );
                break;
                }
            default:
                break;
            }
        }

    return view;
    }

3. The view class is created (in this example, CExampleTabbedView) as a CxSPBaseView derived class.

CExampleTabbedView::CExampleTabbedView( MxSPViewMapper& aMapper,
                         MxSPContactManager& aContactManager,
                         CPbk2UIExtensionView& aView ) :
                    CxSPBaseView( aMapper, aContactManager, aView )
    {
    }

inline void CExampleTabbedView::ConstructL()
    {
    ViewBaseConstructL( KEXAMPLEIMPLEMENTATIONUID, EExampleTabbedViewId );        
    }

4. The CPbk2UIExtensionView instance is received as view class constructor parameter and stored as an iView member. As the xSP view class itself is not CAknView derived, iView should be used for all CAknView related calls and for accessing some Phonebook 2 base instances, for example CAknViewAppUi derived CPbk2AppUiBase as shown below.

CExampleTabbedView::~CExampleTabbedView()
    {
    if (iContainer)
        {
        iView.Pbk2AppUi()->RemoveFromStack(iContainer);
        }
    delete iContainer;
    }
Related APIs
  • CAknView
  • CAknViewAppUi
  • CExampleTabbedView
  • CPbk2AppUiBase
  • CPbk2UIExtensionView
  • CreateViewL
  • CxSPBaseView
  • EExampleTabbedViewId
  • MxSPViewMapper
  • iView

Creating a Phonebook 2 Names List view extension

By following the five steps below, new menu items are added to the Names List view options menu and the invocation of these menu items is handled.

1. MxSPView derived class is created in the factory class (CExampleExtensionFactory). In the example the created class is CExampleNamesListViewExtension. The method CreatePbkViewExtensionL is called by Phonebook 2 via xSP Extension Manager to get a handle to the Names List tab view extension.

MxSPView* CExampleExtensionFactory::CreatePbkViewExtensionL()
    {
    MxSPView* extension = CExampleNamesListViewExtension::NewL();
    return extension;
    }

2. In the created MxSPView derived class, the DynInitMenuPaneL method is overridden. This is called by Phonebook 2 just before the Names List view’s options menu is opened.

void CExampleNamesListViewExtension::DynInitMenuPaneL
                ( TInt aResourceId, CEikMenuPane* aMenuPane )
    {
    switch( aResourceId )
        {
        case R_PHONEBOOK2_NAMESLIST_MAIN_MENU:
            {
            // Add the example menu to Names List view's menu
            AddExampleMenuContentsL( *aMenuPane );
            ChangeCommandL( *aMenuPane, EExampleCmdOperations );
            break;
            }
        case R_EXAMPLE_NAMES_LIST_VIEW_SUBMENU:
            {
            ChangeCommandL( *aMenuPane, EExampleCmdOperation1 );
            ChangeCommandL( *aMenuPane, EExampleCmdOperation2 );
            break;
            }
        default:
            break;
        }
    }

3. The new menu items are added to the menu pane. Resource file is used to define the added menu items in the usual way (MENU_PANE, MENU_ITEM).

void CExampleNamesListViewExtension::AddExampleMenuContentsL( CEikMenuPane& aMenuPane )
    {
    TInt newCommand;
    TInt err = iMapper->GetNewCommand( KEXAMPLEIMPLEMENTATIONUID, 
                                       EExampleCmdOperations, 
                                       newCommand );
    User::LeaveIfError( err );
    TInt pos;
    if( !aMenuPane.MenuItemExists( newCommand, pos ) )
        {
        aMenuPane.AddMenuItemsL( R_EXAMPLE_NAMES_LIST_VIEW_MENU );
        }
    }

4. Menu commands are handled by implementing HandleCommandL defined in MxSPView.

TBool CExampleNamesListViewExtension::HandleCommandL( TInt aCommandId,
                                                      MPbk2ContactUiControl* aUiControl )
    {
    TBool result( EFalse );
    TInt oldCommand;
    TInt err = iMapper->GetOldCommand( KEXAMPLEIMPLEMENTATIONUID, aCommandId, oldCommand );

    if( !err )
        {
        switch( oldCommand )
            {
            case EExampleCmdOperation1:
                {
                Operation1L();              
                aUiControl->UpdateAfterCommandExecution();               
                result = ETrue;
                break;
                }
            case EExampleCmdOperation2:
                {
                Operation2L();
                aUiControl->UpdateAfterCommandExecution();
                result = ETrue;
                break;
                }
            default:
                break;
            }   
        }

    return result;
    }

5. Code is added to support command ID mapping. Command ID mapping is a way to solve the problem of keeping all command IDs unique in the Names List view options menu. Basically what is to be done, is to first tell xSP Extension Manager the command IDs of this extension, and then use MxSPCommandMapper to map the xSP’s command IDs to unique IDs that xSP Extension Manager keeps track of.

RESOURCE XSP_COMMAND_INFO_ARRAY r_example_command_info
    {
    items =
        {
        XSP_COMMAND_INFO
            {
            oldId = EExampleCmdOperations;
            },
        XSP_COMMAND_INFO
            {
            oldId = EExampleCmdOperation1;
            },
        XSP_COMMAND_INFO
            {
            oldId = EExampleCmdOperation2;
            }
        };  
    }
TInt CExampleNamesListViewExtension::CommandInfoResource() const
    {
    return R_EXAMPLE_COMMAND_INFO;
    }
void CExampleNamesListViewExtension::RegisterCommandMapper( MxSPCommandMapper& aMapper )
    {
    iMapper = &aMapper
    }

void CExampleNamesListViewExtension::ChangeCommandL( CEikMenuPane& aMenuPane, TInt aOldCommand )
    {       
    TInt pos;
    if( aMenuPane.MenuItemExists( aOldCommand, pos ) )
        {
        TInt newCommand;
        TInt err = iMapper->GetNewCommand( KEXAMPLEIMPLEMENTATIONUID, aOldCommand, newCommand );
        User::LeaveIfError( err );        
        CEikMenuPaneItem::SData& data = aMenuPane.ItemDataByIndexL( pos );
        data.iCommandId = newCommand;
        }
    }
Related APIs
  • CExampleExtensionFactory
  • CExampleNamesListViewExtension
  • CreatePbkViewExtensionL
  • DynInitMenuPaneL
  • HandleCommandL
  • MxSPCommandMapper
  • MxSPView

Error handling

The methods leave in case of an error situation. Normal error handling practises should be used, e.g. using the cleanup stack and the TRAP harness.

Related APIs
  • TRAP

Memory overhead

None.

Extensions to the API

None.

Related APIs
  • CxSPBaseView
  • CxSPFactory
  • MxSPCommandMapper
  • MxSPContactManager
  • MxSPView
  • MxSPViewMapper

Glossary

Abbreviations

None.

Definitions

Definitions

Names List view

The first view (= the main view) when Phonebook 2 is opened. Contains a list of the contacts.

xSP

Phonebook 2 extension provider

xSP extension

A Phonebook 2 UI extension plug-in based on xSP Extension Manager API, created by a third party service provider.

References

None.