gst/gsterror.c

   1 /* GStreamer
   2  * Copyright (C) <2003> David A. Schleef <ds@schleef.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 /**
  21  * SECTION:gsterror
  22  * @title: GstGError
  23  * @short_description: Categorized error messages
  24  * @see_also: #GstMessage
  25  * @symbols:
  26  * - gst_error_get_message
  27  * - gst_stream_error_quark
  28  * - gst_core_error_quark
  29  * - gst_resource_error_quark
  30  * - gst_library_error_quark
  31  *
  32  * GStreamer elements can throw non-fatal warnings and fatal errors.
  33  * Higher-level elements and applications can programmatically filter
  34  * the ones they are interested in or can recover from,
  35  * and have a default handler handle the rest of them.
  36  *
  37  * The rest of this section will use the term <quote>error</quote>
  38  * to mean both (non-fatal) warnings and (fatal) errors; they are treated
  39  * similarly.
  40  *
  41  * Errors from elements are the combination of a #GError and a debug string.
  42  * The #GError contains:
  43  * - a domain type: CORE, LIBRARY, RESOURCE or STREAM
  44  * - a code: an enum value specific to the domain
  45  * - a translated, human-readable message
  46  * - a non-translated additional debug string, which also contains
  47  * - file and line information
  48  *
  49  * Elements do not have the context required to decide what to do with
  50  * errors.  As such, they should only inform about errors, and stop their
  51  * processing.  In short, an element doesn't know what it is being used for.
  52  *
  53  * It is the application or compound element using the given element that
  54  * has more context about the use of the element. Errors can be received by
  55  * listening to the #GstBus of the element/pipeline for #GstMessage objects with
  56  * the type %GST_MESSAGE_ERROR or %GST_MESSAGE_WARNING. The thrown errors should
  57  * be inspected, and filtered if appropriate.
  58  *
  59  * An application is expected to, by default, present the user with a
  60  * dialog box (or an equivalent) showing the error message.  The dialog
  61  * should also allow a way to get at the additional debug information,
  62  * so the user can provide bug reporting information.
  63  *
  64  * A compound element is expected to forward errors by default higher up
  65  * the hierarchy; this is done by default in the same way as for other types
  66  * of #GstMessage.
  67  *
  68  * When applications or compound elements trigger errors that they can
  69  * recover from, they can filter out these errors and take appropriate action.
  70  * For example, an application that gets an error from xvimagesink
  71  * that indicates all XVideo ports are taken, the application can attempt
  72  * to use another sink instead.
  73  *
  74  * Elements throw errors using the #GST_ELEMENT_ERROR convenience macro:
  75  *
  76  * ## Throwing an error
  77  *
  78  *   |[
  79  *     GST_ELEMENT_ERROR (src, RESOURCE, NOT_FOUND,
  80  *       (_("No file name specified for reading.")), (NULL));
  81  *   ]|
  82  *
  83  * Things to keep in mind:
  84  *
  85  *   * Don't go off inventing new error codes.  The ones
  86  *     currently provided should be enough.  If you find your type of error
  87  *     does not fit the current codes, you should use FAILED.
  88  *   * Don't provide a message if the default one suffices.
  89  *     this keeps messages more uniform.  Use (%NULL) - not forgetting the
  90  *     parentheses.
  91  *   * If you do supply a custom message, it should be
  92  *     marked for translation.  The message should start with a capital
  93  *     and end with a period.  The message should describe the error in short,
  94  *     in a human-readable form, and without any complex technical terms.
  95  *     A user interface will present this message as the first thing a user
  96  *     sees.  Details, technical info, ... should go in the debug string.
  97  *
  98  *   * The debug string can be as you like.  Again, use (%NULL)
  99  *     if there's nothing to add - file and line number will still be
 100  *     passed.  #GST_ERROR_SYSTEM can be used as a shortcut to give
 101  *     debug information on a system call error.
 102  *
 103  */
 104
 105 /* FIXME 2.0: the entire error system needs an overhaul - it's not very
 106  * useful the way it is. Also, we need to be able to specify additional
 107  * 'details' for errors (e.g. disk/file/resource error -> out-of-space; or
 108  * put the url/filename/device name that caused the error somewhere)
 109  * without having to add enums for every little thing.
 110  *
 111  * FIXME 2.0: get rid of GST_{CORE,LIBRARY,RESOURCE,STREAM}_ERROR_NUM_ERRORS.
 112  * Maybe also replace _quark() functions with g_quark_from_static_string()?
 113  */
 114 #ifdef HAVE_CONFIG_H
 115 #include "config.h"
 116 #endif
 117
 118 #include "gst_private.h"
 119 #include <gst/gst.h>
 120 #include "gst-i18n-lib.h"
 121
 122 #define QUARK_FUNC(string)                                              \
 123 GQuark gst_ ## string ## _error_quark (void) {                          \
 124   static GQuark quark;                                                  \
 125   if (!quark)                                                           \
 126     quark = g_quark_from_static_string ("gst-" # string "-error-quark"); \
 127   return quark; }
 128
 129 #define FILE_A_BUG "  Please file a bug at " PACKAGE_BUGREPORT "."
 130
 131 static const gchar *
 132 gst_error_get_core_error (GstCoreError code)
 133 {
 134   switch (code) {
 135     case GST_CORE_ERROR_FAILED:
 136       return _("GStreamer encountered a general core library error.");
 137     case GST_CORE_ERROR_TOO_LAZY:
 138       return _("GStreamer developers were too lazy to assign an error code "
 139           "to this error." FILE_A_BUG);
 140     case GST_CORE_ERROR_NOT_IMPLEMENTED:
 141       return _("Internal GStreamer error: code not implemented." FILE_A_BUG);
 142     case GST_CORE_ERROR_STATE_CHANGE:
 143       return _("GStreamer error: state change failed and some element failed "
 144           "to post a proper error message with the reason for the failure.");
 145     case GST_CORE_ERROR_PAD:
 146       return _("Internal GStreamer error: pad problem." FILE_A_BUG);
 147     case GST_CORE_ERROR_THREAD:
 148       return _("Internal GStreamer error: thread problem." FILE_A_BUG);
 149     case GST_CORE_ERROR_NEGOTIATION:
 150       return _("GStreamer error: negotiation problem.");
 151     case GST_CORE_ERROR_EVENT:
 152       return _("Internal GStreamer error: event problem." FILE_A_BUG);
 153     case GST_CORE_ERROR_SEEK:
 154       return _("Internal GStreamer error: seek problem." FILE_A_BUG);
 155     case GST_CORE_ERROR_CAPS:
 156       return _("Internal GStreamer error: caps problem." FILE_A_BUG);
 157     case GST_CORE_ERROR_TAG:
 158       return _("Internal GStreamer error: tag problem." FILE_A_BUG);
 159     case GST_CORE_ERROR_MISSING_PLUGIN:
 160       return _("Your GStreamer installation is missing a plug-in.");
 161     case GST_CORE_ERROR_CLOCK:
 162       return _("GStreamer error: clock problem.");
 163     case GST_CORE_ERROR_DISABLED:
 164       return _("This application is trying to use GStreamer functionality "
 165           "that has been disabled.");
 166     case GST_CORE_ERROR_NUM_ERRORS:
 167     default:
 168       break;
 169   }
 170   return NULL;
 171 }
 172
 173 static const gchar *
 174 gst_error_get_library_error (GstLibraryError code)
 175 {
 176   switch (code) {
 177     case GST_LIBRARY_ERROR_FAILED:
 178       return _("GStreamer encountered a general supporting library error.");
 179     case GST_LIBRARY_ERROR_TOO_LAZY:
 180       return _("GStreamer developers were too lazy to assign an error code "
 181           "to this error." FILE_A_BUG);
 182     case GST_LIBRARY_ERROR_INIT:
 183       return _("Could not initialize supporting library.");
 184     case GST_LIBRARY_ERROR_SHUTDOWN:
 185       return _("Could not close supporting library.");
 186     case GST_LIBRARY_ERROR_SETTINGS:
 187       return _("Could not configure supporting library.");
 188     case GST_LIBRARY_ERROR_ENCODE:
 189       return _("Encoding error.");
 190     case GST_LIBRARY_ERROR_NUM_ERRORS:
 191     default:
 192       break;
 193   }
 194   return NULL;
 195 }
 196
 197 static const gchar *
 198 gst_error_get_resource_error (GstResourceError code)
 199 {
 200   switch (code) {
 201     case GST_RESOURCE_ERROR_FAILED:
 202       return _("GStreamer encountered a general resource error.");
 203     case GST_RESOURCE_ERROR_TOO_LAZY:
 204       return _("GStreamer developers were too lazy to assign an error code "
 205           "to this error." FILE_A_BUG);
 206     case GST_RESOURCE_ERROR_NOT_FOUND:
 207       return _("Resource not found.");
 208     case GST_RESOURCE_ERROR_BUSY:
 209       return _("Resource busy or not available.");
 210     case GST_RESOURCE_ERROR_OPEN_READ:
 211       return _("Could not open resource for reading.");
 212     case GST_RESOURCE_ERROR_OPEN_WRITE:
 213       return _("Could not open resource for writing.");
 214     case GST_RESOURCE_ERROR_OPEN_READ_WRITE:
 215       return _("Could not open resource for reading and writing.");
 216     case GST_RESOURCE_ERROR_CLOSE:
 217       return _("Could not close resource.");
 218     case GST_RESOURCE_ERROR_READ:
 219       return _("Could not read from resource.");
 220     case GST_RESOURCE_ERROR_WRITE:
 221       return _("Could not write to resource.");
 222     case GST_RESOURCE_ERROR_SEEK:
 223       return _("Could not perform seek on resource.");
 224     case GST_RESOURCE_ERROR_SYNC:
 225       return _("Could not synchronize on resource.");
 226     case GST_RESOURCE_ERROR_SETTINGS:
 227       return _("Could not get/set settings from/on resource.");
 228     case GST_RESOURCE_ERROR_NO_SPACE_LEFT:
 229       return _("No space left on the resource.");
 230     case GST_RESOURCE_ERROR_NOT_AUTHORIZED:
 231       return _("Not authorized to access resource.");
 232     case GST_RESOURCE_ERROR_NUM_ERRORS:
 233     default:
 234       break;
 235   }
 236   return NULL;
 237 }
 238
 239 static const gchar *
 240 gst_error_get_stream_error (GstStreamError code)
 241 {
 242   switch (code) {
 243     case GST_STREAM_ERROR_FAILED:
 244       return _("GStreamer encountered a general stream error.");
 245     case GST_STREAM_ERROR_TOO_LAZY:
 246       return _("GStreamer developers were too lazy to assign an error code "
 247           "to this error." FILE_A_BUG);
 248     case GST_STREAM_ERROR_NOT_IMPLEMENTED:
 249       return _("Element doesn't implement handling of this stream. "
 250           "Please file a bug.");
 251     case GST_STREAM_ERROR_TYPE_NOT_FOUND:
 252       return _("Could not determine type of stream.");
 253     case GST_STREAM_ERROR_WRONG_TYPE:
 254       return _("The stream is of a different type than handled by this "
 255           "element.");
 256     case GST_STREAM_ERROR_CODEC_NOT_FOUND:
 257       return _("There is no codec present that can handle the stream's type.");
 258     case GST_STREAM_ERROR_DECODE:
 259       return _("Could not decode stream.");
 260     case GST_STREAM_ERROR_ENCODE:
 261       return _("Could not encode stream.");
 262     case GST_STREAM_ERROR_DEMUX:
 263       return _("Could not demultiplex stream.");
 264     case GST_STREAM_ERROR_MUX:
 265       return _("Could not multiplex stream.");
 266     case GST_STREAM_ERROR_FORMAT:
 267       return _("The stream is in the wrong format.");
 268     case GST_STREAM_ERROR_DECRYPT:
 269       return _("The stream is encrypted and decryption is not supported.");
 270     case GST_STREAM_ERROR_DECRYPT_NOKEY:
 271       return _("The stream is encrypted and can't be decrypted because no "
 272           "suitable key has been supplied.");
 273     case GST_STREAM_ERROR_NUM_ERRORS:
 274     default:
 275       break;
 276   }
 277
 278   return NULL;
 279 }
 280
 281 QUARK_FUNC (core);
 282 QUARK_FUNC (library);
 283 QUARK_FUNC (resource);
 284 QUARK_FUNC (stream);
 285
 286 /**
 287  * gst_error_get_message:
 288  * @domain: the GStreamer error domain this error belongs to.
 289  * @code: the error code belonging to the domain.
 290  *
 291  * Get a string describing the error message in the current locale.
 292  *
 293  * Returns: (transfer full): a newly allocated string describing
 294  *     the error message (in UTF-8 encoding)
 295  */
 296 gchar *
 297 gst_error_get_message (GQuark domain, gint code)
 298 {
 299   const gchar *message = NULL;
 300
 301   if (domain == GST_CORE_ERROR)
 302     message = gst_error_get_core_error ((GstCoreError) code);
 303   else if (domain == GST_LIBRARY_ERROR)
 304     message = gst_error_get_library_error ((GstLibraryError) code);
 305   else if (domain == GST_RESOURCE_ERROR)
 306     message = gst_error_get_resource_error ((GstResourceError) code);
 307   else if (domain == GST_STREAM_ERROR)
 308     message = gst_error_get_stream_error ((GstStreamError) code);
 309   else {
 310     g_warning ("No error messages for domain %s", g_quark_to_string (domain));
 311     return g_strdup_printf (_("No error message for domain %s."),
 312         g_quark_to_string (domain));
 313   }
 314   if (message)
 315     return g_strdup (message);
 316   else
 317     return
 318         g_strdup_printf (_
 319         ("No standard error message for domain %s and code %d."),
 320         g_quark_to_string (domain), code);
 321 }