freesmartphone.org dbus error specifications

[Heikki Paajanen]

Hi Mickey,

some quick thoughts.

2008/5/12 Michael 'Mickey' Lauer <mickey at vanille-media.de>:
> Hi guys,
>
>  during the past days I put some thought into the biggest missing
>  thing in our API specs, which is the error specification.
>
>  DBus itself does hardly give any guidelines for error specifications --
>  all they really say is:
>   D-Bus remote exceptions have both a textual "name" and a "message".
>
>  This gives a lot of freedom to the designer, which is why we need
>  to come up with a sane solution right from the start. I inspected
>  a couple of dbus APIs and here's my proposal:
>
>  * All dbus remote exceptions from the freesmartphone project use
>  the following 'name' structure:
>
>  org.freesmartphone.<API>.[Interface].<Error>
>
>  * The 'message' structure gives clear-text details about the actual
>  error, but is as small and concise as possible.
>
>  Remarks:
>
>  0.) We do not need to encode 'Error', neither as prefix, nor suffix, nor
>  infix.
>  This would be redundant.
>
>  1.) We use a nested namespace rather than a flat one, this enables
>  fast prefix-matching, so a client might only look for the errors relevant
>  to it.
>
>  2.) [Interface] is optional, there might be small APIs (e.g.
>  org.freesmartphone.Usage or org.freesmartphone.Event)
>  where we do not have an interface category.
>
>  3.) <Error> does not need to be unique, e.g. you could have
>  org.freesmartphone.GSM.Device.NotPresent (which means the actual
>  modem is not present) and
>  org.freesmartphone.GSM.SIM.NotPresent (which means the actual SIM
>  card is not present). In fact, we try to reuse terms here
>  to keep the taxonomy managable and have a clear semantics.
>
>  Exceptions vary, some are very generic, some are specific to
>  an interface, or even a method. With regards to OTAPI (our
>  biggest API right now), I propose the following names and
>  meanings for the four interfaces that I consider (almost) v1.0:

I like the proposal. This structure is also quite close what dbus-glib
bindings give us by default and what we have been using already
with gsmd2.

>
>  ========================================
>  org.freesmartphone.GSM.Device
>  ========================================
>  org.freesmartphone.GSM.Device.NotPresent: the (modem) device is not present
>  org.freesmartphone.GSM.Device.Timeout: the (modem) device did not answer
>  within the expected time
>  org.freesmartphone.GSM.Device.Failed: the (modem) device did return an
>  unspecific error
>
>  ========================================
>  org.freesmartphone.GSM.SIM
>  ========================================
>  org.freesmartphone.GSM.SIM.NotPresent: the SIM card is not present
>  org.freesmartphone.GSM.SIM.Unauthorized: the operation is not authorized (i.e.
>  PIN required)
>  org.freesmartphone.GSM.SIM.NotFound: the requested entity on the SIM card
>  could not be found (i.e. subscriber number, phonebook or message entry)
>  org.freesmartphone.GSM.SIM.MemoryFull: the requested entity could not be
>  stored on the SIM card

What about something like:
org.freesmartphone.GSM.SIM.AuthFailed: PIN code is not accepted
org.freesmartphone.GSM.SIM.AuthFailed: SIM is locked. PUK code is required

>
>  ========================================
>  org.freesmartphone.GSM.Network
>  ========================================
>  org.freesmartphone.GSM.Network.NotPresent: there's no operator present
>  org.freesmartphone.GSM.Network.Unauthorized: the operation is not authorized
>  (i.e. register to a specific provider)
>  org.freesmartphone.GSM.Network.NotFound: the requested entity (i.e. operator
>  or country code) could not be found
>
>  ========================================
>  org.freesmartphone.GSM.Call
>  ========================================
>  org.freesmartphone.GSM.Call.NotFound: the requested entity (call index) could
>  not be found
>  [for sure i'm missing some here, but i need to implement more of that API to
>  understand which one ;)]
>
>  Does that make sense to you? What did I miss, what is superflous?
>  Depending on your comments, I would start adding these errors to
>  the XML specifications over the next days.

So the interface used and the interface in the error may be different,
e.g. all timeouts
are reported as org.freesmartphone.GSM.Device.Timeout, right? We have always
matched the interfaces and only changed the error part, but I think
allowing them
them to differ is better.

I think that at least some kind of internal error code is also needed ;)

Have you thought whether it is mandatory to fully implement all APIs?
If it's not
then some kind of "unsupported" error might be useful too.

   Hessu

>
>  Cheers,
>
>  Mickey.
>  --
>  Dr. Michael 'Mickey' Lauer | IT-Freelancer | http://www.vanille-media.de
>
>  _______________________________________________
>  smartphones-standards mailing list
>  smartphones-standards at linuxtogo.org
>  http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/smartphones-standards
>