W3C home > Mailing lists > Public > public-sysapps@w3.org > November 2012

Re: Telephony API draft updated

From: Jonas Sicking <jonas@sicking.cc>
Date: Thu, 29 Nov 2012 21:33:51 -0800
Message-ID: <CA+c2ei9hT529+1fVyafA4qcah4pms97_XBVj-tiEBoUwjFsg5Q@mail.gmail.com>
To: "Kis, Zoltan" <zoltan.kis@intel.com>
Cc: EDUARDO FULLEA CARRERA <efc@tid.es>, "public-sysapps@w3.org" <public-sysapps@w3.org>
On Fri, Nov 23, 2012 at 1:24 AM, Kis, Zoltan <zoltan.kis@intel.com> wrote:
> Hello,
>
> On Mon, Nov 19, 2012 at 12:35 PM, EDUARDO FULLEA CARRERA <efc@tid.es> wrote:
>> Hi,
>>
>> Please note that an update version of the Telephony API proposal has been uploaded:
>> http://sysapps.github.com/sysapps/proposals/Telephony/Telephony.html
>>
>> This version incorporate feedback received on the first draft, mainly (may not be comprehensive):
>> -removing record functionality
>> -Changes in the states: removing 'error' and 'busy', adding 'accepted' and 'waiting'
>> -Adding two state diagrams for inbound and outbound calls.
>> -An issue note has been created indicating that it needs to be decided whether the state transitions (both in diagrams and textual description) are normative or not, as there is no consensus among the editors
>
> Before taking up that discussion, I would like to raise a new issue
> perhaps easier to agree upon.
>
> Since telephony user experience of today is consistent with it, I
> think it would make sense to have the HW related call controls (audio,
> mike, ...) in the context of a telephone call, rather than on the main
> telephony interface (where it gives the impression of a system
> interface, irrespective of whether is there a telephony service
> available or any call in progress - whereas it is should be just a
> facade to these system controls from the context of a call).
>
> Therefore I propose moving these controls to a separate interface, and
> include it in TelephonyCall.  The WebIDL would become the following:
>
> [NoInterfaceObject]
> interface Telephony : EventTarget {
>     readonly attribute DOMString[]     ownTelNumbers;
>     readonly attribute DOMString[]     emergencyNumbers;
>     readonly attribute TelephonyCall   active;
>     readonly attribute TelephonyCall[] calls;
>     TelephonyCall dial (DOMString number, DialParams params);
>     void          startTone (DOMString tone);
>     void          stopTone ();
>     void          sendTone (DOMString tone);
>              attribute EventHandler    onincoming;
>              attribute EventHandler    oncallschanged;
> };
>
> [NoInterfaceObject]
> interface TelephonyMediaControl {
>     attribute boolean          speakerEnabled;
>     attribute boolean          headsetEnabled;
>     attribute double            audioVolume;
>     attribute boolean          audioMuted;
>     attribute double            micVolume;
>     attribute boolean          micMuted;
>     /**
>      * examples for future extension (remove me)
>      * attribute boolean          frontCameraEnabled;
>      * attribute boolean          backCameraEnabled;
>      * attribute boolean          sendingLocalVideoEnabled;
>      * attribute boolean          receivingRemoteVideoEnabled;
>      */
> }
>
> [NoInterfaceObject]
> interface TelephonyCall : EventTarget {
>     readonly attribute TelephonyMediaControl controls;
>     readonly attribute DOMString    number;
>     readonly attribute DOMString    state;
>     readonly attribute DOMError     error;
>     readonly attribute DOMString?   reason;
>     void answer ();
>     void disconnect ();
>     void hold ();
>     void resume ();
>     void redirect (DOMString redirectNumber);
>              attribute EventHandler onstatechange;
>              attribute EventHandler ondialing;
>              attribute EventHandler onalerting;
>              attribute EventHandler onaccepted;
>              attribute EventHandler onconnecting;
>              attribute EventHandler onconnected;
>              attribute EventHandler ondisconnecting;
>              attribute EventHandler ondisconnected;
>              attribute EventHandler onholding;
>              attribute EventHandler onheld;
>              attribute EventHandler onresuming;
>              attribute EventHandler onredirecting;
>              attribute EventHandler onerror;
> };

I don't think this change is a good idea.

I agree that using the API before a call is started makes no changes
that are visible to the user or possibly even to hardware. However
that doesn't mean that it doesn't make sense to have the API on the
Telephony object.

Consider for example the element.style.color API. This API allows
modifying the text-color that an element is rendered in. If an element
is removed from the document, the element is obviously not rendered at
all. If we were to apply the same argument as is used for the
telephony API, we shouldn't have an API like element.style.color since
in some situations the API doesn't have any effect that is visible to
the user.

However the element.style.color API is very popular with authors. Not
only because it is intuitive, I.e. the API to change an element is
located on the element itself, but also because in some cases changing
the color before an element is rendered makes the code flow for the
application simpler. I.e. it allows the application to modify the
color whenever you want. If that happens to not change something on
the screen until later, or even at all, that's ok.

The call volume is a orthogonal property to any given call. Imagine a
dialer UI which displays audio controls like "speaker" and "microphone
volume" at all times. It would certainly be possible for an
application to create such a UI even with the API proposed here. The
application would have to remember the state using application logic
and once a TelephonyCall object becomes available it would modify
those properties on that object right away. It would then switch the
application logic such that when the user interacts with the UI it
finds the closest TelephonyCall object and modifies that, rather than
modifying the internal application state.

However it seems much more intuitive to put the audio properties on
the Telephony interface. This way it's clear that the settings are
per-call but rather global for all telephony interactions. And the
application can always wire the UI directly up to API without having
to switch between using application state or the API depending on if a
TelephonyCall object happens to be connected. It also means that we
won't have to address complex edge cases such as what happens if
someone uses the API on a disconnected TelephonyCall object.

In short, we should focus on what creates a useable API. We shouldn't
focus on that the API has to map directly to hardware behavior. We
also shouldn't focus on creating the API that is as simple as possible
to implement. Application-author friendliness should be a higher
priority than implementor friendliness.

/ Jonas

https://wiki.mozilla.org/WebAPI/AudioChannels
Received on Friday, 30 November 2012 05:34:53 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 30 November 2012 05:34:53 GMT