sysapps / telephony Goto Github PK

There is a typo in the WebIDL where TelephonyManager's serviceIds and defaultServiceIds attributes have one too many ";"

The spec's markup is no valid HTML5, which is upsetting my text editor's ability to auto close tags, etc.

tone is defined as a "byte" that "Indicates the DTMF tone. Its value can be any sequence of the following characters (0-9; A-D; *; #)."

In WebIDL, a byte is: "a signed integer type that has values in the range [−128, 127]."

So, A-D, "*", and "#" don't fit :)

The spec should be evaluated for potential uses of Promises. There are a number of places where Events are being used to deliver Errors async, where a future would be more appropriate.

We need to define a kind of join method that allows to join the active call to the current held conference call

The following text is out of place:

The following specifications have been used for designing the Telephony API: for GSM the [GSM-CALL] suite, for IMS/SIP the [IMS] suite, for XMPP the XEP 0166 specification.

Should be moved to the introduction.

The following text should be moved to the telephonyManager section:

"While multiple telephony services may be used for making calls, received calls from all telephony services are handled through this object, since all calls are competing for the same resources, and arbitration is needed."

It's possible to check if a TelephonyCall is a conference call by doing an instanceof check:

if (someObject instanceof ConferenceCall){
   ...
}

hence I don't think we need "readonly attribute boolean conference".

The security considerations need to be more detailed - i.e., explain why the API can only be used with trusted content.

For TelephonyManager's readonly attribute Call[] calls, the spec says:

When getting, the user agent MUST return an array containing zero or more Call objects managed by this object. Note that TelephonyCall objects belonging to a multiparty call are managed by the corresponding ConferenceCall object and MUST NOT be also present in this array.

It's not clear from the above how a Call became "managed" by the TelephonyManager. That is, with respect from differentiation with ConferenceCall objects that are not in the list.

Implement the modifications raised on the F2F:

• join() without parameters, meaning: "join all calls on the same telephony service"
• move the named state change handlers (e.g. ondialing, ondisconnected, etc.) to where they belong to: TelephonyCall and ConferenceCall
• remove 'addParticipant' and 'removeParticipant' in this phase
• make sure it works with CDMA 3-way calling.

Need to add the following reference for DTMF:
http://www.itu.int/rec/T-REC-Q.23/en

The spec states in a few places:

If the provided parameters are invalid, throw an InvalidStateError error

This should really be a TypeError. However, invalid attribute types and values are handled automagically via WebIDL, so this can be removed.

What's the standard format for a telephony service id? I.e., what do they look like as a string? Is there some standard that defines them?

There does not seem to be any reason for TelephonyManager to have [NoInterfaceObject].

Because the network can update the emergency numbers dynamically (as can changing physical location), should there be some kind of event for that?

There are places in the spec where events are being generated and then queued, but no particular task queue is specified. We need to check if we can hook into existing task queues or if we need to define a new one.

it is a general audio manager issue for the device, not really specific for telephony even if telephony needs it quite a lot.

Would be nice if the spec had a link to the bug tracker.

The following text should be moved to the TelephonyCall section:

A TelephonyCall object can be created only by using the dial() method, or when there is a new incoming or waiting call. There is only one way a ConferenceCall object can be created: using the join() method on a TelephonyCall object."

Also, drop the following from the paragraph:

All these methods will be discussed in more detail in this document.

The spec is somewhat inconsistant about getting and setting attributes. It would be nicer if when getting an attribute, the spec said "When getting, the user agent MUST bla bla". Same for attributes that can be set. This would integrate the spec more nicely with WebIDL's algorithms.

So we don't get |any params| but something that is more specific like "TelephonyCall call".

There needs to be a reference that specifies how to hide a caller's id (i.e., magic tones that need to be generated before dialing). Or which spec defines that.

The spec currently has a hard link. Need to convert to citation:

<a href='http://xmpp.org/extensions/xep-0166.html'>XEP 0166</a>

http://www.w3.org/2012/sysapps/telephony/

The spec states:

When making a call, the identity (e.g. SIM card, associated to an Integrated Circuit Card Identifier, ICC-ID) must always be specified, either explicitly in the function call, or by using a default telephony service in the implementation. The device may receive phone calls from any active telephony service, even simultaneously, in which case the calls must be arbitrated either by the implementation based on a policy, or by the user by choosing which call to accept. A telephony service may use different protocols for telephony signaling and media (e.g. GSM, CDMA, VoLTE, etc.) with the same identity. Since call states may differ depending on the protocol, the telephony call objects must contain information which identifies the service and the protocol used for making the call.

The definition should avoid conformance requirements. Put the conformance requirements in the algorithms.

The value of state attribute for a call should be defined as an enum, not a DOMString.

The TelephonyManager current has:

attribute DOMString defaultServiceId

Implying that the defaultServiceId can be set. However, it does not define the rules for setting (can I set it to any string?). What happens if it's not a valid service id? etc.

This should be set to readonly till we figure out the way to do it properly.

The use of a "readonly attribute DOMError error" on an *Manager doesn't seem like a good construct. Errors should only result from operations or from an event (i.e., shouldn't be part of an manager interface).

I recommend we remove "readonly attribute DOMError error" and make sure that errors go to error handlers or are thrown as exceptions if sync (or are handled by a Future, if we end up using those).

I'm confused as to why there are TelephoneCalls and ConferenceCalls? Can't they be merged into a single object?

The following text is not longer needed:

Any CallHandler object MUST be either a TelephonyCall or a ConferenceCall.

It is redundant anyhow, as it's the interfaces that define this.

To align with other boolean properties in the platform which almost never uses the 'is' prefix.

Events should not have [NoInterfaceObject], so they can appear in the global scope.

The spec currently has:

interface TelephonyEvent : EventTarget
interface TelephonyServiceEvent : EventTarget

But these should be extending Event, not EventTarget.

The SoTD is missing WIP text warning implementers that the spec can change from under them in incompatible ways.

CallHandler is superfluous in the spec at the moment, as it's used by two interfaces that don't actually need to inherit it. It is superfluous is that it cannot be used on it's own, so it's really just an abstract base class.

To fix this, we have two options:

1. copy/paste everything from CallHandler to the inheriting interfaces (this will bloat the spec a bit).
2. Keep the current design, but instead of inheriting from CallHandler, make TelephoneCall and Conference Call "implement" CallHandler.

In 2. All that needs to change in the spec is:

interface TelephonyCall {
 ... all the same...
}
TelephonyCall implements CallHandler; 

interface ConferenceCall {
 ... all the same...
}
ConferenceCall implements CallHandler;

Then, CallHandler can remain a [NoInterfaceObject].

hideCallerId should be a boolean, that when missing uses the system default. That gives you the three states, with only using a boolean.

The spec states:

The call is is locked in a ConferenceCall object and MUST NOT be managed any more using this object. While in this state, the implementation MUST throw an ILLEGAL_STATE exception when any method call is attempted.

This needs to be stated in the methods themselves, not in the definition of the state.

The spec contains a table that redefines some of the error semantics from the DOM spec. This should be avoided (even if they fit). If the current definitions in the DOM spec are not sufficient, we should enhance them in the DOM spec, not in this spec.

I recommend we remove this.

The current spec contains a whole bunch of stuff that has been commented out, which makes the spec difficult to edit. Why not delete each comment as a commit? then we have a record that we can search if we want to bring anything back.

If it's ok, I would like to remove the unnecessary comments as described above.

For where "If not specified, the implementation MUST provide a default value" appears, the specification should provide recommended values.

This includes ToneParams:

• duration
• gap

(there may be others)

CallHandler should be in its own section.

The spec says:

If there is any error during the method calls which is not handled by exceptions, the following steps MUST be run:

This should be avoided. There should be no situation defined in which this happens - and if there is, it should be addressed within this spec or in future revisions of this specification.