forked from enlightenment/efl
parent
a91e054426
commit
3b77b6c3c5
|
@ -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 <stdlib.h>
|
||||
* #include <stdio.h>
|
||||
*
|
||||
* #include <eina_error.h>
|
||||
*
|
||||
* 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_ */
|
||||
|
|
|
@ -16,120 +16,6 @@
|
|||
* if not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* @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 <stdlib.h>
|
||||
* #include <stdio.h>
|
||||
*
|
||||
* #include <eina_error.h>
|
||||
*
|
||||
* 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;
|
||||
}
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
Loading…
Reference in New Issue