STK DisplayText changes proposal

STK DisplayText changes proposal

[Lucas, GuillaumeX]

[-- Attachment #1: Type: text/plain, Size: 2368 bytes --]

Hi,

According to the 3GPP specifications there is some missing points in the SATK DisplayText implementation and I want to propose some API changes here.

1. clear message after delay / wait for user to clear flag

This flag corresponds to the bit 8 of the command qualifier (see ETSI TS 102 223) and indicates how the message should be cleared by the UI.
In the STK agent documentation it's indicated that this flag is handled using different timeout value for the Agent DisplayText method call. But that doesn't seem the case in the code: there is no check of the flag.

For me it's to the UI to handle the way how the message must be cleared and not to ofono. With the current Agent DisplayText method API this is not possible as there is no indication if the message must be cleared after a delay or after a user action. So I want to propose the following change for the STK Agent:

Change    void DisplayText(string text, byte icon_id, boolean urgent)
By        void DisplayText(string text, byte icon_id, boolean urgent, boolean clear_after_delay)

Where clear_after_delay boolean must be set to '1' for the clear message after delay case and to '0' for the wait for user to clear case.

2. Busy screen

The other missing point in the DisplayText implementation is the case of the busy screen.
According to the sequence 1.2 of the ETSI TS 102 384 we must return a terminal response with the error "screen busy" when the ME is not in the idle screen and if the text message is not urgent. In the current implementation there is no way to return this type of error in the terminal response.

I propose to add a new error code ScreenBusy in the same way of what it's done for GoBack and EndSession event.

Please let me know if you agree with it.

Regards,
Guillaume
---------------------------------------------------------------------
Intel Corporation SAS (French simplified joint stock company)
Registered headquarters: "Les Montalets"- 2, rue de Paris, 
92196 Meudon Cedex, France
Registration Number:  302 456 199 R.C.S. NANTERRE
Capital: 4,572,000 Euros

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.

Re: STK DisplayText changes proposal

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 2399 bytes --]

Hi Guillaume,

On 11/23/2010 09:33 AM, Lucas, GuillaumeX wrote:
> Hi,
> 
> According to the 3GPP specifications there is some missing points in the SATK DisplayText implementation and I want to propose some API changes here.
> 
> 1. clear message after delay / wait for user to clear flag
> 
> This flag corresponds to the bit 8 of the command qualifier (see ETSI TS 102 223) and indicates how the message should be cleared by the UI.
> In the STK agent documentation it's indicated that this flag is handled using different timeout value for the Agent DisplayText method call. But that doesn't seem the case in the code: there is no check of the flag.

Andrew has to answer this one, it seems like there's a disconnect
between the implementation and the docs.  Probably just a bug.

> 
> For me it's to the UI to handle the way how the message must be cleared and not to ofono. With the current Agent DisplayText method API this is not possible as there is no indication if the message must be cleared after a delay or after a user action. So I want to propose the following change for the STK Agent:
> 
> Change    void DisplayText(string text, byte icon_id, boolean urgent)
> By        void DisplayText(string text, byte icon_id, boolean urgent, boolean clear_after_delay)
> 
> Where clear_after_delay boolean must be set to '1' for the clear message after delay case and to '0' for the wait for user to clear case.

Actually I really don't want to make this distinction.  The UI should
always give the user the option to clear the message.  So just
increasing the timeout when wait_for_user flag is set seems enough to me.

> 
> 2. Busy screen
> 
> The other missing point in the DisplayText implementation is the case of the busy screen.
> According to the sequence 1.2 of the ETSI TS 102 384 we must return a terminal response with the error "screen busy" when the ME is not in the idle screen and if the text message is not urgent. In the current implementation there is no way to return this type of error in the terminal response.
> 
> I propose to add a new error code ScreenBusy in the same way of what it's done for GoBack and EndSession event.

I can be convinced that this is a good idea.  However, in 99% of the
cases the STK session is started by the user, so the screen should never
be 'busy'.

Andrew, what do you think?

Regards,
-Denis

Re: STK DisplayText changes proposal

[Andrzej Zaborowski]

[-- Attachment #1: Type: text/plain, Size: 1952 bytes --]

Hi,

On 23 November 2010 17:05, Denis Kenzior <denkenz@gmail.com> wrote:
> On 11/23/2010 09:33 AM, Lucas, GuillaumeX wrote:
>> Hi,
>>
>> According to the 3GPP specifications there is some missing points in the SATK DisplayText implementation and I want to propose some API changes here.
>>
>> 1. clear message after delay / wait for user to clear flag
>>
>> This flag corresponds to the bit 8 of the command qualifier (see ETSI TS 102 223) and indicates how the message should be cleared by the UI.
>> In the STK agent documentation it's indicated that this flag is handled using different timeout value for the Agent DisplayText method call. But that doesn't seem the case in the code: there is no check of the flag.
>
> Andrew has to answer this one, it seems like there's a disconnect
> between the implementation and the docs.  Probably just a bug.

It was in my first proposal, however the decision made here on the
list or on IRC (I don't remember) was to remove all the details from
the specification until there's a specific use case for them from UI
authors.  The current API is greatly simplified compared to TS 102.223
on the basis that some of the parameters are never used by SIM
manufacturers.  This includes for example the "help available"
information in the commands, the return values like "help requested",
"icon could not be displayed", "screen busy" and many other bits.  On
one hand this makes sense but on the other I don't see it as a huge
saving as long a we design the API in such a way that the unneeded
call parameters or return values can be ignored by the UI writer.  I
have to point out that you were the advocate for simplifying the API
to the minimum level needed to implement the iPhone STK app :)

As for the clear after delay flag, there's a check for it in
display_text_cb (line 1248).  As far as I can make out the only
difference is the response sent to the SIM.

Best regards

Re: STK DisplayText changes proposal

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 2391 bytes --]

Hi Andrew,

On 11/23/2010 10:55 AM, Andrzej Zaborowski wrote:
> Hi,
> 
> On 23 November 2010 17:05, Denis Kenzior <denkenz@gmail.com> wrote:
>> On 11/23/2010 09:33 AM, Lucas, GuillaumeX wrote:
>>> Hi,
>>>
>>> According to the 3GPP specifications there is some missing points in the SATK DisplayText implementation and I want to propose some API changes here.
>>>
>>> 1. clear message after delay / wait for user to clear flag
>>>
>>> This flag corresponds to the bit 8 of the command qualifier (see ETSI TS 102 223) and indicates how the message should be cleared by the UI.
>>> In the STK agent documentation it's indicated that this flag is handled using different timeout value for the Agent DisplayText method call. But that doesn't seem the case in the code: there is no check of the flag.
>>
>> Andrew has to answer this one, it seems like there's a disconnect
>> between the implementation and the docs.  Probably just a bug.
> 
> It was in my first proposal, however the decision made here on the
> list or on IRC (I don't remember) was to remove all the details from
> the specification until there's a specific use case for them from UI
> authors.  The current API is greatly simplified compared to TS 102.223
> on the basis that some of the parameters are never used by SIM
> manufacturers.  This includes for example the "help available"
> information in the commands, the return values like "help requested",
> "icon could not be displayed", "screen busy" and many other bits.  On

The help stuff is fully pointless, so we definitely won't be supporting
that one.

> one hand this makes sense but on the other I don't see it as a huge
> saving as long a we design the API in such a way that the unneeded
> call parameters or return values can be ignored by the UI writer.  I
> have to point out that you were the advocate for simplifying the API
> to the minimum level needed to implement the iPhone STK app :)

Oh I still am ;)

> 
> As for the clear after delay flag, there's a check for it in
> display_text_cb (line 1248).  As far as I can make out the only
> difference is the response sent to the SIM.

So it has been a long time since those discussions, but it does seem to
me that using a higher timeout in the case of 'wait_for_user' flag seems
like a good idea.  Do you remember why we left this out?

Regards,
-Denis

Re: STK DisplayText changes proposal

[Andrzej Zaborowski]

[-- Attachment #1: Type: text/plain, Size: 1140 bytes --]

On 23 November 2010 18:08, Denis Kenzior <denkenz@gmail.com> wrote:
> On 11/23/2010 10:55 AM, Andrzej Zaborowski wrote:
>> As for the clear after delay flag, there's a check for it in
>> display_text_cb (line 1248).  As far as I can make out the only
>> difference is the response sent to the SIM.
>
> So it has been a long time since those discussions, but it does seem to
> me that using a higher timeout in the case of 'wait_for_user' flag seems
> like a good idea.  Do you remember why we left this out?

No, I don't, I'll send a patch to use the normal timeout instead of
short timeout when clearing after user action is requested.  As for
the proposal to add a parameter clear_after_delay and the ScreenBusy
response I'm fine with both of them (as I don't think the saving from
hiding these details is worth it) but I leave it up to you and
Guillaume.  It seems that a user action always clears the message but
it may be good to display a "confirm" button anyway.  The ScreenBusy
response is also possible for other proactive commands so for
consistency would need to be added there too.

Best regards,
Andrew

RE: STK DisplayText changes proposal

[Lucas, GuillaumeX]

[-- Attachment #1: Type: text/plain, Size: 2090 bytes --]

Hi Andrew,

> 
> On 23 November 2010 18:08, Denis Kenzior <denkenz@gmail.com> wrote:
> > On 11/23/2010 10:55 AM, Andrzej Zaborowski wrote:
> >> As for the clear after delay flag, there's a check for it in
> >> display_text_cb (line 1248).  As far as I can make out the only
> >> difference is the response sent to the SIM.
> >
> > So it has been a long time since those discussions, but it does seem
> to
> > me that using a higher timeout in the case of 'wait_for_user' flag
> seems
> > like a good idea.  Do you remember why we left this out?
> 
> No, I don't, I'll send a patch to use the normal timeout instead of
> short timeout when clearing after user action is requested.  As for
> the proposal to add a parameter clear_after_delay and the ScreenBusy
> response I'm fine with both of them (as I don't think the saving from
> hiding these details is worth it) but I leave it up to you and
> Guillaume.  It seems that a user action always clears the message but
> it may be good to display a "confirm" button anyway.  The ScreenBusy
> response is also possible for other proactive commands so for
> consistency would need to be added there too.
> 

For the 'clear_after_delay' flag your patch to used the normal timeout and not the short when a user request is waiting will be probably sufficient for the moment. For the ScreenBusy response I'm agree with you that this response is also possible for other proactive commands. I'll do the necessary patch for this.

Regards,
Guillaume
---------------------------------------------------------------------
Intel Corporation SAS (French simplified joint stock company)
Registered headquarters: "Les Montalets"- 2, rue de Paris, 
92196 Meudon Cedex, France
Registration Number:  302 456 199 R.C.S. NANTERRE
Capital: 4,572,000 Euros

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.