libcasio/docs/user/concepts.rst

libcasio concepts

The library interface follows a certain amount of concepts which makes it consistent.

Namespace

In order to interfere as little as possible with user definitions, the library uses a “namespace” which is represented by prefixes for all of its external declarations, definitions and macros. Even for code that uses libcasio, avoid defining anything with any of these prefixes or you'll get an undefined behaviour.

The reserved prefixes are casio_, CASIO_, libcasio_ and LIBCASIO_.

Structure namespaces

For structures you can access the members, these have as prefixes the structure name in order, once again, to not interfere with user code.

For example, if a struct casio_my_type is defined, all member names will start with casio_my_type_, for example:

#include <libcasio/cdefs.h>
CASIO_STRUCT(casio_my_type, casio_my_type_t)

struct casio_my_type {
    int casio_my_type_a;
    char const *casio_my_type_b;
};

Objects

The library is based around objects and functions for using and managing them. The objects are defined as anonymous structures, which means you can't access the content of these objects directly, you need to use some getters for compatibility.

Errors

Almost all functions that can fail in libcasio return an int, even if they open a handle or descriptor of some kind (which is usually passed by using a pointer to it as a first argument). This integer corresponds to the error that occured in the function, or zero, representing the "everything went fine" error.

The errors that can happen in libcasio are defined in <libcasio/error.h>, although as usual, you should include <libcasio.h> to access the code and utilities.

Some errors are "relative", which means their significance depends on the function that returned it, when others are not. For example, casio_error_op means the function has received arguments that it doesn't manage (sometimes, yet), and it should not be transmitted as is, while casio_error_unknown can be transmitted without any risk.

To get the full list of errors, you should read the header directly. If you simply want to get the error name or description, you can use the following functions:

Get a pointer to the error name (which you shall not free).

Get a pointer to the error description (which you shall not free).

The description string should only be used for displaying the error, as it could be translated in future versions of the library.