consider using telephony service objects

[zolkis]

Consider using explicit telephony service objects, exposing functionality specific to a service (SIM).
Connected to #203, #125, #128.
For the proposal, see:
https://etherpad.mozilla.org/O0KQaiKEhN

[hsinyi]

Hi there,

Discussion mozilla had before:

[1] is the very original proposal from my side that looks similar to Zoltan's proposal for using telephony service objects
[2] and [3] are Jonas' reply to [1] and the reasons that we chose dial() with serviceId

[1] https://groups.google.com/forum/#!searchin/mozilla.dev.webapi/multi-sim/mozilla.dev.webapi/ZmFvU47eSvA/qbhQVF18mNwJ
[2] https://groups.google.com/d/msg/mozilla.dev.webapi/1tPzEIftZ24/dbx68uGpkkkJ
[3] irc discussion: Search "hsinyi" and you will find the records. http://logbot.glob.com.au/?c=mozilla%23b2g&s=16+Mar+2013&e=23+Mar+2013

Thanks!

[hsinyi]

Mozilla's IccManager API: http://mxr.mozilla.org/mozilla-central/source/dom/icc/interfaces/

[zolkis]

On one hand, there is the wish to have a simple API that can handle most of the developer use cases, on the other hand the API should be correctly aligned with how telephony works.

The developer use case is mainly writing a dialer. So the target developers are not in the range of millions, but rather in tens or hundreds, most likely familiar with telephony. It is a good goal to lower the threshold for writing a dialer, but the app developer still needs to understand basic concepts of telephony.

There are multiple domains of abstractions in Telephony:

• the telephony network, with all standards, interoperability, etc, including PSTN, cellular and IP telephony
• telephony modems and their AT command sets, providing an abstraction to the network
• telephony middleware, providing an abstraction to the telephony modems, or to IP telephony stacks
• web telephony API, trying to cut corners and be simple to use, while not losing much of the power.

Arguably the best abstraction of the telephony domain for GSM and CDMA is provided by the oFono project:
http://git.kernel.org/cgit/network/ofono/ofono.git/tree/doc
In particular, watch how developers are supposed to track:

• modems (getting online/offline etc): http://git.kernel.org/cgit/network/ofono/ofono.git/tree/doc/manager-api.txt
• interfaces provided by modems: http://git.kernel.org/cgit/network/ofono/ofono.git/tree/doc/modem-api.txt
  In particular, pay attention to the array{string} Interfaces [readonly] method: it enlists objects which are present and usable on a given modem. VoiceCallManager is one of those interfaces, but there are others, too, e.g. NetworkRegistration, SimManager, SupplementaryServices, etc.
  This abstraction is exemplary both in faithfulness to telephony standards and simplicity of use. It does not handle IP telephony, but the concept is easy to extend.

This proposal takes the modem abstraction and generalizes it into a TelephonyService object.
A given device can make phone calls in the following ways:

• built-in modem and SIM1
• built-in modem and SIM2, ...
• through the modem of a device connected via Bluetooth (HFP/ hands-free gateway functionality)
• through IP telephony stacks (SIP, XMPP, skype on signaling, WebRTC, skype etc. on media plane)
• through web services.

Some of the problems a generic telephony API faces:

• differences between protocols (e.g. CDMA vs GSM in call state management, conference calls, etc)
• different interfaces present on different modems vs different telephony protocols
• extensibility of the API vs future changes.
  For some of the problems encountered in this API, see [1].

The approach taken by Mozilla seems to be the following:

• take one use case (voice call management) and assume every dependency is provided and is working (otherwise go on an error path)
• add new interfaces as problems are met on the go (e.g. multiple SIM support done through IccManager).
  This approach lacks proper design and it is subject to break easier, for a simpler API.

However, having a simple API is a good goal. On the F2F there was agreement that

• TelephonyService objects are a good way to solve differences between telephony protocols
• it can represent a variable set of interfaces present on some modems/services.

A TelephonyService object defines the minimal number of properties needed:

• subscriber identity
• provider identity
• a display name
• generic methods (dial, sending tones, etc)
• and optional properties (objects) representing interfaces such as SIM toolkit or network.

In order to maintain a simple interface for developers who don't care about different telephony services (e.g. multiple SIM support), the API could be kept simple by defining the navigator.telephony object as the default TelephonyService object, and having a separate TelephonyManager interface for exposing the more complex functionality. See these changes on: https://etherpad.mozilla.org/O0KQaiKEhN

However, since this API is meant for dialer developers, I argue that the target audience of this API should definitely be interested in the full functionality of this API. Differences may be in what telephony services are going to be supported by the various apps, but not much differences elsewhere. If this is true, the previous revision of the API may also be good enough:
https://etherpad.mozilla.org/ep/pad/view/O0KQaiKEhN/Zf2VbFCaQM

---

[1]
Related issues: #204 #137 #53 #124 #21, #83
Notes on CDMA 3-way calling:
zolkis@cdc3590

[zolkis]

See also https://groups.google.com/d/msg/mozilla.dev.webapi/1tPzEIftZ24/ZLdOQfpDLBIJ

[zolkis]

See also #208 . During prototyping for that use case it turned out that using serviceId's made it easier to handle/implement /arbitrary call merges using the ConferenceCall object, and therefore it is the better choice for dial() type of methods. However, TelephonyService objects are needed for handling other cellular interfaces than call management, and for supporting various modem types. These concepts are implemented in https://rawgithub.com/sysapps/telephony/gh-pages/index2.html .