diff --git a/legacy/eina/src/include/eina_error.h b/legacy/eina/src/include/eina_error.h index 3e43112e3a..ec35c5438f 100644 --- a/legacy/eina/src/include/eina_error.h +++ b/legacy/eina/src/include/eina_error.h @@ -23,6 +23,136 @@ #include "eina_types.h" + +/** + * @page tutorial_error_page Error Tutorial + * + * @section tutorial_error_introduction Introduction + * + * 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. Similar to libC's @c errno and strerror() facilities, this + * is extensible and recommended for other libraries and applications. + * + * @section tutorial_error_registering_msg Registering messages + * + * The error module can provide a system that mimic 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 last error message with + * eina_error_set() / eina_error_get(). + * + * So one has to fisrt register all the error messages that a program + * or a lib should manage. Then, when an error can occur, 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 call before eina_error_set(), to remove previous set + * errors. + * + * Here is an example of use: + * + * @code + * #include + * #include + * + * #include + * + * Eina_Error MY_ERROR_NEGATIVE; + * Eina_Error MY_ERROR_NULL; + * + * voi *data_new() + * { + * eina_error_set(0); + * + * eina_error_set(MY_ERROR_NULL); + * return NULL; + * } + * + * int test(int n) + * { + * eina_error_set(0); + * + * if (n < 0) + * { + * eina_error_set(MY_ERROR_NEGATIVE); + * return 0; + * } + * + * return 1; + * } + * + * int main(void) + * { + * void *data; + * + * if (!eina_init()) + * { + * printf ("Error during the initialization of eina_error module\n"); + * return EXIT_FAILURE; + * } + * + * MY_ERROR_NEGATIVE = eina_error_msg_register("Negative number"); + * MY_ERROR_NULL = eina_error_msg_register("NULL pointer"); + + * data = data_new(); + * if (!data) + * { + * Eina_Error err; + * + * err = eina_error_get(); + * if (err) + * printf("Error during memory allocation: %s\n", + * eina_error_msg_get(err)); + * } + * + * if (!test(0)) + * { + * Eina_Error err; + * + * err = eina_error_get(); + * if (err) + * printf("Error during test function: %s\n", + * eina_error_msg_get(err)); + * } + * + * if (!test(-1)) + * { + * Eina_Error err; + * + * err = eina_error_get(); + * if (err) + * printf("Error during test function: %s\n", + * eina_error_msg_get(err)); + * } + * + * eina_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Of course, instead of printf(), eina_log_print() can be used to + * have beautiful error messages. + */ + +/** + * @addtogroup Eina_Error_Group Error + * + * @brief These functions provide error management for projects. + * + * To use the error system Eina must be initialized with eina_init() + * and later shut down with eina_shutdown(). Error codes are + * registered with eina_error_msg_register() and converted from + * identifier to original message string with eina_error_msg_get(). + * + * Logging functions are not in eina_error anymore, see + * eina_log_print() instead. + * + * @{ + */ + /** * @addtogroup Eina_Tools_Group Tools * @@ -45,15 +175,100 @@ typedef int Eina_Error; * @var EINA_ERROR_OUT_OF_MEMORY * Error identifier corresponding to a lack of memory. */ + +/** + * @brief Register a new error type. + * + * @param msg The description of the error. It will be duplicated using + * eina_stringshare_add(). + * @return The unique number identifier for this error. + * + * This function stores in a list the error message described by + * @p msg. The returned value is a unique identifier greater or equal + * than 1. The description can be retrieve later by passing to + * eina_error_msg_get() the returned value. + * + * @see eina_error_msg_static_register() + */ EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY; EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Register a new error type, statically allocated message. + * + * @param msg The description of the error. This string will not be + * duplicated and thus the given pointer should live during + * usage of eina_error. + * @return The unique number identifier for this error. + * + * This function stores in a list the error message described by + * @p msg. The returned value is a unique identifier greater or equal + * than 1. The description can be retrieve later by passing to + * eina_error_msg_get() the returned value. + * + * @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 Change the message of an already registered message + * + * @param error The Eina_Error to change the message of + * @param msg The description of the error. This string will be + * duplicated only if the error was registered with @ref eina_error_msg_register + * otherwise it must remain intact for the duration + * @return EINA_TRUE if successful, EINA_FALSE on error + * + * This function modifies the message associated with @p error and changes + * it to @p msg. If the error was previously registered by @ref eina_error_msg_static_register + * then the string will not be duplicated, otherwise the previous message + * will be unrefed and @p msg copied. + * + * @see eina_error_msg_register() + */ EAPI Eina_Bool eina_error_msg_modify(Eina_Error error, const char *msg) EINA_ARG_NONNULL(2); + +/** + * @brief Return the last set error. + * + * @return The last error. + * + * This function returns the last error set by eina_error_set(). The + * description of the message is returned by eina_error_msg_get(). + */ EAPI Eina_Error eina_error_get(void); + +/** + * @brief Set the last error. + * + * @param err The error identifier. + * + * This function sets the last error identifier. The last error can be + * retrieved with eina_error_get(). + */ EAPI void eina_error_set(Eina_Error err); + +/** + * @brief Return the description of the given an error number. + * + * @param error The error number. + * @return The description of the error. + * + * This function returns the description of an error that has been + * registered with eina_error_msg_register(). If an incorrect error is + * given, then @c NULL is returned. + */ EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE; + +/** + * @brief Find the #Eina_Error corresponding to a message string + * @param msg The error message string to match (NOT #NULL) + * @return The #Eina_Error matching @p msg, or 0 on failure + * This function attempts to match @p msg with its corresponding #Eina_Error value. + * If no such value is found, 0 is returned. + */ EAPI Eina_Error eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE; /** @@ -64,4 +279,8 @@ EAPI Eina_Error eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE; * @} */ +/** + * @} + */ + #endif /* EINA_ERROR_H_ */ diff --git a/legacy/eina/src/lib/eina_error.c b/legacy/eina/src/lib/eina_error.c index 0345bd5b65..2fa940a708 100644 --- a/legacy/eina/src/lib/eina_error.c +++ b/legacy/eina/src/lib/eina_error.c @@ -16,120 +16,6 @@ * if not, see . */ - -/** - * @page tutorial_error_page Error Tutorial - * - * @section tutorial_error_introduction Introduction - * - * 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. Similar to libC's @c errno and strerror() facilities, this - * is extensible and recommended for other libraries and applications. - * - * @section tutorial_error_registering_msg Registering messages - * - * The error module can provide a system that mimic 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 last error message with - * eina_error_set() / eina_error_get(). - * - * So one has to fisrt register all the error messages that a program - * or a lib should manage. Then, when an error can occur, 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 call before eina_error_set(), to remove previous set - * errors. - * - * Here is an example of use: - * - * @code - * #include - * #include - * - * #include - * - * Eina_Error MY_ERROR_NEGATIVE; - * Eina_Error MY_ERROR_NULL; - * - * voi *data_new() - * { - * eina_error_set(0); - * - * eina_error_set(MY_ERROR_NULL); - * return NULL; - * } - * - * int test(int n) - * { - * eina_error_set(0); - * - * if (n < 0) - * { - * eina_error_set(MY_ERROR_NEGATIVE); - * return 0; - * } - * - * return 1; - * } - * - * int main(void) - * { - * void *data; - * - * if (!eina_init()) - * { - * printf ("Error during the initialization of eina_error module\n"); - * return EXIT_FAILURE; - * } - * - * MY_ERROR_NEGATIVE = eina_error_msg_register("Negative number"); - * MY_ERROR_NULL = eina_error_msg_register("NULL pointer"); - - * data = data_new(); - * if (!data) - * { - * Eina_Error err; - * - * err = eina_error_get(); - * if (err) - * printf("Error during memory allocation: %s\n", - * eina_error_msg_get(err)); - * } - * - * if (!test(0)) - * { - * Eina_Error err; - * - * err = eina_error_get(); - * if (err) - * printf("Error during test function: %s\n", - * eina_error_msg_get(err)); - * } - * - * if (!test(-1)) - * { - * Eina_Error err; - * - * err = eina_error_get(); - * if (err) - * printf("Error during test function: %s\n", - * eina_error_msg_get(err)); - * } - * - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode - * - * Of course, instead of printf(), eina_log_print() can be used to - * have beautiful error messages. - */ - #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -284,36 +170,6 @@ eina_error_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Error_Group Error - * - * @brief These functions provide error management for projects. - * - * To use the error system Eina must be initialized with eina_init() - * and later shut down with eina_shutdown(). Error codes are - * registered with eina_error_msg_register() and converted from - * identifier to original message string with eina_error_msg_get(). - * - * Logging functions are not in eina_error anymore, see - * eina_log_print() instead. - * - * @{ - */ - -/** - * @brief Register a new error type. - * - * @param msg The description of the error. It will be duplicated using - * eina_stringshare_add(). - * @return The unique number identifier for this error. - * - * This function stores in a list the error message described by - * @p msg. The returned value is a unique identifier greater or equal - * than 1. The description can be retrieve later by passing to - * eina_error_msg_get() the returned value. - * - * @see eina_error_msg_static_register() - */ EAPI Eina_Error eina_error_msg_register(const char *msg) { @@ -336,21 +192,6 @@ eina_error_msg_register(const char *msg) return _eina_errors_count; /* identifier = index + 1 (== _count). */ } -/** - * @brief Register a new error type, statically allocated message. - * - * @param msg The description of the error. This string will not be - * duplicated and thus the given pointer should live during - * usage of eina_error. - * @return The unique number identifier for this error. - * - * This function stores in a list the error message described by - * @p msg. The returned value is a unique identifier greater or equal - * than 1. The description can be retrieve later by passing to - * eina_error_msg_get() the returned value. - * - * @see eina_error_msg_register() - */ EAPI Eina_Error eina_error_msg_static_register(const char *msg) { @@ -367,22 +208,6 @@ eina_error_msg_static_register(const char *msg) return _eina_errors_count; /* identifier = index + 1 (== _count). */ } -/** - * @brief Change the message of an already registered message - * - * @param error The Eina_Error to change the message of - * @param msg The description of the error. This string will be - * duplicated only if the error was registered with @ref eina_error_msg_register - * otherwise it must remain intact for the duration - * @return EINA_TRUE if successful, EINA_FALSE on error - * - * This function modifies the message associated with @p error and changes - * it to @p msg. If the error was previously registered by @ref eina_error_msg_static_register - * then the string will not be duplicated, otherwise the previous message - * will be unrefed and @p msg copied. - * - * @see eina_error_msg_register() - */ EAPI Eina_Bool eina_error_msg_modify(Eina_Error error, const char *msg) { @@ -409,16 +234,6 @@ eina_error_msg_modify(Eina_Error error, const char *msg) return EINA_TRUE; } -/** - * @brief Return the description of the given an error number. - * - * @param error The error number. - * @return The description of the error. - * - * This function returns the description of an error that has been - * registered with eina_error_msg_register(). If an incorrect error is - * given, then @c NULL is returned. - */ EAPI const char * eina_error_msg_get(Eina_Error error) { @@ -431,41 +246,18 @@ eina_error_msg_get(Eina_Error error) return _eina_errors[error - 1].string; } -/** - * @brief Return the last set error. - * - * @return The last error. - * - * This function returns the last error set by eina_error_set(). The - * description of the message is returned by eina_error_msg_get(). - */ EAPI Eina_Error eina_error_get(void) { return _eina_last_error; } -/** - * @brief Set the last error. - * - * @param err The error identifier. - * - * This function sets the last error identifier. The last error can be - * retrieved with eina_error_get(). - */ EAPI void eina_error_set(Eina_Error err) { _eina_last_error = err; } -/** - * @brief Find the #Eina_Error corresponding to a message string - * @param msg The error message string to match (NOT #NULL) - * @return The #Eina_Error matching @p msg, or 0 on failure - * This function attempts to match @p msg with its corresponding #Eina_Error value. - * If no such value is found, 0 is returned. - */ EAPI Eina_Error eina_error_find(const char *msg) { @@ -485,6 +277,3 @@ eina_error_find(const char *msg) } return 0; } -/** - * @} - */