freesmartphone.org dbus error specifications

[Michael 'Mickey' Lauer]

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:

========================================
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

========================================
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.

Cheers,

Mickey.
-- 
Dr. Michael 'Mickey' Lauer | IT-Freelancer | http://www.vanille-media.de