[Telephony] streamline sendMMI(), cancelMMI() and dial()

[Hsin-Yi Tsai]

Hi there,

Due to the difficulties of parsing MMI code on gaia, we are working on |*Bug 1058398* <https://bugzilla.mozilla.org/show_bug.cgi?id=1058398> - [meta][B2G][Telephony] streamline mobileConnection.sendMMI(), mobileConnection.cancelMMI() and telephony.dial()| to provide full MMI support on gecko.
* The 1st goal is, gaia doesn't have to distinguish if a string is a call number or a MMI code. mozTelephony.dial() would do all the magic for API users.
More details:*Bug 889737* <https://bugzilla.mozilla.org/show_bug.cgi?id=889737> - [MMI] Unify both sendMMI() and dial() functions
* The 2nd one is,to provide a separate API for user to send data within a ussd session, becausewhen you are in a USSD session the rules of MMI don't apply to the data being exchanged in that session.
More details:*Bug 1058397* <https://bugzilla.mozilla.org/show_bug.cgi?id=1058397> - [B2G][Telephony] add UssdSession API

Thus, acceptance criteria are summarized as:
1a. use telephony to dial an MMI code in addition to a normal call number
1b. know the dialling number is an MMI code ASAP so that we could show a different UI
1c. know the response of that MMI code request
2. when receiving a ussd, could reply in that ussd session

== Proposal of Goal #1 ==
To achieve those criteria, we propose:
telephony.dial("some number here") will return a promise and there are 3 possible consequences:
1. rejected when error occur.
2. resolved as a TelephonyCall => it's a call
3. resolved as an DOMRequest => it's an MMI code request, and gecko is currently handle the request. When the request finishes, 'success' or 'error' event will be triggered on DOMRequest object.

In sum, the new API looks:

partial interface Telephony
{
Promise<(TelephonyCall or DOMRequest)> dial(DOMString number, optional unsigned long serviceId);
};
And, we don't need "MobileConnection::SendMMI" anymore.

== Proposal of Goal #2 ==
When user receives a ussdreceived event, user could reply in that session.

partial interface Telephony
{
attribute EventHandler onussdreceived;
};

interface USSDReceivedEvent : Event
{
readonly attribute unsingned long serviceId;
readonly attribute DOMString? message;
readonly attribute MozUssdSession? session;
};
USSDReceivedEvent::SessionEnded is removed because in the new API user could tell if the session is terminated from the nullable session. If session is null, that means it's ended.

interface MozUssdSession
{
DOMRequest send(DOMString ussd);
};
With the new design, "MobileConnection::Onussdreceived" is removed as well as MobileConnection::CancelMMI().
CancelMMI was designed for cancelling any existing ussd session when we init the dialer appto make sure we're not accidentally sending the data on an existing session.

If you are interested in the API change, welcome to visit bugzilla and join our discussion there! Thank you :)

Best regards,
Hsinyi


--
Hsin-Yi Tsai 蔡欣宜
Mozilla Taiwan
T: +886-2-87861100 ext:312
ht...@mozilla.com

[Ehsan Akhgari]

Having an API which resolves a Promise to a DOMRequest is very weird.
DOMRequest is basically our "promise-like" solution before Promises were
standardized. What is the actual thing that we dispatch success on the
DOMRequest on? We should just resolve the promise to that thing
directly, and not use a DOMRequest at all.

> == Proposal of Goal #2 ==
> When user receives a ussdreceived event, user could reply in that session.
>
> partial interface Telephony
> {
> attribute EventHandler onussdreceived;
> };
>
> interface USSDReceivedEvent : Event

You need to define an init dictionary and add a constructor to this
event type, similar to other event types.

> {
> readonly attribute unsingned long serviceId;
> readonly attribute DOMString? message;

When can message be null?

> readonly attribute MozUssdSession? session;

When can session be null?

> };
> USSDReceivedEvent::SessionEnded is removed because in the new API user
> could tell if the session is terminated from the nullable session. If
> session is null, that means it's ended.
>
> interface MozUssdSession

No "moz" prefixes, please.

> {
> DOMRequest send(DOMString ussd);
> };

Since you're starting to use promises in this API, can we return a
Promise here as well?

Also, a more general question about this event type. It seems like
you're using it as a way to allow the application to register itself to
receive USSD events. Do we care about these types of events which might
have been received inside the RIL code before there was an event
handler? Or do they just get dropped on the floor?

If we care to make such events accessible to the consumer of the API, a
better design would be a |Promise<UssdSession> getUSSDSession();| API so
that we can resolve a promise with a UssdSession representing a USSD
session that was initiated before getUSSDSession was called.

Also, can we have multiple versions of these USSD sessions in flight at
the same time?

Cheers,
Ehsan

[Szu-Yu Chen]

> > partial interface Telephony
> > {
> > Promise<(TelephonyCall or DOMRequest)> dial(DOMString number,
> > optional unsigned long serviceId);
> > };
> > And, we don't need "MobileConnection::SendMMI" anymore.
>
> Having an API which resolves a Promise to a DOMRequest is very weird.
> DOMRequest is basically our "promise-like" solution before Promises were
> standardized. What is the actual thing that we dispatch success on the
> DOMRequest on? We should just resolve the promise to that thing
> directly, and not use a DOMRequest at all.

We will dispatch an MMIResult to DOMRequest.onsuccess

dictionary MozMMIResult
{
DOMString serviceCode = "";
DOMString statusMessage = "";
(unsigned short or object) additionalInformation;
};

It may take some time for the network to process our MMI request and send back the result. If we decide to resolve the promise after we get the response, the promise will be pending there for a while. However, by returning the information we have (whether it is a call or MMI request), the api user could make UX more better, for example, showing that we are currently processing an MMI request. I remembered that this is a point that gaia concerned about.
Ref: https://bugzilla.mozilla.org/show_bug.cgi?id=889737#c29

> > == Proposal of Goal #2 ==
> > When user receives a ussdreceived event, user could reply in that session.
> >
> > partial interface Telephony
> > {
> > attribute EventHandler onussdreceived;
> > };
> >
> > interface USSDReceivedEvent : Event
>
> You need to define an init dictionary and add a constructor to this
> event type, similar to other event types.

Sure. Actually, USSDReceivedEvent is already existed in the code base. The modification here is introducing a new property, "session" and using session.send() to reply the message.

> > readonly attribute MozUssdSession? session;
>
> When can session be null?

When we receive an USSD message from the network. The message will indicate whether the session is ended or not. Then the user could reply the message if the session is alive.
So, in our interface, "session" is null when the network says that it's already ended. This make sense because we don't need to reply the message.

> > {
> > DOMRequest send(DOMString ussd);
> > };
>
> Since you're starting to use promises in this API, can we return a
> Promise here as well?

Yes.

> Also, can we have multiple versions of these USSD sessions in flight at
> the same time?

Only one session at a time.

> Cheers,
> Ehsan

Regards,
Szu-Yu Chen (Aknow)

[Gabriele Svelto]

Hi Szu-Yu,

On 09/09/2014 05:28, Szu-Yu Chen wrote:
> It may take some time for the network to process our MMI request and send back the result. If we decide to resolve the promise after we get the response, the promise will be pending there for a while. However, by returning the information we have (whether it is a call or MMI request), the api user could make UX more better, for example, showing that we are currently processing an MMI request.

Then instead of returning a DOMRequest why don't we return another
Promise? This would make chaining easier and would look more consistent
IMHO.

Gabriele

[Szu-Yu Chen]

Hi Gabriele,

> Then instead of returning a DOMRequest why don't we return another
> Promise? This would make chaining easier and would look more consistent
> IMHO.

I have no idea but it seems very strange for me. (promise resolves as promise???)
How could we state it in the api? Will it be something like this?

Promise<(TelephonyCall or Promise<MMIResult>)> dial(...)

If this is possible and more reasonable from the view of API design, I could implement it in this way.

Best regards,
Aknow
--
Szu-Yu Chen (Aknow) 陳思佑
Mozilla Taiwan