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.
Related APIs
MCCAConnectionMCCAParameterTCCAFactory
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
KErrAlreadyExistsKErrArgumentKErrNotFoundLaunchApplicationL/LaunchAppLMCCAConnectionMCCAParameterSetContactDataL
Limitations of the API
None.
Related APIs
KErrArgumentKErrNotFoundMCCAObserverMCCAParameterMVPbkContactLinkPackLCSetContactDataLTCCAFactoryTDesCiConnection