path: root/HACKING

GENERAL
=======

Telepathy-Ring is a GSM connection manager that provides call and messaging
services through the standard Telepathy interfaces on the session bus.
Telepathy-Ring was originally written atop CSD, the Cellular Services Daemon
shipped on the Nokia N900. The current backend (work in progress...) is
Ofono <http://www.ofono.org>.


REQUIRED LIBRARIES
==================

Telepathy-Ring is based on telepathy-glib and rtcom-telepathy-glib. The latter
will, however, be made redundant soon enough when the ring-specific interfaces
hit upstream.

The unit testing framework of choice is 'check'.

There is a Python test script (tests/check-ring.py) based on python-telepathy,
python-dbus, and python-gobject.


CONNECTION MANAGER AND CONNECTION OBJECT
========================================

The connection manager itself can be found in "src/" subdirectory. Each
object is in a module of its own.

The connection object is based on TpBaseConnection and implements two
'requestotron'-supporting channel manager objects: RingMediaManager and
RingTextManager. It also supports the standard 'Contacts' and 'Capabilities'
interfaces. The extension interface 'Emergency' can be used to query
the known emergency numbers. The extension interface 'StoredMessages'
is used to expunge SMSes spooled on disk.

The GSM interface is used to access GSM-specific settings.


CONTACT HANDLES
===============

The RingConnection object manages the contact handles. The function
ring_normalize_name() in ring-connection.c processes contact handles, or
normalizes them. It gets called when a Telepathy client calls RequestHandles
in order to call or send an SMS, or when a call or an SMS is received from
network.

The contact handles can be phone numbers (e.g., "+12345556789"), emergency
call urns ("urn:service:sos"), or, strings of 11 UTF-8 characters (SMS
TP-Originator-Address in alphanumeric format).

Note that ring_normalize_name() strips away whitespace and commonly used
punctuation from phone numbers (i.e., "+1-(234)-555-6789" becomes
"+12345556789").

As it is not usually possible to get the phone number used by the handset
("MS ISDN") the self handle corresponds to a well-known string "<SelfHandle>".

The alphanumeric SMS addresses are used when an SMS is sent from a service
like 'My Nokia'. Please note that alphanumeric SMS addresses are SMSC-specific
and they can not be used to send SMSes.

Also note that any special handle, such as the self handle, must use
a representation that can not be normalized. Anything longer than 11 UTF-8
characters suffices, however, if it cannot be normalized as a phone number.


MEDIA CHANNELS
==============

RingMediaManager manages two kind of media channels, ordinary peer-to-peer
calls (RingCallChannel) and conferencing channels (RingConferenceChannel).
The StreamedMedia interface is implemented by RingMediaChannel, which is
used as a base object for these two.

The RingMediaChannel implements also Hold, DTMF and DialStrings interfaces.
Hold interface can be used to put call on hold. DTMF interface is used to
send DTMF digits, DialStrings interface dial strings with more automated
processing.

There are numerous additional channel interfaces required in addition to the
StreamedMedia. Group interface is used to accept and release calls. It is
implemented in quite different way in the RingCallChannel and
RingConferenceChannel, RingCallChannel is a peer-to-peer implementation and
RingConferenceChannel can have multiple participants.

The CallState interface is used to indicate various states, such as call
waiting or remote hold. The Emergency interface is used to handle emergency
calls and indicate that the given call has been given emergency priority.

The Conference, MergeableConference, and Splittable interfaces are used to control
conferences. Setting up a conference requires at least two participants.


TONE GENERATION
===============

The tone generator service is used to generate DTMF feedback tones and error
tones in case a call ends unexpectedly. The tone generation is driven by
RingMediaChannel class. Currently only RingCallChannels are using the tone
generation.

The error tones are generated while the call is in 'released' state
until the call enters the 'terminated' state. The tone generation is
suppressed while the network generates the tone (user-connection).
If the network-generated tone is very short (less than half the nominal tone
duration usually determined by ring_call_channel_play_error_tone()),
the error tone is played by the tone generator service after the network closes
the speech traffic channel.


TEXT CHANNELS
=============

RingTextManager manages textual channels (sending and receiving SMSes).
The implementation supports o.f.T.Channel.Interface.Messages interface with
text/plain and text/x-vcard (vCard 2.1) media types. The text/x-calendar
(vCalendar 1.0) support is there, but it has not been enabled yet.

The SMSes are spooled on disk by the cellular backend, and they have to be
explicitly expunged by the client (after it has logged them securely). The
client should use the Connection.Interface.StoredMessages interface for this.

Text channels used to receive class 0 (flash SMSs) are a special case; it is
not possible to send on such a channel. Likewise, a channel created for
receiving an SMS with alphanumeric address cannot be sent on.


MODEM INTERFACE LIBRARY
=======================

Modem interface library found from "modem/" subdirectory is used to
communicate with the Ofono services over D-Bus. The library shields the
application from usual D-Bus-isms and tries to provide an ordinary
GObject-esque experience with it.

Note that only the minimal set of functionality used by Telepathy-Ring is
provided. The services supported are call (for making CS calls), sms (for
sending, receiving, and manipulating spooled SMSs) and sim (for accessing
some SIM information).


TESTING
=======

There is a Python script testing basic functionality (tests/check-ring.py)
and a shell script for setting up suitable test environment and running the
python script (tests/check-ring.sh).


FURTHER READING
===============

In addition to the Telepathy specifications, the following 3GPP documents
are useful when trying to understand how speech calls and short messages
work in GSM and UMTS:

* 3GPP TS 22.001, 24.008 (call signaling)
* 3GPP TS 24.011, 23,038, 23.040, 27.005 (SMS)
* 3GPP TS 11.11 (SIM)