SIM Toolkit API proposals v2

[Yoshi Huang]

Hi
I would like to re-initiate proposals to SIM Toolkit API,
but this time only focus on interface first.
And hope can get some feedbacks from you guys.

There is one good diagram from Android which illustrates how STK works [1]
It's basically like message passing,

SIM initiates a command( Proactive command, precisely),
then ME(Moble Equipment, or the mobile phone) replies a response
(Terminal Response) to SIM.
When SIM receives this response, it notifies ME "Session End" to
indicate this SIM session has been finished
(see [1] for more examples)
Below I replace SIM as more general term "ICC".

The Proactive Command initiated from ICC has several types, most common
ones are
- Showing Menu
- Showing Text
- Get User Input
etc.

And ME can respond accordingly, like
- To reply which item has been selected by user
- User Input(text)

So basically the interface should be like:

ICC -> ME
/**
* The 'stkmessage' event is notified whenever STK Proactive Command is
* issued from ICC.
*/
attribute nsIDOMEventListener onstkmessage;

/**
* 'stksessionend' event is notified whenever STK Session is
terminated by
* ICC.
*/
attribute nsIDOMEventListener onstksessionend;

Note that in onstkmessage, it contains a parameter which is STK
Proactive command.


ME -> ICC
/**
* Send the response back to ICC after an attempt to execute STK
Proactive
* Command.
*/
void sendStkResponse(in nsIDOMMozStkResponse response);


For the detailed data structure of message I'll consolidate later.
Any suggestions/comments are appreciated. :)

Thank you.

[1]: http://www.kandroid.org/online-pdk/guide/stk.html

--
Yoshi Huang, Mozilla Taiwan
yhu...@mozilla.com

[Philipp von Weitershausen]

Hi Yoshi, thanks for bringing this up again. Do you have interface
specs for nsIDOMMozStkResponse as well as the event that is passed to
'onstkmessage'?

> _______________________________________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-webapi

[Yoshi Huang]

On 06/07/2012 02:54 AM, Philipp von Weitershausen wrote:
> Hi Yoshi, thanks for bringing this up again. Do you have interface
> specs for nsIDOMMozStkResponse as well as the event that is passed to
> 'onstkmessage'?
>

Yes, I just don't want to post too many things at one time to distract
people,
as my last time did.

I shall start explaining nsIDOMMozStkCommand, since it's issued by ICC
first.
The name StkCommand is named following the "Proactive Command" from spec.
It means this command is initiated by ICC.
nsIDOMMozStkCommand will be the parameter in onstkmessage.

(PS. Or if you think commmand/message/event will confuse you, I will try
to choose a unique one.)

interface nsIDOMMozStkCommand
{
/**
* The detail information of the proactive command issued by ICC.
*/
readonly attribute nsIDOMMozStkCmdDetails cmdDetails;

/**
* One of nsIDOMMozStkCmd*Param.
*/
readonly attribute nsIDOMMozStkCmdParameter param;
};

You could see the diagram in TS 11.14(GSM) Annex D or
TS 102.223(For UICC) Annex C for the structure of STK commands.

Each proactive command consists of several chunks, or Simple TLV
But it must contain one "Command Details" Simple-TLV (TS 11.14, clause 12.6)
The remaining Simple TLVs should be used according to this "Command Details"

For example.
A Proactive Command "SET_UP_MENU" is the first proactive command to set
up the STK menu.
It usually consists of
- Command Details TLV : type is SET_UP_MENU
- Alpha ID TLV --> should be used as Menu title
- Item TLV-> should be used as 1st Item
- Item TLV -> should be used as 2nd item

And its UI should look like:
-------------
| Title |
-------------
| Item 1 |
-------------
| Item 2 |
-------------

In this case, in nsIDOMMozStkCommand

cmdDetails will be the "Command Details" TLV.

and param should contain the remaining TLVs:
- Alpha ID TLV
- Item 1 TLV
- Item 2 TLV
They will be assembled to be a StkMenu, which is wrapped into a
StkCmdParameter

interface nsIDOMMozStkMenu
{
// items[], title, etc
};

interface nsIDOMMozStkCmdSelectItemParam : nsIDOMMozStkCmdParameter
{
readonly attribute nsIDOMMozStkMenu menu;
};


Next I'll explain StkResponse briefly.
nsIDOMMozStkResponse is the message sent from ME to ICC
The name StkResponse is named following the term "Terminal Response"
from spec.

interface nsIDOMMozStkResponse
{
/**
* The detail information of the proactive command issued by ICC.
*/
readonly attribute nsIDOMMozStkCmdDetails cmdDetails;

/**
* One of STK_RESULT_*.
*/
attribute unsigned short resultCode;

/**
* The identifier of the menu item selected by user.
*/
attribute unsigned short menuSelection;

/**
* User input.
*/
attribute DOMString input;

/**
* YES/NO response.
*
* @see TS 11.14, clause 12.6, Command Qualifier, GET INKEY, bit 3.
*
* true: User selects 'Yes'.
* false: User selects 'No'.
*/
attribute boolean yesNo;

/**
* User has accepted or rejected the call during STK_CMD_CALL_SET_UP.
*
* @see RIL_REQUEST_STK_HANDLE_CALL_SETUP_REQUESTED_FROM_SIM
*
* true: Confirmed by User.
* false: Rejected by User.
*/
attribute boolean confirmation;
};

This response is used to handle many kinds of proactive commands,
like SET_UP_MENU, SELECT_ITEM, GET_INPUT, ... etc
So each attribute has its own purpose to be interpreted by ICC.

Noted here the cmdDetails value in StkResponse should be the same with
corresponding StkCommand.
So ICC won't be confused by multiple Proactive commands.


Once you got a more clear understanding about STK, I will post the WebIDL
But it will be long, as you can see my first STK proposal last week , it
contains many data structures.
Or maybe I'll consider post it in Bugzilla.

Again, thanks for your comments

[Philipp von Weitershausen]

Yoshi, thanks for the detailed answer, and apologies for the late reply.

I'm only slowly getting up to speed with how the STK works, but here
are a few questions/points:

* How would I initialize a session / send an envelope command to the
STK? Can you provide some (fictional) example code of how the API
could be used in an app?

* Why do we expose sendStkResponse() for sending a terminal response?
This seems like something that Gecko should do on behalf of the
application. Consider two applications consuming STK events... which
one would get to send the terminal response? -- I think it would make
more sense to hide that from applications.

I would also recommend we start collecting the interface, use cases,
and code samples on the wiki. I created this page:
https://wiki.mozilla.org/WebAPI/WebSTK

[Yoshi Huang]

Hi philikon

my comments inline ,

On 06/15/2012 09:46 AM, Philipp von Weitershausen wrote:
> Yoshi, thanks for the detailed answer, and apologies for the late reply.

Never mind, I know you're busy :)
Also I post the proposal here to see if anyone has any opinion on it.

> I'm only slowly getting up to speed with how the STK works, but here
> are a few questions/points:
>
> * How would I initialize a session / send an envelope command to the
> STK? Can you provide some (fictional) example code of how the API
> could be used in an app?

The most common example would be the user "Selects an item"
See the diagram "Menu Session - Display Text" in
http://www.kandroid.org/online-pdk/guide/stk.html

the sample code will be

// get a MozStkCommand from SIM, said we store it in 'command'.
// I use MozStkCommand as argument because we need to copy the 'Command
Details' in MozStkCommand
var response = new MozStkResponse(command);

response.resultCode = STK_RESULT_OK;
response.menuSelection = 1234; // identifier of the menu item

mobileConnection.sendStkResponse(response);

I post the IDL of MozStkResponse here for reference

interface nsIDOMMozStkResponse : nsIDOMMozStkConstants

> * Why do we expose sendStkResponse() for sending a terminal response?
> This seems like something that Gecko should do on behalf of the
> application.

Yes, for some terminal response, Gecko can do it on behalf of the app.
For example, in the example diagram I show you above
"Menu Session - Display Text" in
http://www.kandroid.org/online-pdk/guide/stk.html
The Message "TERMINAL RESPONSE - OK" sent from Telephony to RIL (the 3rd
message from top)
can be done inside Gecko.

Actually,
sendStkResponse serves two purpose
- send Terminal Response (For other result code, like item-selection,
helpRequired, terminated by user...)
- send Envelope Command(for Menu Selection)

If the proactive command is interactive, (i.e. need user response/input)
sendStkResponse can be used by the app to send user's response.

> Consider two applications consuming STK events... which
> one would get to send the terminal response? -- I think it would make
> more sense to hide that from applications.

Two STK apps?
In STK, the STK applcation itelf is stored inside SIM, not in the
ME(Mobile Equipment),
ME just helps to display the UI and interacts with SIM according to STK
spec,
(For example, if you check the source of Stk.apk from Android, much its
code is for handling UI)

If you got a simcard with STK service enabled (check USIM Service Table)
when your phone boots up you should see a STK App installed,
and if you remove the simcard and reboot again, you should see the STK
app is disappear.

Or if you mean multi-SIM, (which you said we don't have to do this in v1)
in each STK proactive command/ Stk Response,
there is a TLV called 'Device ID"
And this TLV will contains the information that where is this message
from (i.e. SIM1, or SIM2)
and where this message to (i.e. ME)

> I would also recommend we start collecting the interface, use cases,
> and code samples on the wiki. I created this page:
> https://wiki.mozilla.org/WebAPI/WebSTK
>

Yeah I'll add more document on it,
thanks for this information.

[Philipp von Weitershausen]

On Thu, Jun 14, 2012 at 11:37 PM, Yoshi Huang <yhu...@mozilla.com> wrote:
>> I'm only slowly getting up to speed with how the STK works, but here
>> are a few questions/points:
>>
>> * How would I initialize a session / send an envelope command to the
>> STK? Can you provide some (fictional) example code of how the API
>> could be used in an app?
>
> The most common example would be the user "Selects an item"
> See the diagram "Menu Session - Display Text" in
> http://www.kandroid.org/online-pdk/guide/stk.html
>
> the sample code will be
>
> // get a MozStkCommand from SIM, said we store it in 'command'.
> // I use MozStkCommand as argument because we need to copy the 'Command
> Details' in MozStkCommand
> var response = new MozStkResponse(command);
>
> response.resultCode = STK_RESULT_OK;

That would probably be

response.STK_RESULT_OK;

because we can't just expose constants like these to the global
namespace. Alternatively, we could just use strings.

> response.menuSelection = 1234; // identifier of the menu item
>
> mobileConnection.sendStkResponse(response);

Aha! Thank you. However, as you point out, this example only covers
one line out of the "Menu Session - Display Text" interaction. Can you
spell out the entire interaction please? I think that will help me and
others to understand how that API would be used from beginning to end.
Thanks!

>> * Why do we expose sendStkResponse() for sending a terminal response?
>> This seems like something that Gecko should do on behalf of the
>> application.
>
> Yes, for some terminal response, Gecko can do it on behalf of the app.
> For example, in the example diagram I show you above
> "Menu Session - Display Text" in
> http://www.kandroid.org/online-pdk/guide/stk.html
> The Message "TERMINAL RESPONSE - OK" sent from Telephony to RIL (the 3rd
> message from top)
> can be done inside Gecko.
>
> Actually,
> sendStkResponse serves two purpose
> - send Terminal Response (For other result code, like item-selection,
> helpRequired, terminated by user...)
> - send Envelope Command(for Menu Selection)

Ah! Should we make two different methods for these, perhaps? Or do
they work exactly the same?

> If the proactive command is interactive, (i.e. need user response/input)
> sendStkResponse can be used by the app to send user's response.

Right.

>> Consider two applications consuming STK events... which
>> one would get to send the terminal response? -- I think it would make
>> more sense to hide that from applications.
>
> Two STK apps?

Sorry, two *web* apps.

>> I would also recommend we start collecting the interface, use cases,
>> and code samples on the wiki. I created this page:
>> https://wiki.mozilla.org/WebAPI/WebSTK
>>
> Yeah I'll add more document on it,
> thanks for this information.

Thanks!

[Yoshi Huang]

On 06/16/2012 08:08 AM, Philipp von Weitershausen wrote:
> That would probably be response.STK_RESULT_OK; because we can't just
> expose constants like these to the global namespace. Alternatively, we
> could just use strings.

Okay, I'll revise the IDL again.

>> response.menuSelection = 1234; // identifier of the menu item
>>
>> mobileConnection.sendStkResponse(response);
> Aha! Thank you. However, as you point out, this example only covers
> one line out of the "Menu Session - Display Text" interaction. Can you
> spell out the entire interaction please? I think that will help me and
> others to understand how that API would be used from beginning to end.
> Thanks

Okay, will add more on wiki

>> Actually,
>> sendStkResponse serves two purpose
>> - send Terminal Response (For other result code, like item-selection,
>> helpRequired, terminated by user...)
>> - send Envelope Command(for Menu Selection)
>> Ah! Should we make two different methods for these, perhaps? Or do
>> they work exactly the same?

Yeah,
But I think these two methods are just sending message back to SIM
So I just unify them as sendStkResponse.
And make the message (MozStkResponse) more flexible can be fitted
in these two methods.
So in the data fields of MozStkResponse
some are for Terminal Response(CommadDetails, ResultCode)
some are for Envelope (like menuSelection)

>
>>> Consider two applications consuming STK events... which
>>> one would get to send the terminal response? -- I think it would make
>>> more sense to hide that from applications.
>> Two STK apps?
> Sorry, two *web* apps.
>

Can you elaborate more about this?
For example, if two web apps use Telephony API, when the incoming call comes
Which webapp can get this call?

To me I think STK web app is like a system level app
(like dialer)
But I am not sure when there are multiple system level web apps,
what should happened?


Thanks for your comments
I'll continue to update the wiki and let you know

thanks

[Philipp von Weitershausen]

On Sat, Jun 16, 2012 at 6:39 AM, Yoshi Huang <yhu...@mozilla.com> wrote:
>>> Actually,
>>> sendStkResponse serves two purpose
>>> - send Terminal Response (For other result code, like item-selection,
>>> helpRequired, terminated by user...)
>>> - send Envelope Command(for Menu Selection)
>>> Ah! Should we make two different methods for these, perhaps? Or do
>>> they work exactly the same?
>
> Yeah,
> But I think these two methods are just sending message back to SIM
> So I just unify them as sendStkResponse.
> And make the message (MozStkResponse) more flexible can be fitted
> in these two methods.
> So in the data fields of MozStkResponse
> some are for Terminal Response(CommadDetails, ResultCode)
> some are for Envelope (like menuSelection)

Maybe just {send|Moz}StkMessage? Response implies that there is
something that it's responding to, which is not always the case.

>>>> Consider two applications consuming STK events... which
>>>> one would get to send the terminal response? -- I think it would make
>>>> more sense to hide that from applications.
>>>
>>> Two STK apps?
>>
>> Sorry, two *web* apps.
>>
> Can you elaborate more about this?
> For example, if two web apps use Telephony API, when the incoming call comes
> Which webapp can get this call?

Both webapps.

> To me I think STK web app is like a system level app
> (like dialer)
> But I am not sure when there are multiple system level web apps,
> what should happened?

I think we have a couple of options:

(a) we explicitly limit access to one specific web app. That seems
unnecessarily restrictive to me, and it's hard to predict which app(s)
want to use the API.

(b) we make sure that the API can handle being used from multiple apps
simultaneously. I don't think this too hard, but I haven't thought too
hard about all the edge cases yet. In case there's some problem, we
could do (c).

(c) a webapp has to acquire an API "lock" that locks out other web
apps from using the API during that time, to ensure all STK control
only goes to one app.

[Yoshi Huang]

On 06/19/2012 04:17 AM, Philipp von Weitershausen wrote:
> Maybe just {send|Moz}StkMessage? Response implies that there is
> something that it's responding to, which is not always the case.

Okay I got your point.
Originally I think the most common usage for envelope command is
Menu_Selection
(others cases are rare and even Android doesn't support them, like event
download, mms)
which needs a Item identifier, and a boolean to request for Help
and this message format can be reused by the Terminal Response of Select
Item
so I try to simplify the API and make it just sendStkResponse, without
adding another interface for envelope command.

But your argument is right,
But I'll prefer to keep MozStkResponse/sendStkResponse because they are
mainly used to reply Proactive Command.

And I'll try to add another interface for sending Envelope Command

>
> I think we have a couple of options:
>
>

> (b) we make sure that the API can handle being used from multiple apps
> simultaneously. I don't think this too hard, but I haven't thought too
> hard about all the edge cases yet. In case there's some problem, we
> could do (c).
>

You mean like System Message Handler , Bug 755245?

thanks

[Yoshi Huang]

Hi Philikon,

Thanks for your suggestion.
I've added another interface for Envelope command,
But currently only support "Menu Selection"
so the interface will be sendMenuSelection

I've updated the wiki for more detailed information
https://wiki.mozilla.org/WebAPI/WebSTK

Would you kindly help to take a look and give me some comments about it ?

thanks

On 06/19/2012 04:34 PM, Yoshi Huang wrote:
> On 06/19/2012 04:17 AM, Philipp von Weitershausen wrote:
>> Maybe just {send|Moz}StkMessage? Response implies that there is
>> something that it's responding to, which is not always the case.
> Okay I got your point.
> Originally I think the most common usage for envelope command is
> Menu_Selection
> (others cases are rare and even Android doesn't support them, like
> event download, mms)
> which needs a Item identifier, and a boolean to request for Help
> and this message format can be reused by the Terminal Response of
> Select Item
> so I try to simplify the API and make it just sendStkResponse, without
> adding another interface for envelope command.
>
> But your argument is right,
> But I'll prefer to keep MozStkResponse/sendStkResponse because they
> are mainly used to reply Proactive Command.
>
> And I'll try to add another interface for sending Envelope Command

[Yoshi Huang]

Hi Philikon

I have updated the IDL and add more documentation on Wiki
https://wiki.mozilla.org/WebAPI/WebSTK

Can you help to review that give me some comments?

[Philipp von Weitershausen]

Hi Yoshi,

sorry for the delay. Thanks for adding all the examples and detailed
interface descriptions! It looks great. I only have a couple of
points:

* I'm not sure we want to put this functionality under
MobileConnection. With the SIM locks and now the STK, I think we might
want to create a SIM-centric web API, e.g. navigator.mozIcc?

* Regarding your "TODO: add deviceId for multi-SIM" comment: let's
ignore multi SIM support for now. I'm not sure what it will look like
and how we will be able to support it. Definitely not a blocker.

* Is there a technical reason for nsIDOMMozStkCommand being split up
into two objects, nsIDOMMozStkCmdDetails and nsIDOMMozStkCmdParameter?
I think the API would be much simpler and easier to use if we just
inlined both of those interfaces into nsIDOMMozStkCommand.

Let me know if you need any help with the implementation. It's a big
API, perhaps we can parallelize.

Thanks
Philipp

[Yoshi Huang]

Hi philikon

Thanks for your quick review.
my comments inline,

On 06/25/2012 08:53 PM, Philipp von Weitershausen wrote:
>
> * I'm not sure we want to put this functionality under
> MobileConnection. With the SIM locks and now the STK, I think we might
> want to create a SIM-centric web API, e.g. navigator.mozIcc?

okay, I start with MobileConnection just try to make ICC stuff together.
I'll try to add it into a SIM-centric API,
but should it be mozICC?

> * Regarding your "TODO: add deviceId for multi-SIM" comment: let's
> ignore multi SIM support for now. I'm not sure what it will look like
> and how we will be able to support it. Definitely not a blocker.

okay, just add TODO there in case I forgot.

> * Is there a technical reason for nsIDOMMozStkCommand being split up
> into two objects, nsIDOMMozStkCmdDetails and nsIDOMMozStkCmdParameter?
> I think the API would be much simpler and easier to use if we just
> inlined both of those interfaces into nsIDOMMozStkCommand.

No particular technical reason,
just 'Command Details' is the common elements in proactive command
and it's mandatory,
others are optional and vary according to the type of command

Also when we need to construct MozStkResponse( Terminal Response)
The 'Command Details' data object needs to be consistent with
MozStkCommand(Proactive Command)
So when we construct the response, we also need to provide 'Command Details'
as argument

But I will try to simplify this and update the Wiki according to your
suggestions.

> Let me know if you need any help with the implementation. It's a big
> API, perhaps we can parallelize.

okay,
once the IDL is reviewed, I'll upload my patches and show
what I've done and what needs to done

I'll update the API and wiki and try to see if I can make the API simpler ,
will let you know once I finish that
(maybe next week or later this week due to new assignment in work week)

Thanks for your suggestions

[Philipp von Weitershausen]

On Mon, Jun 25, 2012 at 2:08 PM, Yoshi Huang <yhu...@mozilla.com> wrote:
>> * I'm not sure we want to put this functionality under
>> MobileConnection. With the SIM locks and now the STK, I think we might
>> want to create a SIM-centric web API, e.g. navigator.mozIcc?
>
> okay, I start with MobileConnection just try to make ICC stuff together.
> I'll try to add it into a SIM-centric API,
> but should it be mozICC?

Well, it's mozSms, so I think mozIcc would be appropriate. Eventually
it would be just 'icc', hopefully.

> Also when we need to construct MozStkResponse( Terminal Response)
> The 'Command Details' data object needs to be consistent with
> MozStkCommand(Proactive Command)
> So when we construct the response, we also need to provide 'Command Details'
> as argument

Ah, that's what I missed. Well, given that all the stuff in
nsIDOMMozStkCmdParameter is optional, I think we could still collapse
the three interfaces to just nsIDOMMozStkCommand.

[Yoshi Huang]

On 06/25/2012 11:40 PM, Philipp von Weitershausen wrote:
> Ah, that's what I missed. Well, given that all the stuff in
> nsIDOMMozStkCmdParameter is optional, I think we could still collapse
> the three interfaces to just nsIDOMMozStkCommand.

Hi , philikon
I just updated the wiki according to your suggestion.
https://wiki.mozilla.org/WebAPI/WebSTK

This time I updated :
* move to mozIcc(MozIccManager).
* collapse nsIDOMMozStkCommandDetails nsIDOMStkCmdParameter into
nsIDOMMozStkCommand
* move constants into MozStkCommand and MozStkResponse.
* update some naming convention.
* update examples accordingly.

can you review that again and give me some comments?

Thanks

[Philipp von Weitershausen]

On Thu, Jun 28, 2012 at 9:01 AM, Yoshi Huang <yhu...@mozilla.com> wrote:
> I just updated the wiki according to your suggestion.
> https://wiki.mozilla.org/WebAPI/WebSTK

Thanks! THis looks great! Can you upload a patch to the bug and flag
Jonas for superreview? Thanks!