diff --git a/apps/backend/backend_client.c b/apps/backend/backend_client.c index b294c4c7..4de0b6ed 100644 --- a/apps/backend/backend_client.c +++ b/apps/backend/backend_client.c @@ -73,6 +73,7 @@ #include "backend_client.h" /*! Find client by session-id + * * @param[in] ce_list List of clients * @param[in] id Session id */ @@ -89,6 +90,7 @@ ce_find_byid(struct client_entry *ce_list, } /*! Stream callback for netconf stream notification (RFC 5277) + * * @param[in] h Clicon handle * @param[in] op 0:event, 1:rm * @param[in] event Event as XML @@ -125,6 +127,7 @@ ce_event_cb(clicon_handle h, } /*! Unlock all db:s of a client and call user unlock calback + * * @see xmldb_unlock_all unlocks, but does not call user callbacks which is a backend thing */ static int @@ -167,9 +170,9 @@ release_all_dbs(clicon_handle h, * @param[in] nsc XML Namespace context for xpath * @param[in,out] xret Existing XML tree, merge x into this * @param[out] xerr XML error tree, if retval = 0 - * @retval -1 Error (fatal) - * @retval 0 Statedata callback failed, error in xerr * @retval 1 OK + * @retval 0 Statedata callback failed, error in xerr + * @retval -1 Error (fatal) * @see RFC 6022 */ int @@ -242,6 +245,7 @@ backend_monitoring_state_get(clicon_handle h, } /*! Remove client entry state + * * Close down everything wrt clients (eg sockets, subscriptions) * Finally actually remove client struct in handle * @param[in] h Clicon handle @@ -308,6 +312,7 @@ backend_client_rm(clicon_handle h, } /*! Get clixon per datastore stats + * * @param[in] h Clicon handle * @param[in] dbname Datastore name * @param[in,out] cb Cligen buf @@ -351,6 +356,7 @@ clixon_stats_datastore_get(clicon_handle h, } /*! Get clixon per datastore stats + * * @param[in] h Clicon handle * @param[in] dbname Datastore name * @param[in,out] cb Cligen buf @@ -616,6 +622,7 @@ from_client_edit_config(clicon_handle h, } /* from_client_edit_config */ /*! Create or replace an entire config with another complete config db + * * @param[in] h Clicon handle * @param[in] xe Request: * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., * @param[out] cbret Return xml tree, eg ..., ... - * @retval -1 Fatal error - * @retval 0 Statedata callback failed. no XML tree returned * @retval 1 OK if callback found (and called) xret is set + * @retval 0 Statedata callback failed. no XML tree returned + * @retval -1 Fatal error */ static int clixon_plugin_statedata_one(clixon_plugin_t *cp, @@ -314,6 +318,7 @@ clixon_plugin_statedata_one(clixon_plugin_t *cp, } /*! Go through all backend statedata callbacks and collect state data + * * This is internal system call, plugin is invoked (does not call) this function * Backend plugins can register * @param[in] h clicon handle @@ -322,9 +327,9 @@ clixon_plugin_statedata_one(clixon_plugin_t *cp, * @param[in] xpath String with XPATH syntax. or NULL for all * @param[in] wdef With-defaults parameter, see RFC 6243 * @param[in,out] xret State XML tree is merged with existing tree. - * @retval -1 Error - * @retval 0 Statedata callback failed (xret set with netconf-error) * @retval 1 OK + * @retval 0 Statedata callback failed (xret set with netconf-error) + * @retval -1 Error * @note xret can be replaced in this function */ int @@ -412,13 +417,14 @@ clixon_plugin_statedata_all(clicon_handle h, } /*! Lock database status has changed status + * * @param[in] cp Plugin handle * @param[in] h Clixon handle * @param[in] db Database name (eg "running") * @param[in] lock Lock status: 0: unlocked, 1: locked * @param[in] id Session id (of locker/unlocker) - * @retval -1 Fatal error * @retval 0 OK + * @retval -1 Fatal error */ static int clixon_plugin_lockdb_one(clixon_plugin_t *cp, @@ -446,12 +452,13 @@ clixon_plugin_lockdb_one(clixon_plugin_t *cp, } /*! Lock database status has changed status + * * @param[in] h Clixon handle * @param[in] db Database name (eg "running") * @param[in] lock Lock status: 0: unlocked, 1: locked * @param[in] id Session id (of locker/unlocker) - * @retval -1 Fatal error * @retval 0 OK + * @retval -1 Fatal error */ int clixon_plugin_lockdb_all(clicon_handle h, @@ -548,6 +555,7 @@ clixon_pagination_free(clicon_handle h) } /*! Create and initialize a validate/commit transaction + * * @retval td New alloced transaction, * @retval NULL Error * @see transaction_free which deallocates the returned handle @@ -591,6 +599,7 @@ transaction_free(transaction_data_t *td) } /*! Call single plugin transaction_begin() before a validate/commit. + * * @param[in] cp Plugin handle * @param[in] h Clixon handle * @param[in] td Transaction data @@ -629,6 +638,7 @@ plugin_transaction_begin_one(clixon_plugin_t *cp, /* The plugin_transaction routines need access to struct plugin which is local to this file */ /*! Call transaction_begin() in all plugins before a validate/commit. + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK @@ -652,6 +662,7 @@ plugin_transaction_begin_all(clicon_handle h, } /*! Call single plugin transaction_validate() in a validate/commit transaction + * * @param[in] cp Plugin handle * @param[in] h Clixon handle * @param[in] td Transaction data @@ -689,6 +700,7 @@ plugin_transaction_validate_one(clixon_plugin_t *cp, } /*! Call transaction_validate callbacks in all backend plugins + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK. Validation succeeded in all plugins @@ -711,6 +723,7 @@ plugin_transaction_validate_all(clicon_handle h, } /*! Call single plugin transaction_complete() in a validate/commit transaction + * * complete is called after validate (before commit) * @param[in] cp Plugin handle * @param[in] h Clixon handle @@ -748,6 +761,7 @@ plugin_transaction_complete_one(clixon_plugin_t *cp, } /*! Call transaction_complete() in all plugins after validation (before commit) + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK @@ -772,6 +786,7 @@ plugin_transaction_complete_all(clicon_handle h, } /*! Revert a commit + * * @param[in] h CLICON handle * @param[in] td Transaction data * @param[in] nr The plugin where an error occured. @@ -803,6 +818,7 @@ plugin_transaction_revert_all(clicon_handle h, /*! Call single plugin transaction_commit() in a commit transaction + * * @param[in] cp Plugin handle * @param[in] h Clixon handle * @param[in] td Transaction data @@ -839,6 +855,7 @@ plugin_transaction_commit_one(clixon_plugin_t *cp, } /*! Call transaction_commit callbacks in all backend plugins + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK @@ -869,6 +886,7 @@ plugin_transaction_commit_all(clicon_handle h, } /*! Call single plugin transaction_commit_done() in a commit transaction + * * @param[in] cp Plugin handle * @param[in] h Clixon handle * @param[in] td Transaction data @@ -905,6 +923,7 @@ plugin_transaction_commit_done_one(clixon_plugin_t *cp, } /*! Call transaction_commit_done callbacks in all backend plugins + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK @@ -928,6 +947,7 @@ plugin_transaction_commit_done_all(clicon_handle h, } /*! Call single plugin transaction_end() in a commit/validate transaction + * * @param[in] cp Plugin handle * @param[in] h Clixon handle * @param[in] td Transaction data @@ -964,6 +984,7 @@ plugin_transaction_end_one(clixon_plugin_t *cp, } /*! Call transaction_end() in all plugins after a successful commit. + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK @@ -1016,6 +1037,7 @@ plugin_transaction_abort_one(clixon_plugin_t *cp, } /*! Call transaction_abort() in all plugins after a failed validation/commit. + * * @param[in] h Clicon handle * @param[in] td Transaction data * @retval 0 OK diff --git a/apps/cli/cli_generate.c b/apps/cli/cli_generate.c index 850d1b9c..35ba68b5 100644 --- a/apps/cli/cli_generate.c +++ b/apps/cli/cli_generate.c @@ -1420,10 +1420,15 @@ yang2cli_yspec(clicon_handle h, fprintf(stderr, "%s\n", cbuf_get(cb)); goto done; } + clicon_debug(CLIXON_DBG_DEFAULT, "%s Generated auto-cli for module:%s", + __FUNCTION__, yang_argument_get(ymod)); /* Add prefix: assume new are appended */ for (i=0; ico_command); co_prefix_set(co, prefix); + } } /* Post-processing, iterate over the generated cligen parse-tree with corresponding yang * Note cannot do it inline in yang2cli above since: @@ -1435,7 +1440,7 @@ yang2cli_yspec(clicon_handle h, goto done; } // pt_print(stderr,pt); - clicon_debug(1, "%s Generated auto-cli for %s", __FUNCTION__, yang_argument_get(ymod)); + if (printgen) clicon_log(LOG_NOTICE, "%s: Top-level cli-spec %s:\n%s", __FUNCTION__, treename, cbuf_get(cb)); diff --git a/example/main/example_backend.c b/example/main/example_backend.c index 51d81e6f..e267ab06 100644 --- a/example/main/example_backend.c +++ b/example/main/example_backend.c @@ -77,6 +77,7 @@ #define _STATEFILTER /*! Yang action + * * Start backend with -- -a * where instance-id points to an action node in some YANG * Hard-coded to action "reset" from RFC7950 7.15 @@ -84,12 +85,14 @@ static char *_action_instanceid = NULL; /*! Notification stream + * * Enable notification streams for netconf/restconf * Start backend with -- -n */ static int _notification_stream = 0; /*! Variable to control if reset code is run. + * * The reset code inserts "extra XML" which assumes ietf-interfaces is * loaded, and this is not always the case. * Start backend with -- -r @@ -97,18 +100,21 @@ static int _notification_stream = 0; static int _reset = 0; /*! Variable to control if state code is run + * * The state code adds extra non-config data * Start backend with -- -s */ static int _state = 0; /*! File where state XML is read from, if _state is true -- -sS + * * Primarily for testing * Start backend with -- -sS */ static char *_state_file = NULL; /*! XPath to register for pagination state XML from file, + * * if _state is true -- -sS -x * Primarily for testing * Start backend with -- -sS -x @@ -116,18 +122,21 @@ static char *_state_file = NULL; static char *_state_xpath = NULL; /*! Read state file init on startup instead of on request + * * Primarily for testing: -i * Start backend with -- -siS */ static int _state_file_cached = 0; /*! Cache control of read state file pagination example, + * * keep xml tree cache as long as db is locked */ static cxobj *_state_xml_cache = NULL; /* XML cache */ static int _state_file_transaction = 0; /*! Variable to control module-specific upgrade callbacks. + * * If set, call test-case for upgrading ietf-interfaces, otherwise call * auto-upgrade * Start backend with -- -u @@ -135,17 +144,20 @@ static int _state_file_transaction = 0; static int _module_upgrade = 0; /*! Variable to control general-purpose upgrade callbacks. + * * Start backend with -- -U */ static int _general_upgrade = 0; /*! Variable to control transaction logging (for debug) + * * If set, call syslog for every transaction callback * Start backend with -- -t */ static int _transaction_log = 0; /*! Variable to trigger validation/commit errors (synthetic errors) for tests + * * XPath to trigger validation error, ie if the XPath matches, then validate fails * This is to make tests where a transaction fails midway and aborts/reverts the transaction. * Start backend with -- -V @@ -154,6 +166,7 @@ static int _transaction_log = 0; static char *_validate_fail_xpath = NULL; /*! Sub state variable to fail on validate/commit (not configured) + * * Obscure, but a way to first trigger a validation error, next time to trigger a commit error */ static int _validate_fail_toggle = 0; /* fail at validate and commit */ @@ -169,6 +182,7 @@ main_begin(clicon_handle h, transaction_log(h, td, LOG_NOTICE, __FUNCTION__); return 0; } + /*! This is called on validate (and commit). Check validity of candidate */ int @@ -307,6 +321,7 @@ example_stream_timer_setup(clicon_handle h) } /*! Smallest possible RPC declaration for test + * * Yang/XML: * If the RPC operation invocation succeeded and no output parameters * are returned, the contains a single element defined @@ -324,6 +339,7 @@ empty_rpc(clicon_handle h, /* Clicon handle */ } /*! More elaborate example RPC for testing + * * The RPC returns the incoming parameters */ static int @@ -384,7 +400,8 @@ example_copy_extra(clicon_handle h, /* Clicon handle */ } /*! Action callback, example from RFC7950 7.15 - * Note callback is hardcoded C, while registration is controlled by -- -a option + * + * @note callback is hardcoded C, while registration is controlled by -- -a option */ static int example_action_reset(clicon_handle h, /* Clicon handle */ @@ -709,12 +726,13 @@ example_pagination(void *h0, } /*! Lock databse status has changed status + * * @param[in] h Clixon handle * @param[in] db Database name (eg "running") * @param[in] lock Lock status: 0: unlocked, 1: locked * @param[in] id Session id (of locker/unlocker) - * @retval -1 Fatal error * @retval 0 OK + * @retval -1 Fatal error */ int example_lockdb(clicon_handle h, @@ -725,7 +743,6 @@ example_lockdb(clicon_handle h, int retval = -1; clicon_debug(1, "%s Lock callback: db%s: locked:%d", __FUNCTION__, db, lock); - /* Part of cached pagination example */ if (strcmp(db, "running") == 0 && lock == 0 && @@ -736,7 +753,6 @@ example_lockdb(clicon_handle h, } _state_file_transaction = 0; } - retval = 0; // done: return retval; @@ -811,8 +827,8 @@ static const map_str2str namespace_map[] = { * @param[in] db Name of datastore, eg "running", "startup" or "tmp" * @param[in] xt XML tree. Upgrade this "in place" * @param[in] msd Info on datastore module-state, if any - * @retval -1 Error * @retval 0 OK + * @retval -1 Error */ int example_upgrade(clicon_handle h, @@ -949,6 +965,7 @@ main_yang_mount(clicon_handle h, } /*! Testcase module-specific upgrade function moving interfaces-state to interfaces + * * @param[in] h Clicon handle * @param[in] xn XML tree to be updated * @param[in] ns Namespace of module (for info) @@ -1053,6 +1070,7 @@ upgrade_2014_to_2016(clicon_handle h, } /*! Testcase upgrade function removing interfaces-state + * * @param[in] h Clicon handle * @param[in] xn XML tree to be updated * @param[in] ns Namespace of module (for info) @@ -1152,6 +1170,7 @@ upgrade_2016_to_2018(clicon_handle h, } /*! Testcase module-specific upgrade function moving interfaces-state to interfaces + * * @param[in] h Clicon handle * @param[in] xn XML tree to be updated * @param[in] ns Namespace of module (for info) @@ -1307,8 +1326,8 @@ example_start(clicon_handle h) } /*! Plugin daemon. - * @param[in] h Clicon handle * + * @param[in] h Clicon handle * plugin_daemon is called once after daemonization has been made but before lowering of privileges * the main event loop is entered. */ @@ -1380,6 +1399,7 @@ static clixon_plugin_api api = { }; /*! Backend plugin initialization + * * @param[in] h Clixon handle * @retval NULL Error with clicon_err set * @retval api Pointer to API struct diff --git a/lib/clixon/clixon_plugin.h b/lib/clixon/clixon_plugin.h index 12685637..ec838d41 100644 --- a/lib/clixon/clixon_plugin.h +++ b/lib/clixon/clixon_plugin.h @@ -52,6 +52,7 @@ */ /*! Registered RPC callback function + * * @param[in] h Clicon handle * @param[in] xn Request: * @param[out] cbret Return xml tree, eg ...,