summaryrefslogtreecommitdiff
path: root/src/lib/eina/eina_error.h
blob: c21cb7bc7e9ef4d56bc208cb7420555516173f4f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
/* EINA - EFL data type library
 * Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library;
 * if not, see <http://www.gnu.org/licenses/>.
 */

#ifndef EINA_ERROR_H_
#define EINA_ERROR_H_

#include <stdarg.h>

#include "eina_types.h"


/**
 * @page tutorial_error_page Error Tutorial
 *
 * @section tutorial_error_registering_msg Registering messages
 *
 * The error module can provide a system that extends the errno system
 * of the C standard library. It consists in 2 parts:
 *
 * @li A way of registering new messages with
 * eina_error_msg_register() and eina_error_msg_get(),
 * @li A way of setting / getting the last error message with
 * eina_error_set() / eina_error_get().
 *
 * So one has to first register all the error messages that a program
 * or a library should manage. Then, when an error occurs, use
 * eina_error_set(), and when errors are managed, use
 * eina_error_get(). If eina_error_set() is used to set an error, do
 * not forget to remove previous set errors before calling eina_error_set().
 *
 * Here is an example for use:
 *
 * @include eina_error_01.c
 *
 * Of course, instead of printf(), eina_log_print() can be used to
 * have beautiful error messages.
 */

/**
 * @defgroup Eina_Error_Group Error
 * @ingroup Eina_Tools_Group
 *
 * @brief This group discusses the functions that provide error management for projects.
 *
 * The Eina error module provides a way to manage errors in a simple
 * but powerful way in libraries and modules. It is also used in Eina
 * itself.  An extension to libC's @c errno and strerror() facilities,
 * this is extensible and recommended for other libraries and
 * applications as well.
 *
 * While libC's @c errno is fixed, Eina_Error can be extended by
 * libraries and applications with domain-specific codes and
 * associated error messages. All @c errno.h codes are usable
 * seamlessly with Eina_Error. The constants defined in errno.h will
 * have messages as reported by strerror() in eina_error_msg_get()
 *
 * Success (no-error) condition is reported with Eina_Error 0
 * (#EINA_ERROR_NO_ERROR).
 *
 * A simple example of how to use this can be seen @ref tutorial_error_page
 * "here".
 *
 * @{
 */

/**
 * @typedef Eina_Error
 * @brief The integer type containing the error type.
 *
 * Errors are registered with eina_error_msg_register(),
 * eina_error_msg_static_register() or those inherited from the
 * system's @c errno.h such as @c ENOMEM.
 */
typedef int Eina_Error;

/**
 * @def EINA_ERROR_NO_ERROR
 * @brief No error reported.
 *
 * This is a convenience macro for people that are extra verbose, same
 * as "0".
 */
#define EINA_ERROR_NO_ERROR ((Eina_Error)0)

/**
 * @var EINA_ERROR_OUT_OF_MEMORY
 * @brief The error identifier corresponding to lack of memory.
 *
 * @deprecated since 1.19, same as @c ENOMEM from @c errno.h
 */
EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY EINA_DEPRECATED; /* use ENOMEM */

/**
 * @brief Registers a new error type.
 * @details This function stores the error message described by
 *          @p msg in a list. The returned value is a unique identifier greater than or equal
 *          to @c 1. The description can be retrieved later by passing
 *          the returned value to eina_error_msg_get().
 *
 * @param[in] msg The description of the error \n
 *                It is duplicated using eina_stringshare_add().
 * @return The unique number identifier for this error
 *
 * @note There is no need to register messages that exist in libC's @c
 *       errno.h, such as @c ENOMEM or @c EBADF.
 *
 * @see eina_error_msg_static_register()
 */
EAPI Eina_Error  eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Registers a new error type, statically allocated message.
 * @details This function stores the error message described by
 *          @p msg in a list. The returned value is a unique identifier greater than or equal
 *          to @c 1. The description can be retrieved later by passing
 *          the returned value to eina_error_msg_get().
 *
 * @param[in] msg The description of the error \n
 *            This string is not duplicated and thus
 *            the given pointer should live during the usage of eina_error.
 * @return The unique number identifier for this error
 *
 * @note There is no need to register messages that exist in libC's @c
 *       errno.h, such as @c ENOMEM or @c EBADF.
 *
 * @see eina_error_msg_register()
 */
EAPI Eina_Error  eina_error_msg_static_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Changes the message of an already registered message.
 * @details This function modifies the message associated with @p error and changes
 *          it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register
 *          then the string is not duplicated, otherwise the previous message
 *          is unref'ed and @p msg is copied.
 *
 * @param[in] error The Eina_Error to change the message of
 * @param[in] msg The description of the error \n
 *            This string is duplicated only if the error is registered with @ref eina_error_msg_register,
 *            otherwise it must remain intact for the duration.
 * @return #EINA_TRUE if successful, otherwise #EINA_FALSE on error
 *
 * @note It is not possible to modify messages that exist in libC's @c
 *       errno.h, such as @c ENOMEM or @c EBADF.
 *
 *
 * @see eina_error_msg_register()
 */
EAPI Eina_Bool   eina_error_msg_modify(Eina_Error  error,
                                       const char *msg) EINA_ARG_NONNULL(2);

/**
 * @brief Returns the last set error.
 * @details This function returns the last error set by eina_error_set(). The
 *          description of the message is returned by eina_error_msg_get().
 *
 * @return The last error or 0 (#EINA_ERROR_NO_ERROR).
 *
 * @note This function is thread safe @since 1.10, but slower to use.
 */
EAPI Eina_Error  eina_error_get(void);

/**
 * @brief Sets the last error.
 * @details This function sets the last error identifier. The last error can be
 *          retrieved by eina_error_get().
 *
 * @param[in] err The error identifier
 *
 * @note This is also used to clear previous errors, in which case @p err should
 *        be @c 0 (#EINA_ERROR_NO_ERROR).
 *
 * @note This function is thread safe @since 1.10, but slower to use.
 */
EAPI void        eina_error_set(Eina_Error err);

/**
 * @brief Returns the description of the given error number.
 * @details This function returns the description of an error that has been
 *          registered by eina_error_msg_register(). If an incorrect error is
 *          given, then @c NULL is returned.
 * @param[in] error The error number
 * @return The description of the error
 *
 */
EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE;

/**
 * @brief Finds the #Eina_Error corresponding to a message string.
 * @details This function attempts to match @p msg with its corresponding #Eina_Error value.
 *          If no such value is found, @c 0 is returned.
 *
 * @param[in] msg The error message string to match (NOT @c NULL)
 * @return The #Eina_Error matching @p msg, otherwise @c 0 on failure
 *
 * @note this function only works for explicitly registered errors
 *       such as the messages given to eina_error_msg_register(),
 *       eina_error_msg_static_register() or modified with
 *       eina_error_msg_modify().
 */
EAPI Eina_Error  eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE;

/**
 * @}
 */

#endif /* EINA_ERROR_H_ */