Configuration

Initialization

Before making any API call, you must invoke cowl_init(), which is needed to initialize the library’s internal state. This state is meant to be application-scoped, therefore calling cowl_deinit() is generally unnecessary. If you need to do so, you must not use previously retrieved objects as they will be invalid.

cowl_ret cowl_init(void)

Initializes the library.

Note

It’s mandatory to call this function before making any other function call.

Returns:

Return code.

void cowl_deinit(void)

Deinitializes the library.

Note

Calling this function releases any resource loaded when the library was initialized. You must not use objects retrieved before deinitializing the library, even if you later re-initialize it.

Handlers and defaults

Global/default behaviour of the API can be configured via these functions. In general, you will still be able to provide local overrides for specific objects.

CowlReader *cowl_get_reader(void)

Gets the default reader.

Returns:

The default reader.

void cowl_set_reader(CowlReader reader)

Sets the default reader.

Note

This function must be called again if you reinitialize library API after deinitializing it.

Parameters:

  • reader – The reader.

CowlWriter *cowl_get_writer(void)

Gets the default writer.

Returns:

The default writer.

void cowl_set_writer(CowlWriter writer)

Sets the default writer.

Note

This function must be called again if you reinitialize the library after deinitializing it.

Parameters:

  • writer – The writer.

CowlErrorHandler *cowl_get_error_handler(void)

Gets the global error handler.

Returns:

The global error handler.

void cowl_set_error_handler(CowlErrorHandler handler)

Sets the global error handler.

Note

This function must be called again if you reinitialize the library after deinitializing it.

Parameters:

  • handler – The error handler.

Library version

The library version can be retrieved via the following functions, allowing for some degree of feature checking.

UVersion cowl_get_version(void)

Returns the version of the library.

Returns:

Library version.

CowlString *cowl_get_version_string(void)

Returns the string representation of the library version.

Note

You must release the returned object via cowl_release().

Returns:

String representation.