src/include/eina_error.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 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  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_ERROR_H_
  20 #define EINA_ERROR_H_
  21
  22 #include <stdarg.h>
  23
  24 #include "eina_types.h"
  25
  26
  27 /**
  28  * @page tutorial_error_page Error Tutorial
  29  *
  30  * @section tutorial_error_registering_msg Registering messages
  31  *
  32  * The error module can provide a system that mimics the errno system
  33  * of the C standard library. It consists in 2 parts:
  34  *
  35  * @li a way of registering new messages with
  36  * eina_error_msg_register() and eina_error_msg_get(),
  37  * @li a way of setting / getting last error message with
  38  * eina_error_set() / eina_error_get().
  39  *
  40  * So one has to fisrt register all the error messages that a program
  41  * or a lib should manage. Then, when an error can occur, use
  42  * eina_error_set(), and when errors are managed, use
  43  * eina_error_get(). If eina_error_set() is used to set an error, do
  44  * not forget to call before eina_error_set(), to remove previous set
  45  * errors.
  46  *
  47  * Here is an example of use:
  48  *
  49  * @include eina_error_01.c
  50  *
  51  * Of course, instead of printf(), eina_log_print() can be used to
  52  * have beautiful error messages.
  53  */
  54
  55 /**
  56  * @addtogroup Eina_Error_Group Error
  57  *
  58  * @brief These functions provide error management for projects.
  59  *
  60  * The Eina error module provides a way to manage errors in a simple but
  61  * powerful way in libraries and modules. It is also used in Eina itself.
  62  * Similar to libC's @c errno and strerror() facilities, this is extensible and
  63  * recommended for other libraries and applications.
  64  *
  65  * A simple example of how to use this can be seen @ref tutorial_error_page
  66  * "here".
  67  */
  68
  69 /**
  70  * @addtogroup Eina_Tools_Group Tools
  71  *
  72  * @{
  73  */
  74
  75 /**
  76  * @defgroup Eina_Error_Group Error
  77  *
  78  * @{
  79  */
  80
  81 /**
  82  * @typedef Eina_Error
  83  * Error type.
  84  */
  85 typedef int Eina_Error;
  86
  87 /**
  88  * @var EINA_ERROR_OUT_OF_MEMORY
  89  * Error identifier corresponding to a lack of memory.
  90  */
  91
  92 EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY;
  93
  94 /**
  95  * @brief Register a new error type.
  96  *
  97  * @param msg The description of the error. It will be duplicated using
  98  *        eina_stringshare_add().
  99  * @return The unique number identifier for this error.
 100  *
 101  * This function stores in a list the error message described by
 102  * @p msg. The returned value is a unique identifier greater or equal
 103  * than 1. The description can be retrieve later by passing to
 104  * eina_error_msg_get() the returned value.
 105  *
 106  * @see eina_error_msg_static_register()
 107  */
 108 EAPI Eina_Error  eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 109
 110 /**
 111  * @brief Register a new error type, statically allocated message.
 112  *
 113  * @param msg The description of the error. This string will not be
 114  *        duplicated and thus the given pointer should live during
 115  *        usage of eina_error.
 116  * @return The unique number identifier for this error.
 117  *
 118  * This function stores in a list the error message described by
 119  * @p msg. The returned value is a unique identifier greater or equal
 120  * than 1. The description can be retrieve later by passing to
 121  * eina_error_msg_get() the returned value.
 122  *
 123  * @see eina_error_msg_register()
 124  */
 125 EAPI Eina_Error  eina_error_msg_static_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 126
 127 /**
 128  * @brief Change the message of an already registered message
 129  *
 130  * @param error The Eina_Error to change the message of
 131  * @param msg The description of the error. This string will be
 132  * duplicated only if the error was registered with @ref eina_error_msg_register
 133  * otherwise it must remain intact for the duration.
 134  * @return #EINA_TRUE if successful, #EINA_FALSE on error.
 135  *
 136  * This function modifies the message associated with @p error and changes
 137  * it to @p msg.  If the error was previously registered by @ref eina_error_msg_static_register
 138  * then the string will not be duplicated, otherwise the previous message
 139  * will be unrefed and @p msg copied.
 140  *
 141  * @see eina_error_msg_register()
 142  */
 143 EAPI Eina_Bool   eina_error_msg_modify(Eina_Error  error,
 144                                        const char *msg) EINA_ARG_NONNULL(2);
 145
 146 /**
 147  * @brief Return the last set error.
 148  *
 149  * @return The last error.
 150  *
 151  * This function returns the last error set by eina_error_set(). The
 152  * description of the message is returned by eina_error_msg_get().
 153  */
 154 EAPI Eina_Error  eina_error_get(void);
 155
 156 /**
 157  * @brief Set the last error.
 158  *
 159  * @param err The error identifier.
 160  *
 161  * This function sets the last error identifier. The last error can be
 162  * retrieved with eina_error_get().
 163  *
 164  * @note This is also used to clear previous errors, in that case @p err should
 165  * be @c 0.
 166  */
 167 EAPI void        eina_error_set(Eina_Error err);
 168
 169 /**
 170  * @brief Return the description of the given an error number.
 171  *
 172  * @param error The error number.
 173  * @return The description of the error.
 174  *
 175  * This function returns the description of an error that has been
 176  * registered with eina_error_msg_register(). If an incorrect error is
 177  * given, then @c NULL is returned.
 178  */
 179 EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE;
 180
 181 /**
 182  * @brief Find the #Eina_Error corresponding to a message string
 183  * @param msg The error message string to match (NOT @c NULL)
 184  * @return The #Eina_Error matching @p msg, or 0 on failure
 185  * This function attempts to match @p msg with its corresponding #Eina_Error value.
 186  * If no such value is found, 0 is returned.
 187  */
 188 EAPI Eina_Error  eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE;
 189
 190 /**
 191  * @}
 192  */
 193
 194 /**
 195  * @}
 196  */
 197
 198 #endif /* EINA_ERROR_H_ */