Phonebook 2 xSP View Activation API Specification Document

Changes in Phonebook 2 xSP View Activation API documentation

1.0 22.05.2007 Approved

2.0

29.10.2007

Approved

Update to reflect API extension

Changes in Phonebook 2 xSP View Activation API

1.0 First version

2.0

API has been extended. Functionality has been added to enable getting of xSP extension view related data.

Purpose

Phonebook 2 xSP View Activation API serves two purposes. The first one is to enable external applications to bring xSP extension plug-in views to front, i.e. opening Phonebook 2 to a certain xSP extension view. The second one is to enable getting of xSP extension view related data.

Constraints

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

API description

The Phonebook 2 xSP View Activation API is a Library API that is provided for opening Phonebook 2 to a certain xSP extension view and getting xSP view related data. Primarily, the API enables the developer to summon a view from his xSP extension plug-in by identifying the plug-in UID and the view ID. The standard view activation mechanism cannot be used with xSP extensions, as a methodology called view mapping is used with them. In practise, view mapping means that the xSP developer does not know the real IDs of his xSP extension views as they are assigned runtime at the xSP extension loading phase. Phonebook 2 xSP View Activation API attaches to the xSP Extension Manager component that handles the view mapping and thus the xSP developer known view ID can be used in an API call. Technically, Phonebook 2 xSP View Activation API is a client-server interface. Through the client-server interface the xSP view related data is transferred in a form of descriptor. The Phonebook 2 xSP View Activation API provides means to transform the data from an object to a descriptor form and vice versa.

Use cases

Phonebook 2 xSP View Activation API has two functions. The first one is to launch Phonebook 2 to a certain xSP extension view. This can be done either synchronously or asynchronously with several parameter combinations, so these two cases form the use cases of this API. The second one is to get xSP extension view related data. This can be done synchronously or asynchronously.

API class structure

The Phonebook 2 xSP View Activation API class structure is simple, as the whole API consists of two classes. The first class, RxSPViewServices, is derived from RSessionBase, which is a client-side interface through which communication with the server is channeled. As is also in this case, the clients normally define and implement a derived class to provide a richer interface. The second class, CxSPViewData, is a helper class and used for externalizing the xSP view related data into a descriptor and internalizing the xSP view related data from a descriptor.

xSP View Activation API classes


xSP View Activation API classes

Related APIs
  • CxSPViewData
  • RSessionBase
  • RxSPViewServices

Using the Phonebook 2 xSP View Activation API

RxSPViewServices and CxSPViewData classes are used to access the API. Two synchronous view activation methods can be called directly without initialization of the RxSPViewServices instance. An asynchronous view activation method is also provided. It requires an open client handle. A set of synchronous and asynchronous functions to get xSP view related data are also provided. These functions require an open handle as well. CxSPViewData enables transformation of xSP view data from an object to a descriptor form and vice versa.

Example use case: synchronous view launch

Synchronous view launch is a very simple operation as it consists of only one method call to the API. The handle to API does not have to be initialized in any specific way:

// Handle to xSP View Services API RxSPViewServices
ixSPViewServices; 

The activation call in basic form contains only the xSP extension plug-in UID and the ID of the view to be brought to front:

TUint32 someViewID = 10000; TInt err = ixSPViewServices.Activate(
KUidSomePlugin, someViewID ); User::LeaveIfError( err ); 

There exists also a version of activation call that takes the Phonebook 2 view state as parameter and can thus be used to configure the initial looks of the view, for example which contact field index has the focus:

TUint32
someViewID = 10000; CPbk2ViewState* pbk2ViewParam = CPbk2ViewState::NewLC();
 // set view state here  HBufC8* paramBuf = pbk2ViewParam->PackLC(); TPtr8
ptr = paramBuf->Des();  TInt err = ixSPViewServices.Activate( KUidSomePlugin,
someViewID, ptr ); User::LeaveIfError( err );  CleanupStack::PopAndDestroy(2);
    // pbk2ViewParam, paramBuf 

Example use case: asynchronous view launch

Asynchronous view launch differs from the synchronous one in the following ways: the operation requires separate Open() and Close() calls, and the API calls should be naturally done from active object because of the asynchronous nature. In the code example below the class CSampleViewActivator is derived from CActive. The handle to the API is defined in a similar way as in the synchronous case above.

//
Handle to xSP View Services API RxSPViewServices ixSPViewServices; 

When using the asynchronous API, the Open() call must be done before the activation call, as shown below. In this example the iPtr parameter is TPtr8 similar to the synchronous case, containing the Phonebook 2 view state. aPlugin is the xSP extension plug-in UID and aView the view ID. iStatus is the common CActive TRequestStatus. At the end Close() should be called to close the handle.

void CSampleViewActivator::ActivateL(
TUint32 aPlugin, TUint32 aView )     {     Cancel();     ixSPViewServices.Close();
// cancel & close the possible previous call      User::LeaveIfError(
ixSPViewServices.Open() );                     // Launch Phonebook     ixSPViewServices.Activate(
aPlugin, aView, iPtr, iStatus );        // Bring view in front      SetActive();
    }  void CSampleViewActivator::RunL()     {     ixSPViewServices.Close();
    } 
Related APIs
  • CActive
  • CSampleViewActivator
  • Close()
  • Open()
  • TPtr8
  • aPlugin
  • aView
  • iPtr
  • iStatus

Example use case: getting xSP view related data

Getting xSP view related data synchronously requires a set of procedures: getting the total amount of xSP tab-views, asking for needed descriptor length, allocating buffer space and getting the view data in a descriptor form, and, finally, unpacking the data.

TInt count; TInt err = ixSPViewServices.GetViewCount(
count ); User::LeaveIfError( err ); for( TInt i = 0; i < count; i++ ) 
{  TInt bufferLength;   err = ixSPViewServices.GetPackedViewDataBufferLength(
i, bufferLength );   User::LeaveIfError( err );     if( bufferLength > 0 )      {
        HBufC8* packed = HBufC8::NewLC( bufferLength );       TPtr8 packedPtr = packed->Des();
        err = ixSPViewServices.GetPackedViewData( i, packedPtr );         User::LeaveIfError(
err );        CxSPViewData* viewData = CxSPViewData::NewL( *packed );        CleanupStack::PushL(
viewData );                // use view data here            CleanupStack::PopAndDestroy();
// viewData;      CleanupStack::PopAndDestroy(); // packed;       }    }

It is also possible to get xSP view related data asynchronously by using active objects and asynchronous versions of above described functions.

Error handling

Some of the methods leave in case of an error situation. Normal error handling practices 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
  • CxSPViewData
  • RxSPViewServices

Glossary

Abbreviations

Abbreviations

API Application programming interface

UID

Unique identifier

Definitions

Definitions

xSP extension

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

References

None.