1 Some notes on the error handling introduced after 0.7.3
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
18 - elements call gst_element_error to signal an error:
19 gst_element_error (element, domain, code, message, debug);
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
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.
38 gst_element_error (src, RESOURCE, OPEN_READ,
39 (_("Could not open file \"%s\" for reading"), src->filename),
42 The message is specified since we have more information:
43 - the resource is a file
44 - we know the file name
46 gst_element_error (element, CORE, NEGOTIATION, NULL, NULL);
48 This is a simple negotiation error. The default message will be
49 signaled, telling the user that GStreamer had an internal error.
51 gst_element_error (ebml, RESOURCE, READ, NULL,
52 ("Read error at position %llu (0x%llx)",
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