error handling in GStreamer

[Thomas Vander Stichele <thomas apestaart org>]

(I'm forwarding this to gnome-desktop-devel to get more feedback from possible
application developers and because some people have varying opinions on where
GError should go from here)

We've started working on proper i18n'd error handling in GStreamer. 
We're still unclear about some of the issues, so now is the time to
chime in.

Here are the goals:

a) signal errors from core and plugins on elements using real GObject
signals
b) provide a specific enum (in a GError) against a canonical list of
enums for error codes that we (hopefully) can keep media-agnostic.
c) provide a translated string matching the enum code
d) provide a debug string (non-translated) for further debugging.
e) provide the element that first signalled the error
f) make a patch set that is largely applicable to stable and head at the
same time

In an application, the following would thus be possible:
a) pop up an error dialog with an advanced button, where "advanced"
would show (d) and (e), as well as source code file, line number,
function
b) have the application trap errors of a specific kind so that it can
decide to try plan b instead of popping up a dialog
c) have the application use available translated strings (from core and
plugins) if it chooses to do so
d) have the application be able to provide it's own error messages if it
thinks it needs to, based on the enum

some things to consider here:
a) we can provide functions that map the very specific finegrained enums
to coarse enum domains (ie, all device errors could map to one class).

b) we need to decide on whether or not we want plug-ins to be able to
provide custom translated messages.  If there is a direct one-to-one
mapping between enums and error strings, this is not really necessary. 
If the enum would be coarse-grained (ie, only apply to a domain, like
GST_ERROR_DEVICE), then the element needs to be able to give more
specific data.
c) who knows best what went wrong, the element or the app ? A good
example to question is this:
  - if a plugin gives the translatable string, then it can pass along
what resource failed, ie which file was not found.  if an app does it,
it can know what resource it wanted to access, and thus provide a more
human way for the resource, ie "Could not listen to URGent radio"
instead of "could not open URL http://cleo.rug.ac.be:8000/mix";



c) the API for elements could be something like
   gst_element_gerror (GstErrorType GST_ERROR_(type), gchar *message,
gchart *debug);
   since we want both strings to be printf-like if needed, this would
also mean that
   - gst_element_gerror takes ownership of the strings and frees them
   - a typical call would look like
     gst_element_gerror (GST_ERROR_DEVICE,
                         g_strdup_printf (_("%s not accessible",
                                          device),
                         g_strdup_printf ("no write permissions on %s",
                                          device));

d) my current idea is that it should work like this:
  - use the API just shown (with the two strings)
  - the plugin decides to either:
    - provide a specific translatable UI string for this error
    or
    - use NULL as this string
  - the application connects to the signal, and chooses to
    - based on the enum, work around the problem somehow (try another
device, another file, ...)
    - if it does show the error, it checks if the translated string is
NULL or not
      if NULL, either show the generic error for this or show it's own
translated string for it
      if non-NULL, show the error passed along
    - behind the advanced button, the debug output can be shown


As for the translations itself; the core would contain a hopefully
exhaustive list of error enums, and code to map between enums and
translatable strings.  The translations would probably live in gnome cvs
and get regularly sinked to core until the time we can move cvs.

How does that sound ? Any remarks/objections/... ?

Thomas

Dave/Dina : future TV today ! - http://davedina.apestaart.org/
<-*- thomas (dot) apestaart (dot) org -*->
We told 'em that didn't sound very Sunday-go-to-meetin'
<-*- thomas (at) apestaart (dot) org -*->
URGent, best radio on the net - 24/7 ! - http://urgent.rug.ac.be/