diff options
Diffstat (limited to 'docs/user/concepts.rst')
-rw-r--r-- | docs/user/concepts.rst | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/docs/user/concepts.rst b/docs/user/concepts.rst new file mode 100644 index 0000000..4afdd6e --- /dev/null +++ b/docs/user/concepts.rst @@ -0,0 +1,80 @@ +.. _user-concepts: + +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: + +.. code-block:: c + + #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 :c:type:`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: + +.. c:function:: char const *casio_error_name(int code) + + Get a pointer to the error name (which you shall not free). + +.. c:function:: char const *casio_error_desc(int code) + + 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. |