Eina_Error_Group(3)

NAME
Eina_Error_Group - Error

 - This group discusses the functions that provide error management for projects.

SYNOPSIS

  Macros
#define EINA_ERROR_NO_ERROR ((Eina_Error)0)
No error reported.

  Typedefs
typedef int Eina_Error
The integer type containing the error type.
typedef Eina_Bool Eina_Success_Flag
A flag indicating a function completed succesfully.

  Functions
EINA_API Eina_Error eina_error_msg_register (const char *msg)
Registers a new error type.
EINA_API Eina_Error eina_error_msg_static_register (const char *msg)
Registers a new error type, statically allocated message.
EINA_API Eina_Bool eina_error_msg_modify (Eina_Error error, const char *msg)
Changes the message of an already registered message.
EINA_API Eina_Error eina_error_get (void)
Returns the last set error.
EINA_API void eina_error_set (Eina_Error err)
Sets the last error.
EINA_API const char * eina_error_msg_get (Eina_Error error)
Returns the description of the given error number.
EINA_API Eina_Error eina_error_find (const char *msg)
Finds the Eina_Error corresponding to a message string.

  Variables
EINA_API Eina_Error EINA_ERROR_OUT_OF_MEMORY EINA_DEPRECATED

Detailed Description

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 errno and strerror() facilities, this is extensible and recommended for other libraries and applications as well.

While libC's errno is fixed, Eina_Error can be extended by libraries and applications with domain-specific codes and associated error messages. All 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 here.

Macro Definition Documentation

  #define EINA_ERROR_NO_ERROR ((Eina_Error)0)

No error reported. This is a convenience macro for people that are extra verbose, same as '0'.

Typedef Documentation

  Eina_Error

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 errno.h such as ENOMEM.

  Eina_Success_Flag

A flag indicating a function completed succesfully. Errors are reported with a EINA_FALSE value for Eina_Success_Flag return and success with a EINA_TRUE.

Function Documentation

  EINA_API Eina_Error eina_error_msg_register (const char * msg)

Registers a new error type. This function stores the error message described by msg in a list. The returned value is a unique identifier greater than or equal to 1. The description can be retrieved later by passing the returned value to eina_error_msg_get().

Parameters
    msg The description of the error
     It is duplicated using eina_stringshare_add().

Returns
    The unique number identifier for this error

Note
    There is no need to register messages that exist in libC's errno.h, such as ENOMEM or EBADF.

See also
    eina_error_msg_static_register()

References EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_add(), and EINA_TRUE.

Referenced by ecore_evas_init().

  EINA_API Eina_Error eina_error_msg_static_register (const char * msg)

Registers a new error type, statically allocated message. This function stores the error message described by msg in a list. The returned value is a unique identifier greater than or equal to 1. The description can be retrieved later by passing the returned value to eina_error_msg_get().

Parameters
    msg The description of the error
     This string is not duplicated and thus the given pointer should live during the usage of eina_error.

Returns
    The unique number identifier for this error

Note
    There is no need to register messages that exist in libC's errno.h, such as ENOMEM or EBADF.

See also
    eina_error_msg_register()

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_init().

  EINA_API Eina_Bool eina_error_msg_modify (Eina_Error error, const char * msg)

Changes the message of an already registered message. This function modifies the message associated with error and changes it to msg. If the error is previously registered by eina_error_msg_static_register then the string is not duplicated, otherwise the previous message is unref'ed and msg is copied.

Parameters
    error The Eina_Error to change the message of
    msg The description of the error
     This string is duplicated only if the error is registered with eina_error_msg_register, otherwise it must remain intact for the duration.

Returns
    EINA_TRUE if successful, otherwise EINA_FALSE on error

Note
    It is not possible to modify messages that exist in libC's errno.h, such as ENOMEM or EBADF.

See also
    eina_error_msg_register()

References EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_add(), eina_stringshare_del(), and EINA_TRUE.

  EINA_API Eina_Error eina_error_get (void)

Returns the last set error. This function returns the last error set by eina_error_set(). The description of the message is returned by eina_error_msg_get().

Returns
    The last error or 0 (EINA_ERROR_NO_ERROR).

Note
    This function is thread safe

Since
    1.10, but slower to use.

References eina_main_loop_is(), and eina_tls_get().

Referenced by elm_photocam_file_set().

  EINA_API void eina_error_set (Eina_Error err)

Sets the last error. This function sets the last error identifier. The last error can be retrieved by eina_error_get().

Parameters
    err The error identifier

Note
    This is also used to clear previous errors, in which case err should be 0 (EINA_ERROR_NO_ERROR).

    This function is thread safe

Since
    1.10, but slower to use.

References eina_main_loop_is(), and eina_tls_set().

Referenced by edje_edit_state_image_border_fill_set(), edje_edit_state_image_border_set(), edje_edit_state_image_set(), and edje_edit_state_vector_set().

  EINA_API const char* eina_error_msg_get (Eina_Error error)

Returns the description of the given error number. This function returns the description of an error that has been registered by eina_error_msg_register(). If an incorrect error is given, then NULL is returned.

Parameters
    error The error number

Returns
    The description of the error

References eina_hash_add(), eina_hash_find(), EINA_LOCK_SUCCEED, eina_spinlock_release(), eina_spinlock_take(), eina_stringshare_add(), and eina_strlcpy().

Referenced by ecore_con_client_send(), ecore_con_server_send(), and eina_promise_reject().

  EINA_API Eina_Error eina_error_find (const char * msg)

Finds the Eina_Error corresponding to a message string. This function attempts to match msg with its corresponding Eina_Error value. If no such value is found, 0 is returned.

Parameters
    msg The error message string to match (NOT NULL)

Returns
    The Eina_Error matching msg, otherwise 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().

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Author

Generated automatically by Doxygen for EFL from the source code.