The codebase for telepathy-ring 2.0.0

Telepathy-ring is now licensed under the LGPL (see COPYING for
details) and ported over to Ofono backend.

At the initial stage, the features of the 2.x.x series are not
on par with the previous 1.x.x series.

1 files changed, 161 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..4f5595f
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,161 @@
+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)