docs/random/error

   1 Some notes on the error handling introduced after 0.7.3
   2
   3 - there are four domains for errors:
   4   - CORE: core GStreamer errors
   5   - LIBRARY: supporting library errors
   6   - RESOURCE: errors accessing resources (files, network, memory, ...)
   7   - STREAM: errors in the data stream
   8 - Each error in GStreamer or plug-ins can be put under one of these four.
   9 - the enum is called Gst(Domain)Error and has GST_(DOMAIN)_ERROR_(CODE) members
  10   (see GError API docs for rationale)
  11 - each of the enums starts with _FAILED at 1 (with FAILED being the generic
  12   error if none of the others applies)
  13 - second in the enum is TOO_LAZY, which allows us to keep track of those errors
  14   that we haven't categorized yet.  This means they really should either move
  15   to another one, or a new one ought to be created.
  16 - each enum ends with NUM_ERRORS
  17
  18 - elements call gst_element_error to signal an error:
  19   gst_element_error (element, domain, code, message, debug);
  20   With :
  21   - element being the one signalling the error
  22   - domain one of CORE, LIBRARY, RESOURCE, STREAM
  23   - code one of the suffixes in the Gst(Domain)Error enum
  24   - message is either NULL (to signal the standard error message for the
  25     given domain and code), or a printf-like set with the format being
  26     marked for translation.
  27     The string should start with a capital and end in a period so it forms
  28     a complete sentence.
  29     The string can/should be shown to the user of an application.
  30   - debug is either NULL or a non-translated debug string, which can be used
  31     to diagnose errors after they've happened.
  32     The string can be shown to the user when he asks for additional debug info.
  33     A useful macro is GST_ERROR_SYSTEM, which prints out the system error
  34     that explains the failure by using g_strerror.
  35
  36 - Some example calls:
  37
  38       gst_element_error (src, RESOURCE, OPEN_READ,
  39         (_("Could not open file \"%s\" for reading"), src->filename),
  40         GST_ERROR_SYSTEM);
  41
  42       The message is specified since we have more information:
  43           - the resource is a file
  44           - we know the file name
  45
  46       gst_element_error (element, CORE, NEGOTIATION, NULL, NULL);
  47
  48       This is a simple negotiation error.  The default message will be
  49       signaled, telling the user that GStreamer had an internal error.
  50
  51       gst_element_error (ebml, RESOURCE, READ, NULL,
  52                          ("Read error at position %llu (0x%llx)",
  53                          pos, pos));
  54
  55       The plugin asked to read on the underlying resource (using bytestream),
  56       but failed.  The user will get a generic read error.  The debug info
  57       will contain the exact position in the stream at which the read error
  58       occured.
  59