From 2dabfe756782dac4648b2b71379419de82d66b9b Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Mon, 19 Jan 2004 18:00:43 +0000 Subject: [PATCH] adding docs Original commit message from CVS: adding docs --- ChangeLog | 7 +++++ docs/random/error | 59 +++++++++++++++++++++++++++++++++++ gst/elements/gstfilesrc.c | 9 +----- plugins/elements/gstfilesrc.c | 9 +----- 4 files changed, 68 insertions(+), 16 deletions(-) create mode 100644 docs/random/error diff --git a/ChangeLog b/ChangeLog index 33aca24923..e543022038 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2004-01-19 Thomas Vander Stichele + + * docs/random/error: + doc explaining error system + * gst/elements/gstfilesrc.c: (gst_filesrc_open_file): + cleanup + 2004-01-19 Thomas Vander Stichele * gst/gst-i18n-app.h: diff --git a/docs/random/error b/docs/random/error new file mode 100644 index 0000000000..faf2a46d44 --- /dev/null +++ b/docs/random/error @@ -0,0 +1,59 @@ +Some notes on the error handling introduced after 0.7.3 + +- there are four domains for errors: + - CORE: core GStreamer errors + - LIBRARY: supporting library errors + - RESOURCE: errors accessing resources (files, network, memory, ...) + - STREAM: errors in the data stream +- Each error in GStreamer or plug-ins can be put under one of these four. +- the enum is called Gst(Domain)Error and has GST_(DOMAIN)_ERROR_(CODE) members + (see GError API docs for rationale) +- each of the enums starts with _FAILED at 1 (with FAILED being the generic + error if none of the others applies) +- second in the enum is TOO_LAZY, which allows us to keep track of those errors + that we haven't categorized yet. This means they really should either move + to another one, or a new one ought to be created. +- each enum ends with NUM_ERRORS + +- elements call gst_element_error to signal an error: + gst_element_error (element, domain, code, message, debug); + With : + - element being the one signalling the error + - domain one of CORE, LIBRARY, RESOURCE, STREAM + - code one of the suffixes in the Gst(Domain)Error enum + - message is either NULL (to signal the standard error message for the + given domain and code), or a printf-like set with the format being + marked for translation. + The string should start with a capital and not end in a period + (FIXME: this is something we may want to change). + The string can/should be shown to the user of an application. + - debug is either NULL or a non-translated debug string, which can be used + to diagnose errors after they've happened. + The string can be shown to the user when he asks for additional debug info. + A useful macro is GST_ERROR_SYSTEM, which prints out the system error + that explains the failure by using g_strerror. + +- Some example calls: + + gst_element_error (src, RESOURCE, OPEN_READ, + (_("Could not open file \"%s\" for reading"), src->filename), + GST_ERROR_SYSTEM); + + The message is specified since we have more information: + - the resource is a file + - we know the file name + + gst_element_error (element, CORE, NEGOTIATION, NULL, NULL); + + This is a simple negotiation error. The default message will be + signaled, telling the user that GStreamer had an internal error. + + gst_element_error (ebml, RESOURCE, READ, NULL, + ("Read error at position %llu (0x%llx)", + pos, pos)); + + The plugin asked to read on the underlying resource (using bytestream), + but failed. The user will get a generic read error. The debug info + will contain the exact position in the stream at which the read error + occured. + diff --git a/gst/elements/gstfilesrc.c b/gst/elements/gstfilesrc.c index 78d1a9f6ed..3dceef1b08 100644 --- a/gst/elements/gstfilesrc.c +++ b/gst/elements/gstfilesrc.c @@ -747,14 +747,7 @@ gst_filesrc_open_file (GstFileSrc *src) if (src->fd < 0) { if (errno == ENOENT) - gst_element_error (src, RESOURCE, NOT_FOUND, - NULL, - NULL); -/* thomas - gst_element_error (src, RESOURCE, NOT_FOUND, - (_("File \"%s\" does not exist"), src->filename), - NULL); -*/ + gst_element_error (src, RESOURCE, NOT_FOUND, NULL, NULL); else gst_element_error (src, RESOURCE, OPEN_READ, (_("Could not open file \"%s\" for reading"), src->filename), diff --git a/plugins/elements/gstfilesrc.c b/plugins/elements/gstfilesrc.c index 78d1a9f6ed..3dceef1b08 100644 --- a/plugins/elements/gstfilesrc.c +++ b/plugins/elements/gstfilesrc.c @@ -747,14 +747,7 @@ gst_filesrc_open_file (GstFileSrc *src) if (src->fd < 0) { if (errno == ENOENT) - gst_element_error (src, RESOURCE, NOT_FOUND, - NULL, - NULL); -/* thomas - gst_element_error (src, RESOURCE, NOT_FOUND, - (_("File \"%s\" does not exist"), src->filename), - NULL); -*/ + gst_element_error (src, RESOURCE, NOT_FOUND, NULL, NULL); else gst_element_error (src, RESOURCE, OPEN_READ, (_("Could not open file \"%s\" for reading"), src->filename),