aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_error.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_error.h')
-rw-r--r--libraries/eina/src/include/eina_error.h198
1 files changed, 0 insertions, 198 deletions
diff --git a/libraries/eina/src/include/eina_error.h b/libraries/eina/src/include/eina_error.h
deleted file mode 100644
index dd87edf..0000000
--- a/libraries/eina/src/include/eina_error.h
+++ /dev/null
@@ -1,198 +0,0 @@
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 */
85typedef int Eina_Error;
86
87/**
88 * @var EINA_ERROR_OUT_OF_MEMORY
89 * Error identifier corresponding to a lack of memory.
90 */
91
92EAPI 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 */
108EAPI 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 */
125EAPI 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 */
143EAPI 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 */
154EAPI 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 */
167EAPI 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 */
179EAPI 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 */
188EAPI 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_ */
generated by cgit v1.1 at 2024-08-27 21:31:39 +0000