Error Management

Data Structures
struct	bj_error

Macros
#define	bj_error_code_is_user   (c) (((c >> 24) & 0xFF) > 0x00)
#define	bj_error_code_kind(c)
#define	BJ_ERROR_MESSAGE_MAX_LEN   127

Enumerations

enum

bj_error_code {   BJ_ERROR_NONE = 0x00000000 , BJ_ERROR = 0x00000001 , BJ_ERROR_UNSUPPORTED = 0x00000101 , BJ_ERROR_NOT_IMPLEMENTED = 0x00000201 ,   BJ_ERROR_SYSTEM = 0x00000002 , BJ_ERROR_FILE_NOT_FOUND = 0x00000102 , BJ_ERROR_CANNOT_ALLOCATE = 0x00000202 , BJ_ERROR_INITIALIZE = 0x00000302 ,   BJ_ERROR_DISPOSE = 0x00000302 , BJ_ERROR_IO = 0x00000003 , BJ_ERROR_CANNOT_READ_FILE = 0x00000103 , BJ_ERROR_INVALID_DATA = 0x00000004 ,   BJ_ERROR_INVALID_FORMAT = 0x00000104 , BJ_ERROR_INCORRECT_VALUE = 0x00000204 , BJ_ERROR_VIDEO = 0x00000005 , BJ_ERROR_AUDIO = 0x00000006 }

Functions
void	bj_set_error (bj_error **p_error, uint32_t code, const char *message)
bj_bool	bj_check_error (const bj_error *p_error, uint32_t code)
bj_bool	bj_forward_error (bj_error *p_source, bj_error **p_destination)
void	bj_clear_error (bj_error **p_error)

Detailed Description

Recoverable error handling facilities.

This API provides a simple mechanism for communicating recoverable errors from callee to caller.

When a function may fail, it takes a bj_error pointer as a parameter. The failing function may fill in this value to communicate error while the caller can check for the value of bj_error_code to check if any error occurred:

    bj_error* error = 0;
 
    function_returning_error(&error);
 
    if(error != 0) {
        bj_info("There was an error");
    }

Use bj_set_error from inside a custom function that may result in an error:

void function_returning_error(bj_error** error) {
    bj_set_error(error, CODE, "An error occured");
}

---

Data Structure Documentation

bj_error

struct bj_error

Error structure.

Described any error reported by a potentially failing function.

Banjo-internals guarantee code to be a value of bj_error_code.

Data Fields
uint32_t	code	Error code.
char	message[127+1]	Optional error description.

Macro Definition Documentation

bj_error_code_is_user

#define bj_error_code_is_user   (c) (((c >> 24) & 0xFF) > 0x00)

Checks if an error code is user-provided or Banjo.

All Banjo error codes are guaranted to have their most signigicant byte set to 0x00. This helper macro evaluates to BJ_TRUE if the provided error is user-defined.

Parameters

c	The error code

bj_error_code_kind

#define bj_error_code_kind

(

c

)

Value:

(c & 0x000000FF)

Evaluates to an error code kind.

Banjo error codes are hierarchical. The least significant byte is the same value for all error codes of the same kind, and corresponds to the generic error code value of the said kind.

This helper macro evaluates to the kind error code of any given code.

For example, bj_error_code_kind(BJ_ERROR_CANNOT_ALLOCATE) evaluates to BJ_ERROR_OS.

Parameters

c	The error code

BJ_ERROR_MESSAGE_MAX_LEN

#define BJ_ERROR_MESSAGE_MAX_LEN   127

Maximum number of characters an error message in bj_error can hold.

Enumeration Type Documentation

bj_error_code

enum bj_error_code

A numeric representation of an error in Banjo.

Within a bj_error object, the first field is a uint32_t value indicating the type of error encountered.

An error code is a 32-bit value composed as follows:

• The most significant byte is always 0x00.
• The least significant byte represents the error kind.
• The two middle bytes represent the specific error code.

For example, BJ_ERROR_INCORRECT_VALUE is 0x204, where:

• The most significant byte is 0x00,
• The next two bytes are 0x0002,
• The least significant byte is 0x04.

Internal specifier

The most significant byte is always 0x00 for Banjo errors. User applications can set a different value to this byte to identify the origin of the error code.

You can use bj_error_code_is_user to check if an error code is defined outside of Banjo.

Error Kind

The error kind is a numerical value set on the least significant byte that is the same for all values of the same category.

For example, BJ_ERROR_INVALID_FORMAT and BJ_ERROR_INCORRECT_VALUE have the same kind, which is equal to 0x04.

Every error kind has its own error code, represented by a uint32_t with only the least significant byte set. For example: BJ_ERROR_INVALID_DATA.

You can use bj_error_code_kind to get the error kind code of any error code.

Enumerator
BJ_ERROR_NONE	No Error.
BJ_ERROR	General Error (unspecified)
BJ_ERROR_UNSUPPORTED	Unsupported operation error.
BJ_ERROR_NOT_IMPLEMENTED	Unsupported operation error.
BJ_ERROR_SYSTEM	Generic OS error.
BJ_ERROR_FILE_NOT_FOUND	The requested file was not found.
BJ_ERROR_CANNOT_ALLOCATE	Cannot allocate the specified memory block.
BJ_ERROR_INITIALIZE	A system component cannot be initalized.
BJ_ERROR_DISPOSE	A system component cannot be terminated properly.
BJ_ERROR_IO	IO-related errors.
BJ_ERROR_CANNOT_READ_FILE	Error while attempting to read a file.
BJ_ERROR_INVALID_DATA	Incorrect data.
BJ_ERROR_INVALID_FORMAT	Data format does not match expected format.
BJ_ERROR_INCORRECT_VALUE	Mismatched expected value.
BJ_ERROR_VIDEO	Error while running video layer.
BJ_ERROR_AUDIO	Error while running audio layer.

Function Documentation

bj_check_error()

bj_bool bj_check_error	(	const bj_error *	p_error,
		uint32_t	code )

Checks if the given error matches the error code.

If p_error is 0, return false, which must be interpreted as "no error". Otherwise, returns true only if p_error->code == code.

Parameters

p_error	The error to check
code	The error code to match

Returns

true if p_error matches code, false otherwise.

bj_clear_error()

void bj_clear_error

(

bj_error **

p_error

)

Clears the given error location.

Parameters

p_error

The error to clear.

bj_forward_error()

bj_bool bj_forward_error	(	bj_error *	p_source,
		bj_error **	p_destination )

Forward an error into another error location.

This function is used when calling an error-returning function from another error-returning function.

If p_source contains a non-zero error, it is moved to p_destination. If *p_destination already contains an error, p_source is only logged (using bj_error).

Parameters

p_source	The source error.
p_destination	The destination error pointer.

Returns

BJ_TRUE if both p_source and p_destination are non-zero. When this happens, this means there was an error to propagate and that the caller asked for it.

bj_set_error()

void bj_set_error	(	bj_error **	p_error,
		uint32_t	code,
		const char *	message )

Fills in a bj_error object with given code and message.

Parameters

p_error	The error to fill in.
code	Error code.
message	The error message to set.

If p_error is null, the function does nothing.

If p_error is not null, the function only stored the error if code == 0. Otherwise, code and message are only reported as logs.

message must point to a 0-terminated C-string of at max BJ_ERROR_MESSAGE_MAX_LEN character. If the given string is larger, it is truncated to BJ_ERROR_MESSAGE_MAX_LEN and the nul pointer is enforced.