avis/errors.h File Reference

Detailed Description

Error handling.

#include <stdlib.h>
#include <avis/stdtypes.h>
#include <avis/defs.h>

Go to the source code of this file.

Data Structures

struct ElvinError

Error reporting information for the Avis client library. More...

Defines

#define ELVIN_ERROR_BASE   0

#define ELVIN_ERRNO_BASE   10000

#define ELVIN_HOST_ERROR_BASE   20000

#define ELVIN_ERROR_NONE   0

#define ELVIN_ERROR_INTERNAL   (ELVIN_ERROR_BASE + 1)

#define ELVIN_ERROR_PROTOCOL   (ELVIN_ERROR_BASE + 2)

#define ELVIN_ERROR_CONNECTION_CLOSED   (ELVIN_ERROR_BASE + 3)

#define ELVIN_ERROR_INVALID_URI   (ELVIN_ERROR_BASE + 4)

#define ELVIN_ERROR_SYNTAX   (ELVIN_ERROR_BASE + 5)

#define ELVIN_ERROR_TRIVIAL_EXPRESSION   (ELVIN_ERROR_BASE + 6)

#define ELVIN_ERROR_NACK   (ELVIN_ERROR_BASE + 7)

#define ELVIN_ERROR_USAGE   (ELVIN_ERROR_BASE + 8)

#define ELVIN_ERROR_TIMEOUT   (ELVIN_ERROR_BASE + 9)

#define ELVIN_ERROR_ROUTER_FAILURE   (ELVIN_ERROR_BASE + 10)

#define avis_emalloc(size)   do_avis_emalloc ((size), __FILE__, __LINE__)

#define avis_estrdup(str)   do_avis_estrdup ((str), __FILE__, __LINE__)

#define ELVIN_EMPTY_ERROR   {ELVIN_ERROR_NONE, NULL}

An empty error instance.

#define elvin_error_reset(error)   (elvin_error_free (error))

Free any resources and reset the error info back to OK state.

#define on_error_return_false(stat)   on_error_return (stat, false)

Macro statement to return false if an error is set in the "error" variable inside the current scope.

#define on_error_return(stat, retval)   {stat; if (elvin_error_occurred (error)) return (retval);}

Macro statement to return a given value if an error is set in the "error" variable inside the current scope.

#define host_to_elvin_error(code)   (ELVIN_HOST_ERROR_BASE + (code))

Convert the h_errno error code generated by gethostbyname () etc to an error code that can be used with elvin_error_set().

#define errno_to_elvin_error(code)   (ELVIN_ERRNO_BASE + (code))

Translate a system errno error code into a code that can be used with elvin_error_set().

#define elvin_error_ok(error)   ((error)->code == ELVIN_ERROR_NONE)

True if no error has occurred.

#define elvin_error_occurred(error)   (!elvin_error_ok (error))

True if an error has occurred.

Functions

AVIS_PUBLIC void * do_avis_emalloc (size_t size, const char *file, int line)

AVIS_PUBLIC char * do_avis_estrdup (const char *str, const char *file, int line)

AVIS_PUBLIC void elvin_error_free (ElvinError *error)

Free any resources allocated to an error instance and reset the error code.

AVIS_PUBLIC void elvin_error_init (ElvinError *error)

Initialise an uninitialised error instance.

AVIS_PUBLIC void elvin_perror (const char *tag, ElvinError *error)

Like perror () but taking error info from an ElvinError instance.

AVIS_PUBLIC bool elvin_error_from_errno (ElvinError *error)

Load an error status from the system's "errno" error variable and strerror () function.

AVIS_PUBLIC bool elvin_error_set (ElvinError *error, int code, const char *message,...)

Signal an error has occurred.

Define Documentation

#define avis_emalloc ( size ) do_avis_emalloc ((size), __FILE__, __LINE__)

#define avis_estrdup ( str ) do_avis_estrdup ((str), __FILE__, __LINE__)

#define ELVIN_EMPTY_ERROR {ELVIN_ERROR_NONE, NULL}

An empty error instance.

This can be assigned to an error instance to initialise it on declaration rather than using elvin_error_init() (which is the other method). Regardless of initialisation method, elvin_error_free() should be used to release any resources allocated before disposing.

#define ELVIN_ERRNO_BASE 10000

#define ELVIN_ERROR_BASE 0

#define ELVIN_ERROR_CONNECTION_CLOSED (ELVIN_ERROR_BASE + 3)

#define ELVIN_ERROR_INTERNAL (ELVIN_ERROR_BASE + 1)

#define ELVIN_ERROR_INVALID_URI (ELVIN_ERROR_BASE + 4)

#define ELVIN_ERROR_NACK (ELVIN_ERROR_BASE + 7)

#define ELVIN_ERROR_NONE 0

#define elvin_error_occurred ( error ) (!elvin_error_ok (error))

True if an error has occurred.

#define elvin_error_ok ( error ) ((error)->code == ELVIN_ERROR_NONE)

True if no error has occurred.

#define ELVIN_ERROR_PROTOCOL (ELVIN_ERROR_BASE + 2)

#define elvin_error_reset ( error ) (elvin_error_free (error))

Free any resources and reset the error info back to OK state.

#define ELVIN_ERROR_ROUTER_FAILURE (ELVIN_ERROR_BASE + 10)

#define ELVIN_ERROR_SYNTAX (ELVIN_ERROR_BASE + 5)

#define ELVIN_ERROR_TIMEOUT (ELVIN_ERROR_BASE + 9)

#define ELVIN_ERROR_TRIVIAL_EXPRESSION (ELVIN_ERROR_BASE + 6)

#define ELVIN_ERROR_USAGE (ELVIN_ERROR_BASE + 8)

#define ELVIN_HOST_ERROR_BASE 20000

#define errno_to_elvin_error ( code ) (ELVIN_ERRNO_BASE + (code))

Translate a system errno error code into a code that can be used with elvin_error_set().

#define host_to_elvin_error ( code ) (ELVIN_HOST_ERROR_BASE + (code))

Convert the h_errno error code generated by gethostbyname () etc to an error code that can be used with elvin_error_set().

#define on_error_return	(	stat,
		retval		)	{stat; if (elvin_error_occurred (error)) return (retval);}

Macro statement to return a given value if an error is set in the "error" variable inside the current scope.

Parameters:

	stat	The statement to execute before the test.
	retval	The value to return on error.

Function Documentation

AVIS_PUBLIC void* do_avis_emalloc	(	size_t	size,
		const char *	file,
		int	line
	)

AVIS_PUBLIC char* do_avis_estrdup	(	const char *	str,
		const char *	file,
		int	line
	)

AVIS_PUBLIC void elvin_error_free ( ElvinError * error )

Free any resources allocated to an error instance and reset the error code.

The error instance may be reused after this call.

See also:: elvin_error_reset()

AVIS_PUBLIC bool elvin_error_from_errno ( ElvinError * error )

Load an error status from the system's "errno" error variable and strerror () function.

Parameters:

error

The error to affect.

See also:: elvin_error_set()

AVIS_PUBLIC void elvin_error_init ( ElvinError * error )

Initialise an uninitialised error instance.

See also:: ELVIN_EMPTY_ERROR
elvin_error_reset()

AVIS_PUBLIC bool elvin_error_set	(	ElvinError *	error,
		int	code,
		const char *	message,
			...
	)

Signal an error has occurred.

If an error is already set, this has no effect (see elvin_error_reset() if you want to override any existing error status).

Parameters:

	error	The error to target.
	code	The error code. One of the ELVIN_ERROR_* defines or host_to_elvin_error().
	message	The message, possibly including printf-style format placeholders.
	...	The rest of the arguments if message contains format placeholders.

Returns:: Returns false as a convenience so that this can be used in return statements indicating an error.

See also:: elvin_error_from_errno()
elvin_error_free()

AVIS_PUBLIC void elvin_perror	(	const char *	tag,
		ElvinError *	error
	)

Like perror () but taking error info from an ElvinError instance.


Data Structures
struct	ElvinError
	Error reporting information for the Avis client library. More...
Defines
#define	ELVIN_ERROR_BASE 0
#define	ELVIN_ERRNO_BASE 10000
#define	ELVIN_HOST_ERROR_BASE 20000
#define	ELVIN_ERROR_NONE 0
#define	ELVIN_ERROR_INTERNAL (ELVIN_ERROR_BASE + 1)
#define	ELVIN_ERROR_PROTOCOL (ELVIN_ERROR_BASE + 2)
#define	ELVIN_ERROR_CONNECTION_CLOSED (ELVIN_ERROR_BASE + 3)
#define	ELVIN_ERROR_INVALID_URI (ELVIN_ERROR_BASE + 4)
#define	ELVIN_ERROR_SYNTAX (ELVIN_ERROR_BASE + 5)
#define	ELVIN_ERROR_TRIVIAL_EXPRESSION (ELVIN_ERROR_BASE + 6)
#define	ELVIN_ERROR_NACK (ELVIN_ERROR_BASE + 7)
#define	ELVIN_ERROR_USAGE (ELVIN_ERROR_BASE + 8)
#define	ELVIN_ERROR_TIMEOUT (ELVIN_ERROR_BASE + 9)
#define	ELVIN_ERROR_ROUTER_FAILURE (ELVIN_ERROR_BASE + 10)
#define	avis_emalloc(size) do_avis_emalloc ((size), __FILE__, __LINE__)
#define	avis_estrdup(str) do_avis_estrdup ((str), __FILE__, __LINE__)
#define	ELVIN_EMPTY_ERROR {ELVIN_ERROR_NONE, NULL}
	An empty error instance.
#define	elvin_error_reset(error) (elvin_error_free (error))
	Free any resources and reset the error info back to OK state.
#define	on_error_return_false(stat) on_error_return (stat, false)
	Macro statement to return false if an error is set in the "error" variable inside the current scope.
#define	on_error_return(stat, retval) {stat; if (elvin_error_occurred (error)) return (retval);}
	Macro statement to return a given value if an error is set in the "error" variable inside the current scope.
#define	host_to_elvin_error(code) (ELVIN_HOST_ERROR_BASE + (code))
	Convert the h_errno error code generated by gethostbyname () etc to an error code that can be used with elvin_error_set().
#define	errno_to_elvin_error(code) (ELVIN_ERRNO_BASE + (code))
	Translate a system errno error code into a code that can be used with elvin_error_set().
#define	elvin_error_ok(error) ((error)->code == ELVIN_ERROR_NONE)
	True if no error has occurred.
#define	elvin_error_occurred(error) (!elvin_error_ok (error))
	True if an error has occurred.
Functions
AVIS_PUBLIC void *	do_avis_emalloc (size_t size, const char *file, int line)
AVIS_PUBLIC char *	do_avis_estrdup (const char str, const char file, int line)
AVIS_PUBLIC void	elvin_error_free (ElvinError *error)
	Free any resources allocated to an error instance and reset the error code.
AVIS_PUBLIC void	elvin_error_init (ElvinError *error)
	Initialise an uninitialised error instance.
AVIS_PUBLIC void	elvin_perror (const char tag, ElvinError error)
	Like perror () but taking error info from an ElvinError instance.
AVIS_PUBLIC bool	elvin_error_from_errno (ElvinError *error)
	Load an error status from the system's "errno" error variable and strerror () function.
AVIS_PUBLIC bool	elvin_error_set (ElvinError error, int code, const char message,...)
	Signal an error has occurred.