From 846966407541e07d9b08e26b446afba754df76a0 Mon Sep 17 00:00:00 2001 From: Olof hagsand Date: Sun, 10 Oct 2021 18:48:10 +0200 Subject: [PATCH] Updated contribution and statedata callback docs --- CONTRIBUTING.md | 23 ++++++++++++++--------- apps/backend/backend_plugin.c | 10 +++++----- lib/clixon/clixon_plugin.h | 15 +++++++++++++-- 3 files changed, 32 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23044340..35ce420c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,7 +68,7 @@ In some cases, Clixon uses three-value returns as follows: ### Return values Clixon uses goto:s only to get a single point of exit functions as follows:: - +``` { int retval = -1; @@ -77,6 +77,7 @@ Clixon uses goto:s only to get a single point of exit functions as follows:: done: return retval } +``` Notes: @@ -98,24 +99,28 @@ How to document the code: * This is a detailed description * spanning several lines. * + * @param[in] src This is a description of the first parameter + * @param[in,out] dest This is a description of the second parameter + * @retval 0 This is a description of the return value + * @retval -1 This is a description of another return value + * * Example usage: * @code * fn(a, &b); * @endcode * - * @param[in] src This is a description of the first parameter - * @param[in,out] dest This is a description of the second parameter - * @retval 0 This is a description of the return value - * @retval -1 This is a description of another return value * @see See also this function */ ``` ## Testing -For a new feature, you need to write [a CI test](https://github.com/clicon/clixon/blob/master/test/README.md), including some functionality tests and preferably some negative tests. Tests are then run automatically as regression on commit [by github actions](https://github.com/clicon/clixon/actions/). +For a new feature, it is important to write (or extend) [a clixon test](https://github.com/clicon/clixon/blob/master/test/README.md), including some functionality tests and preferably some negative tests. Tests are then run automatically as regression on commit [by github actions](https://github.com/clicon/clixon/actions/). These tests are also the basis for more extensive CI tests run by the project which -include [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test), [vagrant tests on other platforms](https://github.com/clicon/clixon/tree/master/test/vagrantvalgrind), [coverage tests](https://app.codecov.io/gh/clicon/clixon) and occasional [fuzzing with AFL](https://github.com/clicon/clixon/tree/master/fuzz). - -In particular, a new feature must pass the [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test). \ No newline at end of file +include: +- [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test). Running the .mem.sh for cli, backend,netconf and restconf is mandatory. +- [Vagrant tests on other operating systems](https://github.com/clicon/clixon/tree/master/test/vagrant]. Other OS:s include ubuntu, centos and freebsd +- [CI on other platforms](https://github.com/clicon/clixon/tree/master/test/cicd]. Other platforms include x86-64, 32-bit i686, and armv71 +- [coverage tests](https://app.codecov.io/gh/clicon/clixon) +- [fuzzing with AFL](https://github.com/clicon/clixon/tree/master/test/fuzz) (occasionally) diff --git a/apps/backend/backend_plugin.c b/apps/backend/backend_plugin.c index e9d39588..0542c655 100644 --- a/apps/backend/backend_plugin.c +++ b/apps/backend/backend_plugin.c @@ -453,11 +453,11 @@ clixon_plugin_lockdb_all(clicon_handle h, */ int clixon_pagination_cb_call(clicon_handle h, - char *xpath, - int locked, - uint32_t offset, - uint32_t limit, - cxobj *xstate) + char *xpath, + int locked, + uint32_t offset, + uint32_t limit, + cxobj *xstate) { int retval = -1; pagination_data_t pd; diff --git a/lib/clixon/clixon_plugin.h b/lib/clixon/clixon_plugin.h index 5a700c9b..62168e2d 100644 --- a/lib/clixon/clixon_plugin.h +++ b/lib/clixon/clixon_plugin.h @@ -196,13 +196,24 @@ typedef int (plgauth_t)(clicon_handle h, void *req, clixon_auth_type_t auth_type */ typedef int (plgreset_t)(clicon_handle h, const char *db); -/* Plugin statedata +/* Provide state data from plugin + * + * A complete valid XML tree is created by the plugin and sent back via xtop, which is merged + * into a complete state tree by the system. + * The plugin should ensure that xpath is matched (using namspace context nsc) + * This callback may be replaced with a "dispatcher" type API in the future where the + * XPath binding is stricter, similar to the pagination API. + * * @param[in] h Clicon handle * @param[in] xpath Part of state requested * @param[in] nsc XPATH namespace context. * @param[out] xtop XML tree where statedata is added * @retval -1 Fatal error * @retval 0 OK + * + * @note The system will make an xpath check and filter out non-matching trees + * @note The system does not validate the xml, unless CLICON_VALIDATE_STATE_XML is set + * @see clixon_pagination_cb_register for special paginated state data callback */ typedef int (plgstatedata_t)(clicon_handle h, cvec *nsc, char *xpath, cxobj *xtop); @@ -293,7 +304,7 @@ struct clixon_plugin_api{ plgdaemon_t *cb_daemon; /* Plugin daemonized (always called) */ plgreset_t *cb_reset; /* Reset system status */ - plgstatedata_t *cb_statedata; /* Get state data from plugin (backend only) */ + plgstatedata_t *cb_statedata; /* Provide state data XML from plugin */ plglockdb_t *cb_lockdb; /* Database lock changed state */ trans_cb_t *cb_trans_begin; /* Transaction start */ trans_cb_t *cb_trans_validate; /* Transaction validation */