Handling errors
Errors are reported by Cowl via return values (such as cowl_ret
), or by returning NULL
on allocation errors. Sometimes this may not be enough, such as when reading ontology documents:
in these cases, Cowl lets you setup CowlErrorHandler
instances, which grant more
fine-grained control over errors.
Error handlers can be either provided locally to specific objects (such as via
cowl_manager_set_error_handler()
), or you can opt to specify a global
error handler via cowl_set_error_handler()
. If you do both, Cowl prioritizes
local error handlers, as you would expect.
-
struct CowlErrorHandler
Provides a mechanism for error handling.
Public Members
-
void *ctx
Error handler context, can be anything.
-
void (*handle_error)(void *ctx, CowlError const *error)
Pointer to a function called when an error occurs.
- Param ctx:
Error handler context.
- Param error:
Error.
-
void (*free)(void *ctx)
Pointer to a resource deallocator function for the context.
Note
Can be NULL if the context does not need to release resources.
- Param ctx:
Error handler context.
-
void *ctx
-
struct CowlError
Error data structure.
-
struct CowlErrorLoc
Error location.
Public Members
-
CowlString *source
Location of the ontology where the error occurred.
-
CowlString *source
-
CowlString *cowl_error_to_string(CowlError const *error)
Returns a human-readable string representation of the specified error.
Note
You must release the returned object via
cowl_release()
.- Parameters:
error – The error.
- Returns:
String representation, or NULL on error.
-
UString cowl_error_to_ustring(CowlError const *error)
Returns a human-readable string representation of the specified error.
Note
The returned object must be destroyed by calling
ustring_deinit()
.- Parameters:
error – The error.
- Returns:
String representation, or ustring_null on error.
-
cowl_ret cowl_handle_error(cowl_ret code, UString desc, CowlAny *origin)
Handles an error by using the most specific error handler available.
- Parameters:
code – Error code.
desc – Error description.
origin – Object that originated the error.
- Returns:
Error code.
-
cowl_ret cowl_handle_syntax_error(UString desc, CowlAny *origin, CowlErrorLoc loc)
Handles a syntax error via the most specific error handler available.
- Parameters:
desc – Error description.
origin – Object that originated the error.
loc – Error location.
- Returns:
Error code.
-
cowl_ret cowl_handle_error_code(cowl_ret code, CowlAny *origin)
Handles a generic error of the specified type via the most specific error handler available.
- Parameters:
code – Error code.
origin – Object that originated the error.
- Returns:
Error code.
-
cowl_ret cowl_handle_stream_error(ustream_ret code, CowlAny *origin)
Handles an IO stream error via the most specific error handler available.
- Parameters:
code – Error code.
origin – Object that originated the error.
- Returns:
Error code.