Purpose

CCA Launch API provides an interface to a thin library running in the client content to launch a Contact Centric Application as an embedded application.

Constraints

This API is valid for all platforms running on S60 5.1 or later.

Classification and release information

This API is a Domain API and was first published in S60 release 5.1. This document is valid from S60 release 5.1 onwards.

Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

API description

Contact Centric Application (CCA) provides a way to handle all contact specific tasks with one uniform user interface. Contact Centric Application is mainly just a framework for view plug-ins which performs operations and specified tasks for a contact. The application is launched from all places where the action is targeted to the contact. Such places are, for example, to open it from Phonebook names list to perform an action to a selected contact. Contact Centric Application is not only for contacts that are found in the local contact store.

Clients can control the launching of Contact Centric Application with the API in various ways: the most important issue is to provide data for identifying the contact that is selected to be used. This can be done by using Virtual Phonebook contact links and contact IDs or the phone number of the contact. The CCA Launch API does not check the validity of given contacts, e.g., the validity of a given phone number. By giving the UID of the plug-in implementation, the user of the API can control which view plug-in is launched on screen first by the Contact Centric Application.

Use cases

  • Launching Contact Centric Application with ContactLink.

  • Launching Contact Centric Application with ContactId.

  • Launching Contact Centric Application with phone number.

  • Launching Contact Centric Application to selected plug-in view.

  • Launching Contact Centric Application with observer callback.

API class structure

The CCA Launch API consists of the interface classes MCCAConnection and MCCAParameter. Client instantiates these interfaces with the help of a single factory class TCCAFactory. After instantiation, the client can set the required data of the used contact to the parameter object. The actual launching of the application is done by giving the parameter to a launching method of the connection object. Ownerships of MCCAConnection and MCCAParameter objects are transferred to clients.

CCA Launch API concept


CCA Launch API concept

Related APIs
  • MCCAConnection
  • MCCAParameter
  • TCCAFactory

Using the CCA Launch API

Clients need to import ccaclient.lib in their project make files. After that including the API headers ccafactory.h, mccaconnection.h and mccaparameter.h is necessary.

Note, the actual launching of the embedded Contact Centric Application is done by using the AppServer architecture and this crosses over the thread boundary.

The following is an example on how to use CCA Launch API as class members. There are also examples about possible scenarios related to example code lines.

In class declaration:

Class MCCAConnection;
MCCAConnection* iConnection;

In class implementation:

#include<ccafactory.h>
#include<mccaparameter.h>
#include<mccaconnection.h>

Using of the API is started by instantiating parameter and connection classes with the help of TCCAFactory static methods.

MCCAConnection* parameter = TCCAFactory::NewParameterL()
CleanupClosePushL( *parameter );
iConnection = TCCAFactory::NewConnectionL()

MCCAParameter is used to store and define how Contact Centric Application is launched. Mainly, this means defining the contact data which is wanted to be launched on Contact Centric Application. First the client has to define the type of contact data and connection. This is done by using enumerations. Here, the contact data is set to be the Virtual Phonebook contact ID.

parameter->SetConnectionFlag(ENormal);
parameter->SetContactDataFlag(EContactId);

Next step is to set the actual data of the contact which identifies contact for Contact Centric Application. If data flag of the contact is not set, the SetContactDataL method leaves with KErrNotFound. The API is designed for enabling multiple ways to set the contact data, therefore SetContactDataL takes TDesC as parameter.

parameter->SetContactDataL(aIdString);

After this, there are the Virtual Phonebook contact links ( MVPbkContactLink) used for launching. This is the recommended way to launch the Contact Centric Application, if possible. Note, because the CCA Launch API uses the AppServer framework, links have to be packed with thePackLC method before setting this method.

parameter->SetConnectionFlag(ENormal);

MVPbkContactLink* link = GetContactLink()->CloneLC();
HBufC* packed = link->PackLC();

parameter->SetContactDataFlag(EContactLink);
parameter->SetContactDataL(packed);

CleanupStack::PopAndDestroy(packed);
CleanupStack::PopAndDestroy(link);

It is also possible to launch Contact Centric Application with a contact's phone number:

parameter->SetConnectionFlag(ENormal);
parameter->SetContactDataFlag(EContactMSISDN);
parameter->SetContactDataL(_L("+123123"));

If there is a need to launch Contact Centric Application for a particular plug-in view, it can be done by entering the UID of the plug-in:

parameter->SetLaunchedViewUid(aUid);

Now the parameter object is ready for launching. Launching is done by setting the parameter object as parameter for connection object launching method. Launching of Contact Centric Application is synchronous but when the application is launched the control is given back to client. Note, if the contact data is not set, this method leaves with KErrArgument.

iConnection->LaunchAppL( *parameter );
CleanupStack::Pop();//parameter is on iConnection's responsibility

Other way of launching is to utilize the MCCAObserver observer callback.

// Inherit the observer-class
class CMyClass : public MCCAObserver
  {
  ...
  public:
  void CCASimpleNotifyL( TNotifyType aType, TInt aReason );
  ...

// Give pointer to your observer-class during the launch
iConnection->LaunchApplicationL( *parameter, this );
CleanupStack::Pop();//parameter is on iConnection's responsibility
// Implement the needed functionality
void CMyClass::CCASimpleNotifyL( TNotifyType aType, TInt aReason )
  {
  // your implementation
  }

Clearing the CCA Launch API object is recommended to be called when client's application exits, or it can be also done when iConnection has notified application exit through the MCCAObserver observer interface.

iConnection->Close();

Error handling

LaunchApplicationL/LaunchAppL of MCCAConnection leaves with KErrArgument if the given parameter does not have any contact data. LaunchApplicationL/LaunchAppL of MCCAConnection leaves with KErrAlreadyExists if more than one simultaneous application launches are started per one MCCAConnection instance. Setting the contact data method SetContactDataL on MCCAParameter leaves KErrNotFound if the contact data flag is not set as the specified type of data. These are the only special error cases of CCA Client API. Using of LaunchApplicationL/LaunchAppL can cause leaves from the AppServer framework side when launching the Contact Centric Application. As usual, the clients have to take care of all normal system wide errors, e.g. low memory situation.

Related APIs
  • KErrAlreadyExists
  • KErrArgument
  • KErrNotFound
  • LaunchApplicationL/LaunchAppL
  • MCCAConnection
  • MCCAParameter
  • SetContactDataL

Memory overhead

None.

Limitations of the API

None.

Related APIs
  • KErrArgument
  • KErrNotFound
  • MCCAObserver
  • MCCAParameter
  • MVPbkContactLink
  • PackLC
  • SetContactDataL
  • TCCAFactory
  • TDesC
  • iConnection

Glossary

Abbreviations

API Application Programming Interface

CCA

Contact Centric Application

UID

Unique Identifier

UI

User Interface

Definitions

Contact Centric Application Application framework with plug-ins to manipulate contact specified operations.

Phonebook, Names list

Main view of the Phonebook application.

AppServer Framework

Allows launching of embedded applications.

Virtual Phonebook

Library for handling contact storages.

Contact data

Data used to identify the contact. Can be contact links, contact ID or phone number of contact.