11 GstGError

Categorized error messages

11.1 Overview

GStreamer elements can throw non-fatal warnings and fatal errors. Higher-level elements and applications can programatically filter the ones they are interested in or can recover from, and have a default handler handle the rest of them.

The rest of this section will use the term error to mean both (non-fatal) warnings and (fatal) errors; they are treated similarly.

Errors from elements are the combination of a <g-error> and a debug string. The <g-error> contains: - a domain type: CORE, LIBRARY, RESOURCE or STREAM - a code: an enum value specific to the domain - a translated, human-readable message - a non-translated additional debug string, which also contains - file and line information

Elements do not have the context required to decide what to do with errors. As such, they should only inform about errors, and stop their processing. In short, an element doesn't know what it is being used for.

It is the application or compound element using the given element that has more context about the use of the element. Errors can be received by listening to the <gst-bus> of the element/pipeline for <gst-message> objects with the type ‘GST_MESSAGE_ERROR’ or ‘GST_MESSAGE_WARNING’. The thrown errors should be inspected, and filtered if appropriate.

An application is expected to, by default, present the user with a dialog box (or an equivalent) showing the error message. The dialog should also allow a way to get at the additional debug information, so the user can provide bug reporting information.

A compound element is expected to forward errors by default higher up the hierarchy; this is done by default in the same way as for other types of <gst-message>.

When applications or compound elements trigger errors that they can recover from, they can filter out these errors and take appropriate action. For example, an application that gets an error from xvimagesink that indicates all XVideo ports are taken, the application can attempt to use another sink instead.

Elements throw errors using the <gst-element-error> convenience macro:

     
         GST_ELEMENT_ERROR (src, RESOURCE, NOT_FOUND,
           (_("No file name specified for reading.")), (NULL));
     

Things to keep in mind:

• Don't go off inventing new error codes. The ones currently provided should be enough. If you find your type of error does not fit the current codes, you should use FAILED.
• Don't provide a message if the default one suffices. this keeps messages more uniform. Use (NULL) - not forgetting the parentheses.
• If you do supply a custom message, it should be marked for translation. The message should start with a capital and end with a period. The message should describe the error in short, in a human-readable form, and without any complex technical terms. A user interface will present this message as the first thing a user sees. Details, technical info, ... should go in the debug string.
• The debug string can be as you like. Again, use (NULL) if there's nothing to add - file and line number will still be passed. <gst-error-system> can be used as a shortcut to give debug information on a system call error.

Last reviewed on 2006-09-15 (0.10.10)

11.2 Usage