Skip to content

W
White Rabbit Trigger Distribution
Commit e0b366cb authored by Dimitris Lampridis's avatar Dimitris Lampridis
Browse files
Options

[doc] wip

parent d64db65c
Hide whitespace changes
Inline Side-by-side
Showing with 111 additions and 29 deletions
doc/usage_clib.rst
View file @ e0b366cb
......@@ -8,6 +8,13 @@ C Library
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
......@@ -15,17 +22,75 @@ 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
......@@ -34,12 +99,18 @@ Initialisation API
#include <libwrtd.h>
int main(void) {
struct wrtd_dev *wrtd;
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);
}
......@@ -48,6 +119,30 @@ Initialisation API
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
......@@ -55,20 +150,22 @@ Attributes
.. doxygenenum:: wrtd_attr
.. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID
.. _api_attr_func:
Functions
+++++++++
.. doxygenstruct:: wrtd_tstamp
:members:
.. 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
......
software/lib/libwrtd.c
View file @ e0b366cb
......@@ -16,12 +16,12 @@
/**
* @defgroup Base
* Functions to manage the basic device and library configuration.
* Functions to manage the basic Node and library configuration.
* @{
*/
/**
* Initialize the WRTD device and obtain the WRTD device token.
* Initialize the WRTD Node and obtain the WRTD device token.
*
* @param[in] resource_name Underlying MockTurtle device ID in
* the form of **MTxxx** or **trtl-xxxx**.
......@@ -115,7 +115,7 @@ wrtd_status wrtd_init(const char *resource_name,
}
/**
* Close a WRTD device and release all resources.
* Close a WRTD Node and release all resources.
*
* @param[in] wrtd Device token.
* @return #wrtd_status
......@@ -136,7 +136,7 @@ wrtd_status wrtd_close(wrtd_dev *wrtd)
}
/**
* Reset a WRTD device. This will remove all defined Alarms and Rules.
* Reset a WRTD Node. This will remove all defined Alarms and Rules.
*
* @param[in] wrtd Device token.
* @return #wrtd_status
......@@ -175,7 +175,9 @@ wrtd_status wrtd_reset(wrtd_dev *wrtd)
* @param[out] error_code #wrtd_status pointer to return the error code. Ignored if NULL.
* @param[in] error_description_buffer_size Size of pre-allocated `error_description` buffer.
* @param[out] error_description Buffer to store the detailed error message string.
* @return #wrtd_status. See also IVI-3.2, section 3.1.2.1.
* @return #wrtd_status. However, if the buffer size parameter is 0, then this function returns
* instead a positive value, indicating the minimum buffer size necessary to fit the full message.
* See also IVI-3.2, section 3.1.2.1.
*/
wrtd_status wrtd_get_error(wrtd_dev *wrtd,
wrtd_status *error_code,
......
software/lib/libwrtd.h
View file @ e0b366cb
......@@ -23,10 +23,8 @@ typedef struct wrtd_dev wrtd_dev;
/**
* @enum wrtd_status
* White Rabbit Trigger Distribution error codes.
*
* Names and values inspired by IVI-3.2 and IVI-3.15.
* Error codes can be converted to strings by means of
* the #wrtd_error_message function. The latest error can
* be retrieved with the #wrtd_get_error function.
*/
typedef enum wrtd_status {
/** No error. */
......@@ -91,23 +89,8 @@ typedef enum wrtd_status {
/**
* @enum wrtd_attr
* White Rabbit Trigger Distribution attributes.
* Names and values inspired by IVI-3.2 and IVI-3.15.
*
* Attributes can be of type `bool`, `int32`, `string`, or `tstamp` (#wrtd_tstamp).
* Access can be `RW` (read/write), `RO` (read-only) or `WO` (write-only).
* Furthermore an attribute can be related to a specific `alarm`, `rule`, `application`,
* or it can be `global` (it applies to the whole device).
*
* Attributes are accessed by means of the following API functions, depending
* on their type:
* - #wrtd_set_attr_bool
* - #wrtd_get_attr_bool
* - #wrtd_set_attr_int32
* - #wrtd_get_attr_int32
* - #wrtd_set_attr_string
* - #wrtd_get_attr_string
* - #wrtd_set_attr_tstamp
* - #wrtd_get_attr_tstamp
* Names and values inspired by IVI-3.2 and IVI-3.15.
*/
typedef enum wrtd_attr {
/** Same as *IVI_INSTR_SPECIFIC_ATTR_BASE*. */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment