glib/gerror.h

   1 /* gerror.h - Error reporting system
   2  *
   3  *  Copyright 2000 Red Hat, Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This 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 License
  16  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef __G_ERROR_H__
  20 #define __G_ERROR_H__
  21
  22 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  23 #error "Only <glib.h> can be included directly."
  24 #endif
  25
  26 #include <stdarg.h>
  27
  28 #include <glib/gquark.h>
  29
  30 G_BEGIN_DECLS
  31
  32 /**
  33  * GError:
  34  * @domain: error domain, e.g. #G_FILE_ERROR
  35  * @code: error code, e.g. %G_FILE_ERROR_NOENT
  36  * @message: human-readable informative error message
  37  *
  38  * The `GError` structure contains information about
  39  * an error that has occurred.
  40  */
  41 typedef struct _GError GError;
  42
  43 struct _GError
  44 {
  45   GQuark       domain;
  46   gint         code;
  47   gchar       *message;
  48 };
  49
  50 GLIB_AVAILABLE_IN_ALL
  51 GError*  g_error_new           (GQuark         domain,
  52                                 gint           code,
  53                                 const gchar   *format,
  54                                 ...) G_GNUC_PRINTF (3, 4);
  55
  56 GLIB_AVAILABLE_IN_ALL
  57 GError*  g_error_new_literal   (GQuark         domain,
  58                                 gint           code,
  59                                 const gchar   *message);
  60 GLIB_AVAILABLE_IN_ALL
  61 GError*  g_error_new_valist    (GQuark         domain,
  62                                 gint           code,
  63                                 const gchar   *format,
  64                                 va_list        args) G_GNUC_PRINTF(3, 0);
  65
  66 GLIB_AVAILABLE_IN_ALL
  67 void     g_error_free          (GError        *error);
  68 GLIB_AVAILABLE_IN_ALL
  69 GError*  g_error_copy          (const GError  *error);
  70
  71 GLIB_AVAILABLE_IN_ALL
  72 gboolean g_error_matches       (const GError  *error,
  73                                 GQuark         domain,
  74                                 gint           code);
  75
  76 /* if (err) *err = g_error_new(domain, code, format, ...), also has
  77  * some sanity checks.
  78  */
  79 GLIB_AVAILABLE_IN_ALL
  80 void     g_set_error           (GError       **err,
  81                                 GQuark         domain,
  82                                 gint           code,
  83                                 const gchar   *format,
  84                                 ...) G_GNUC_PRINTF (4, 5);
  85
  86 GLIB_AVAILABLE_IN_ALL
  87 void     g_set_error_literal   (GError       **err,
  88                                 GQuark         domain,
  89                                 gint           code,
  90                                 const gchar   *message);
  91
  92 /* if (dest) *dest = src; also has some sanity checks.
  93  */
  94 GLIB_AVAILABLE_IN_ALL
  95 void     g_propagate_error     (GError       **dest,
  96                                 GError        *src);
  97
  98 /* if (err && *err) { g_error_free(*err); *err = NULL; } */
  99 GLIB_AVAILABLE_IN_ALL
 100 void     g_clear_error         (GError       **err);
 101
 102 /* if (err) prefix the formatted string to the ->message */
 103 GLIB_AVAILABLE_IN_ALL
 104 void     g_prefix_error               (GError       **err,
 105                                        const gchar   *format,
 106                                        ...) G_GNUC_PRINTF (2, 3);
 107
 108 /* g_propagate_error then g_error_prefix on dest */
 109 GLIB_AVAILABLE_IN_ALL
 110 void     g_propagate_prefixed_error   (GError       **dest,
 111                                        GError        *src,
 112                                        const gchar   *format,
 113                                        ...) G_GNUC_PRINTF (3, 4);
 114
 115 G_END_DECLS
 116
 117 #endif /* __G_ERROR_H__ */