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 . 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 "". 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)