.. _clib:

C Library
=========

.. _api_error:

Error Handling API
------------------

Every function in the WRTD C library returns an :ref:`error code <api_error_codes>` of type
:cpp:type:`wrtd_status`. The Error Handling API provides :ref:`functions <api_error_func>` for
retrieving and interpreting errors from the Node.

Error codes can be converted to strings by means of the :cpp:func:`wrtd_error_message` function. The
latest error can be retrieved with the :cpp:func:`wrtd_get_error` function.

.. _api_error_codes:

Error Codes
+++++++++++

.. doxygenenum:: wrtd_status

.. _api_error_func:

Functions
+++++++++

.. doxygenfunction:: wrtd_get_error
.. code-block:: c

   #include <libwrtd.h>

   int main(void) {
           wrtd_dev *wrtd;
           wrtd_status status, err_code;
           char *err_msg;
           int buf_size;

           status = wrtd_init("MT01", false, NULL, &wrtd);

           if (status != WRTD_SUCCESS) {
                   buf_size = wrtd_get_error(wrtd, NULL, 0, NULL);
                   err_msg = calloc(sizeof(char), buf_size);
                   wrtd_get_error(wrtd, &err_code, buf_size, err_msg)
                   printf("ERROR: %d, %s\n", err_code, err_msg);
                   return status;
           }

           wrtd_close(wrtd);

           return 0;
   }

.. doxygenfunction:: wrtd_error_message
.. code-block:: c

   #include <libwrtd.h>

   int main(void) {
           wrtd_dev *wrtd;
           wrtd_status status;
           char err_msg[256];

           status = wrtd_init("MT01", false, NULL, &wrtd);

           if (status != WRTD_SUCCESS) {
                   wrtd_error_message(wrtd, status, err_msg);
                   printf("ERROR: %d, %s\n", status, err_msg);
                   return status;
           }

           wrtd_close(wrtd);

           return 0;
   }

.. _api_init:

Initialisation API
------------------

The initialisation API provides the functions to initiate/close a connection to the :ref:`node`, as
well as to reset it.

:cpp:func:`wrtd_init` is the first function that should be called by any program, in order to obtain
the "device token" to be used in all subsequent function calls. See also :ref:`node_id` on how to
figure out the ``resource_name`` of a :ref:`node`.

Conversely, :cpp:func:`wrtd_close` should be called before exiting the program. No further WRTD
library functions can be used after that.

.. doxygenfunction:: wrtd_init
.. doxygenfunction:: wrtd_close
.. doxygenfunction:: wrtd_reset
.. code-block:: c

   #include <libwrtd.h>

   int main(void) {
           wrtd_dev *wrtd;
           wrtd_status status;

           status = wrtd_init("MT01", false, NULL, &wrtd);

           /* This will erase all defined rules and alarms
              from the Node, so it might not be what you want
              the program to do every time it is executed. */
           wrtd_reset(wrtd);

           /* Do some more work here... */

           wrtd_close(wrtd);
   }

.. _api_attr:

Attribute Handling API
----------------------

Attributes can be of type ``bool``, ``int32``, ``string``, or ``tstamp`` (:cpp:class:`wrtd_tstamp`).

Access can be ``RW`` (read/write), ``RO`` (read-only) or ``WO`` (write-only).

Furthermore they can be related to a specific ``alarm``, ``rule``, ``application``, or they can be
``global`` (they apply to the whole device).

:ref:`Attributes <api_attr_id>` are accessed by means of the following :ref:`functions
<api_attr_func>`, depending on their type:

* :cpp:func:`wrtd_set_attr_bool`
* :cpp:func:`wrtd_get_attr_bool`
* :cpp:func:`wrtd_set_attr_int32`
* :cpp:func:`wrtd_get_attr_int32`
* :cpp:func:`wrtd_set_attr_string`
* :cpp:func:`wrtd_get_attr_string`
* :cpp:func:`wrtd_set_attr_tstamp`
* :cpp:func:`wrtd_get_attr_tstamp`

When using one of the above functions to access a "global" :ref:`attribute`, the :ref:`rep_cap_id`
parameter should be set to :c:macro:`WRTD_GLOBAL_REP_CAP_ID`.

.. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID

.. _api_attr_id:

Attributes
++++++++++

.. doxygenenum:: wrtd_attr

.. _api_attr_func:

Functions
+++++++++

.. doxygenfunction:: wrtd_set_attr_bool
.. doxygenfunction:: wrtd_get_attr_bool

.. doxygenfunction:: wrtd_set_attr_int32
.. doxygenfunction:: wrtd_get_attr_int32

.. doxygenfunction:: wrtd_set_attr_string
.. doxygenfunction:: wrtd_get_attr_string

.. doxygenstruct:: wrtd_tstamp
                   :members:
.. doxygenfunction:: wrtd_set_attr_tstamp
.. doxygenfunction:: wrtd_get_attr_tstamp

.. _api_log:

Event Logging API
-----------------

.. doxygendefine:: WRTD_LOG_ENTRY_SIZE

.. doxygenfunction:: wrtd_clear_event_log_entries
.. doxygenfunction:: wrtd_get_next_event_log_entry

.. _api_alarm:

Alarms API
----------

.. doxygenfunction:: wrtd_add_alarm
.. doxygenfunction:: wrtd_disable_all_alarms
.. doxygenfunction:: wrtd_remove_alarm
.. doxygenfunction:: wrtd_remove_all_alarms
.. doxygenfunction:: wrtd_get_alarm_name

.. _api_rule:

Rules API
---------

.. doxygenfunction:: wrtd_add_rule
.. doxygenfunction:: wrtd_disable_all_rules
.. doxygenfunction:: wrtd_remove_rule
.. doxygenfunction:: wrtd_remove_all_rules
.. doxygenfunction:: wrtd_get_rule_name
.. doxygenfunction:: wrtd_reset_rule_stats

.. _api_app:

Applications API
----------------

.. doxygenfunction:: wrtd_get_fw_name
