V 0.1.1
Kate Alhola
kate.alhola@nokia.com
Basic concepts
Connection Manager
Connection Manager implements certain protocol towards network service and offers Tepelathy Dbus API to system. As example in Maemo 5, there is connection manager named Cabble handling Googletalk's XMPP protocol, Ring for cellular telephony, Sofia for SIP VoIP telephony, Spirit for Skype. You can add new protocols by just adding new connection managers, as example you can add Idle connection manager for IRC. If you would like to implement new you need to write new connection manager to support it and for Maemo 5 you need also control panel plugin to set up account.
Account
Account defines your service provider, your user name in that service, your authentication crentials and other protocol dependent parameters like server address, port, used encryption.
Account Manager
Account Manager maintains data base of your accounts and keeps track their status. As example, you will be logged in mobile telephone network when device is switched on and online. You may also set that you are logged in you GoogleTalk and Skype accounts when device is online. To establish connection to service client application should require your account from account manager.
Client applications
Application that uses services provided by Telepathy connection managers. As example chat client or phone user interface are telepathy clients. If you implement application that sends your current GPS location to your friend with instant message or SMS, it could be telepathy client.
Service Provider
Ad example your mobile operator or GoogleTalk or Skype service. It can be even your own IRC server.
Connection
To be able to use services provided by service provider, connection manager should establish connection with it. To set up connection client application should provide all needed details to connection manager, as example network address of the server, your login name and password. In case of account manager, client application will get account details from AM. If your account is set to be automatically connected, there may be also connection already established and client application should only retrieve it from AM. It is not technically mandatory to use accounts provided by AM and it is possible set up own connection with own details if needed. In most of cases this is not recommended because it may confuse users and spoil their user experience. In cellular, there is only default connection and you need require it from CM
Channel
Channel is communication stream between you client application and your peer. It can be audio or multimedia call, chat connection, instant message connection or file transfer. Channel may go directly from you local connection manager to peer's system or it may go via service providers server but to clint application it looks like just connection between client and peer. To set up channel your client should provide contact address, as example username or telephone number of your peer and request connection from connection manager.
It is possible to use as example Googletalk connection manager without using services provided by mission control if you provide account details yourself but then you are not working with same account than device user has specified for his/her use as default. For user experience, using account provided by mission control is goof idea. In cellular, it is not possible to have multiple simultaneous cellular accounts and therefore using mission control is mandatory.
Telepathy communication protocols are implemented in connection managers that are communicating using Dbus with user applications. In most cases it is not sense to use directly dbus API for user applications. There couple of Telepathy interface libraries providing API classes to user application and implementing Dbus messaging. In this example we use Telepathy-Qt4 library that is providing Qt API. There is also Glib style telepathy-glib API library.
Telepathy is based on communication over Dbus with connection managers running as separate processes. Many actions need communication with server or with peer over external network. Operations with telepathy are asynchronous as nature even function call returns immediately, actual result comes much later as form of Qt signal or callback in some other platforms. Most of actions implemented with telepathy needs multiple asynchronous steps and some kind of state machine functionality.
Using Telepathy via API library still needs deep understanding how telepathy works and coding is challenging task. In this example I provide simplified easy API layer as example code.
For future applications best solution would be to use services via Qt-Mobility libraries. With Qt mobility we can get cross platform compatibility also to non-telepathy and non-Linux environments ,as example for Series 60
Telpathy works with synchronous interface. That mean's that all actions are initiated by function call and signal is emitted when action is complete. User application should then implement state machine logic that based on slots called by signals, progress to next state and initiate successive actions. The positive thing in synchronous model is that it dies nit hang user interface in any cases even if completing operation takes time.
TpSession hides part of this complexity. Many actions implements multiple state transitions before they return signal of completed operation. TpSession implements synchronous mode in some operations, as example in class initialization where is multiple short transitions over Dbus. When initialization is called with synchronous mode, call returns after all transitions are done and completing signal is received.
TpSession API library is at the moment experimental proof of concept library top of Telepathy-Qt4. It's main intention is to provide simplified API for most common services provided by telepathy, It does not try to provide any kind of data abstraction or hide Telepathy-Qt4 API inside of it. Basic functionality can be accessed without using any of complicated Telepathy-Qt4 API's but if application needs some more advanced features, they can freely access Telepathy-Qt4 classes inside of TpSession Classes.
Minimum that your application needs to send SMS or Instant message is instance of TpSession class with prefered connection manager “ring” specified and synchronous mode specified in in constructor
TpSession* tps =new TpSession("ring",true);
tps->sendMessageToAddress("ring",”+555666777”,”Telepathy session is for you”);
If you would also receive messages, you need to connect one slot handler for sending for received message.
connect(tps,SIGNAL(messageReceived(const Tp::ReceivedMessage &,TpSessionAccount *)),
SLOT(onMessageReceived(const Tp::ReceivedMessage &,TpSessionAccount *)));
....
void TestProg::onMessageReceived(const Tp::ReceivedMessage &msg,TpSessionAccount *acc)
{
qDebug() << "MessageReceived " << msg.text() << "from " << msg.sender()->id();
}
You will find full example code from tests/syncsms directory
If you would like to get indication of incoming phone call, yuou chould listen new Channels signals from your connection manager , TpSessionAccount .
TpSessionAccount* tpsa=tps->getAccount(“Ring”);
connect(tpsa,SIGNAL(newChannel(TpSessionAccount *,Qstring,QString,const Tp::ChannelDetails)),
SLOT(onNewChannels(TpSessionAccount *,Qstring,QString,const Tp::ChannelDetails)));
Testprog::onNewChannels(TpSessionAccount *tpsa,Qstring channelType,QString peerId,const Tp::ChannelDetails)
{
qDebug() << “Incoming call type “ << channelType << “from “ << peerId;
}
Top level class, counterpart of Account Manager. TpSession connects to account manager and requests accounts from it. TpSession creates TpSessionAccount for all accounts . As top level class TpSession provides simplified interface to send and receive messages via any account. TpSession provides signal when it has accounts ready. If you require some specific account in constructor, you will receive signal only when this account is ready. If you use constructor without any parameters, you will get one signal for every account. If synchronous is true, constructor is executed as synchronous and it does return after transactions to set up accounts are done.
TpSessionAccount class represents every account you have. As example account for “Ring” connection manager represents your cellular account and you may send and receive SMS with it. Gabble represents your GoogleTalk account if you have defined them. TpSessionAccounts are created by TpSession class,they are not intended to be created stand-alone
When you start chat session or call with your buddy, channel is established with your buddy. TpSessionChannel represents this connection. TpSession account makes automatically channel when you send message to your buddy's address. If you send successive messages to same buddy with TpSessionAccount, it automatically reuses existing connection.
----- The next one describes internal operation of TpSession ----
This describes, how my API library works. If you just plan use it as it is, you don't need
look it in deep as details. If you plan implement function by your own code then understanding all functionality is necessary.
First step, we need to establish connection with Mission control.
mAM = Tp::AccountManager::create();
Mission Control emits signal when connection with account manager is created, it also emits signal later if new accounts are created.
connect(mAM->becomeReady(),SIGNAL(finished(Tp::PendingOperation *)),
SLOT(onAMReady(Tp::PendingOperation *)));
connect(mAM.data(),SIGNAL(accountCreated(const QString &)),
SLOT(onAccountCreated(const QString &)));
When we have connection with Account Manager, we have Dbus paths available to account. Dbus path itself contains as part, several properties like connection manager used, protocol and user name in service if needed.
To get more details of we need to request accounts creating Tp::AcountPtr object. When this object becomes ready, it emits finished signal. When we receive signal, we can get actual account
Tp::account * acc = mAcc.data();
Now, when we have actual account, we can ask several properties from account.
More to come .....