glib/gerror.h

   1 /* gerror.h - Error reporting system
   2  *
   3  *  Copyright 2000 Red Hat, Inc.
   4  *
   5  * The Gnome Library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public License as
   7  * published by the Free Software Foundation; either version 2 of the
   8  * License, or (at your option) any later version.
   9  *
  10  * The Gnome Library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with the Gnome Library; see the file COPYING.LIB.  If not,
  17  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  *   Boston, MA 02111-1307, USA.
  19  */
  20
  21 #ifndef __G_ERROR_H__
  22 #define __G_ERROR_H__
  23
  24 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  25 #error "Only <glib.h> can be included directly."
  26 #endif
  27
  28 #include <stdarg.h>
  29
  30 #include <glib/gquark.h>
  31
  32 G_BEGIN_DECLS
  33
  34 /**
  35  * GError:
  36  * @domain: error domain, e.g. #G_FILE_ERROR
  37  * @code: error code, e.g. %G_FILE_ERROR_NOENT
  38  * @message: human-readable informative error message
  39  *
  40  * The <structname>GError</structname> structure contains
  41  * information about an error that has occurred.
  42  */
  43 typedef struct _GError GError;
  44
  45 struct _GError
  46 {
  47   GQuark       domain;
  48   gint         code;
  49   gchar       *message;
  50 };
  51
  52 GLIB_AVAILABLE_IN_ALL
  53 GError*  g_error_new           (GQuark         domain,
  54                                 gint           code,
  55                                 const gchar   *format,
  56                                 ...) G_GNUC_PRINTF (3, 4);
  57
  58 GLIB_AVAILABLE_IN_ALL
  59 GError*  g_error_new_literal   (GQuark         domain,
  60                                 gint           code,
  61                                 const gchar   *message);
  62 GLIB_AVAILABLE_IN_ALL
  63 GError*  g_error_new_valist    (GQuark         domain,
  64                                 gint           code,
  65                                 const gchar   *format,
  66                                 va_list        args) G_GNUC_PRINTF(3, 0);
  67
  68 GLIB_AVAILABLE_IN_ALL
  69 void     g_error_free          (GError        *error);
  70 GLIB_AVAILABLE_IN_ALL
  71 GError*  g_error_copy          (const GError  *error);
  72
  73 GLIB_AVAILABLE_IN_ALL
  74 gboolean g_error_matches       (const GError  *error,
  75                                 GQuark         domain,
  76                                 gint           code);
  77
  78 /* if (err) *err = g_error_new(domain, code, format, ...), also has
  79  * some sanity checks.
  80  */
  81 GLIB_AVAILABLE_IN_ALL
  82 void     g_set_error           (GError       **err,
  83                                 GQuark         domain,
  84                                 gint           code,
  85                                 const gchar   *format,
  86                                 ...) G_GNUC_PRINTF (4, 5);
  87
  88 GLIB_AVAILABLE_IN_ALL
  89 void     g_set_error_literal   (GError       **err,
  90                                 GQuark         domain,
  91                                 gint           code,
  92                                 const gchar   *message);
  93
  94 /* if (dest) *dest = src; also has some sanity checks.
  95  */
  96 GLIB_AVAILABLE_IN_ALL
  97 void     g_propagate_error     (GError       **dest,
  98                                 GError        *src);
  99
 100 /* if (err && *err) { g_error_free(*err); *err = NULL; } */
 101 GLIB_AVAILABLE_IN_ALL
 102 void     g_clear_error         (GError       **err);
 103
 104 /* if (err) prefix the formatted string to the ->message */
 105 GLIB_AVAILABLE_IN_ALL
 106 void     g_prefix_error               (GError       **err,
 107                                        const gchar   *format,
 108                                        ...) G_GNUC_PRINTF (2, 3);
 109
 110 /* g_propagate_error then g_error_prefix on dest */
 111 GLIB_AVAILABLE_IN_ALL
 112 void     g_propagate_prefixed_error   (GError       **dest,
 113                                        GError        *src,
 114                                        const gchar   *format,
 115                                        ...) G_GNUC_PRINTF (3, 4);
 116
 117 G_END_DECLS
 118
 119 #endif /* __G_ERROR_H__ */