api property notification order

api property notification order

[Jussi Kukkonen]

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

Hi,

I'm wondering if there could be some additional promises made by the
API about the order of certain property changes and method call
returns. I realize what I'm talking about is fairly close to an API
change so it's more like a discussion starter than a ready suggestion.

The exact problem I ran into is that property changes that are a
result of a API method call are notified _after_ the method call
returns. From an API user point of view that is wrong. As an example I
thought this would be a fairly logical way to handle PIN resets:
  * property change SimManager.PinRequired="puk" -> show pin reset UI to user
  * user enters PUK and new PIN -> call SimManager.PinReset()
  * wait for method to return, present any errors. In particular
org.ofono.Error.Failed:
    "It looks like you entered the wrong PUK. You can try again X more
times before the SIM is permanently locked"
Doing that will mislead the user really badly as the Retries-property
hasn't been decreased yet...

From my point of view the order of events should be:
 1. properties that are less likely to trigger UI actions themselves
(e.g. "Retries", "ServiceNumbers")
 2. properties that can be expected to trigger UI actions themselves
(e.g. "PinRequired")
 3. method call returns
The distinction between 1 and 2 is sugar coating but unless method
calls return after property changes, UI development will be more
complex than I thought.

Jussi

Re: api property notification order

[Denis Kenzior]

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

Hi Jussi,

On 01/03/2012 03:55 AM, Jussi Kukkonen wrote:
> Hi,
> 
> I'm wondering if there could be some additional promises made by the
> API about the order of certain property changes and method call
> returns. I realize what I'm talking about is fairly close to an API
> change so it's more like a discussion starter than a ready suggestion.
> 
> The exact problem I ran into is that property changes that are a
> result of a API method call are notified _after_ the method call

In general most operations that affect a single property are implemented
as 'method return, then signal' semantics.  However, there are a few
exceptions and oFono really does not make any guarantees on the order.
The reason this was chosen is that it tends to work a bit nicer with
certain D-Bus bindings than the alternative.  Other than the
aforementioned reason, I do not believe there is a fundamental advantage
to one order or the other in such cases, but I'd love to hear any
arguments arguing otherwise from a UI-writer perspective.

> returns. From an API user point of view that is wrong. As an example I
> thought this would be a fairly logical way to handle PIN resets:
>   * property change SimManager.PinRequired="puk" -> show pin reset UI to user
>   * user enters PUK and new PIN -> call SimManager.PinReset()
>   * wait for method to return, present any errors. In particular
> org.ofono.Error.Failed:
>     "It looks like you entered the wrong PUK. You can try again X more
> times before the SIM is permanently locked"
> Doing that will mislead the user really badly as the Retries-property
> hasn't been decreased yet...
> 

Ah, but the problem here is really not the ordering.  The problem is
that this is a fairly complicated transaction, requiring several calls
to the driver and affecting several attributes at once. Not only do the
pin retries have to be checked, but also what the new PIN required is or
whether the SIM is blocked forever. e.g. you might actually have run out
of PUK retries and blocked your SIM forever.  To add additional
complexity, not all modem drivers support querying pin retries, or we
simply do not have the AT command details available...

What is happening here is that the method return is generated purely on
the success / failure of the pin reset operation, not

> From my point of view the order of events should be:
>  1. properties that are less likely to trigger UI actions themselves
> (e.g. "Retries", "ServiceNumbers")
>  2. properties that can be expected to trigger UI actions themselves
> (e.g. "PinRequired")
>  3. method call returns
> The distinction between 1 and 2 is sugar coating but unless method
> calls return after property changes, UI development will be more
> complex than I thought.
> 

In general I'm open to the idea of querying pin retries and pin type
before returning from PIN/PUK related method calls.  However, this
probably needs to be studied a bit more carefully for feasibility and
impact.

Regards,
-Denis

Re: api property notification order

[Jussi Kukkonen]

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

Hi, thanks for a comprehensive answer.

On Mon, Jan 2, 2012 at 2:14 AM, Denis Kenzior <denkenz@gmail.com> wrote:
  [...clip...]
>> returns. From an API user point of view that is wrong. As an example I
>> thought this would be a fairly logical way to handle PIN resets:
>>   * property change SimManager.PinRequired="puk" -> show pin reset UI to user
>>   * user enters PUK and new PIN -> call SimManager.PinReset()
>>   * wait for method to return, present any errors. In particular
>> org.ofono.Error.Failed:
>>     "It looks like you entered the wrong PUK. You can try again X more
>> times before the SIM is permanently locked"
>> Doing that will mislead the user really badly as the Retries-property
>> hasn't been decreased yet...
>>
>
> Ah, but the problem here is really not the ordering.  The problem is
> that this is a fairly complicated transaction, requiring several calls
> to the driver and affecting several attributes at once. Not only do the
> pin retries have to be checked, but also what the new PIN required is or
> whether the SIM is blocked forever. e.g. you might actually have run out
> of PUK retries and blocked your SIM forever.  To add additional
> complexity, not all modem drivers support querying pin retries, or we
> simply do not have the AT command details available...
>
> What is happening here is that the method return is generated purely on
> the success / failure of the pin reset operation, not

Ah, I see. I did take a look at the code but missed this. I was afraid
you might have reasons for it...

From a software 'completeness' POV I should just make my UI messages
change as the situation in ofono changes, but I dislike that for two
reasons: First, it makes the whole thing a lot more complex, and
second, changing UI messages is just bad design: I'd rather wait until
the 'side effects' like retry-counts are all there and then show the
message. I realise I can never be 100% sure that things won't change
but I'm mostly interested in the 99.9% cases.

It looks like I don't really have an alternative though -- I think
I'll delay the message creation by a very short time so the retry
count is correct in most cases and add state handling for the message
content to cover the 0.x%.

> In general I'm open to the idea of querying pin retries and pin type
> before returning from PIN/PUK related method calls.  However, this
> probably needs to be studied a bit more carefully for feasibility and
> impact.

That sounds good to me.

Jussi