*: change the signature of the northbound callbacks to be more flexible

Having a fixed set of parameters for each northbound callback isn't a
good idea since it makes it difficult to add new parameters whenever
that becomes necessary, as several hundreds or thousands of existing
callbacks need to be updated accordingly.

To remediate this issue, this commit changes the signature of all
northbound callbacks to have a single parameter: a pointer to a
'nb_cb_x_args' structure (where x is different for each type
of callback). These structures encapsulate all real parameters
(both input and output) the callbacks need to have access to. And
adding a new parameter to a given callback is as simple as adding
a new field to the corresponding 'nb_cb_x_args' structure, without
needing to update any instance of that callback in any daemon.

This commit includes a .cocci semantic patch that can be used to
update old code to the new format automatically.

Signed-off-by: Renato Westphal <renato@opensourcerouting.org>

1 files changed, 166 insertions, 86 deletions

diff --git a/lib/northbound.h b/lib/northbound.h
index 19a2ba0865..84382eeb60 100644
--- a/lib/northbound.h
+++ b/lib/northbound.h
@@ -86,6 +86,129 @@ union nb_resource {
 	void *ptr;
 };
 
+/*
+ * Northbound callbacks parameters.
+ */
+
+struct nb_cb_create_args {
+	/*
+	 * The transaction phase. Refer to the documentation comments of
+	 * nb_event for more details.
+	 */
+	enum nb_event event;
+
+	/* libyang data node that is being created. */
+	const struct lyd_node *dnode;
+
+	/*
+	 * Pointer to store resource(s) allocated during the NB_EV_PREPARE
+	 * phase. The same pointer can be used during the NB_EV_ABORT and
+	 * NB_EV_APPLY phases to either release or make use of the allocated
+	 * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
+	 */
+	union nb_resource *resource;
+};
+
+struct nb_cb_modify_args {
+	/*
+	 * The transaction phase. Refer to the documentation comments of
+	 * nb_event for more details.
+	 */
+	enum nb_event event;
+
+	/* libyang data node that is being modified. */
+	const struct lyd_node *dnode;
+
+	/*
+	 * Pointer to store resource(s) allocated during the NB_EV_PREPARE
+	 * phase. The same pointer can be used during the NB_EV_ABORT and
+	 * NB_EV_APPLY phases to either release or make use of the allocated
+	 * resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
+	 */
+	union nb_resource *resource;
+};
+
+struct nb_cb_destroy_args {
+	/*
+	 * The transaction phase. Refer to the documentation comments of
+	 * nb_event for more details.
+	 */
+	enum nb_event event;
+
+	/* libyang data node that is being deleted. */
+	const struct lyd_node *dnode;
+};
+
+struct nb_cb_move_args {
+	/*
+	 * The transaction phase. Refer to the documentation comments of
+	 * nb_event for more details.
+	 */
+	enum nb_event event;
+
+	/* libyang data node that is being moved. */
+	const struct lyd_node *dnode;
+};
+
+struct nb_cb_pre_validate_args {
+	/* libyang data node associated with the 'pre_validate' callback. */
+	const struct lyd_node *dnode;
+};
+
+struct nb_cb_apply_finish_args {
+	/* libyang data node associated with the 'apply_finish' callback. */
+	const struct lyd_node *dnode;
+};
+
+struct nb_cb_get_elem_args {
+	/* YANG data path of the data we want to get. */
+	const char *xpath;
+
+	/* Pointer to list entry (might be NULL). */
+	const void *list_entry;
+};
+
+struct nb_cb_get_next_args {
+	/* Pointer to parent list entry. */
+	const void *parent_list_entry;
+
+	/* Pointer to (leaf-)list entry. */
+	const void *list_entry;
+};
+
+struct nb_cb_get_keys_args {
+	/* Pointer to list entry. */
+	const void *list_entry;
+
+	/*
+	 * Structure to be filled based on the attributes of the provided list
+	 * entry.
+	 */
+	struct yang_list_keys *keys;
+};
+
+struct nb_cb_lookup_entry_args {
+	/* Pointer to parent list entry. */
+	const void *parent_list_entry;
+
+	/* Structure containing the keys of the list entry. */
+	const struct yang_list_keys *keys;
+};
+
+struct nb_cb_rpc_args {
+	/* XPath of the YANG RPC or action. */
+	const char *xpath;
+
+	/* Read-only list of input parameters. */
+	const struct list *input;
+
+	/* List of output parameters to be populated by the callback. */
+	struct list *output;
+};
+
+/*
+ * Set of configuration callbacks that can be associated to a northbound node.
+ */
 struct nb_callbacks {
 	/*
 	 * Configuration callback.
@@ -97,18 +220,9 @@ struct nb_callbacks {
 	 * initialize the default values of its children (if any) from the YANG
 	 * models.
 	 *
-	 * event
-	 *    The transaction phase. Refer to the documentation comments of
-	 *    nb_event for more details.
-	 *
-	 * dnode
-	 *    libyang data node that is being created.
-	 *
-	 * resource
-	 *    Pointer to store resource(s) allocated during the NB_EV_PREPARE
-	 *    phase. The same pointer can be used during the NB_EV_ABORT and
-	 *    NB_EV_APPLY phases to either release or make use of the allocated
-	 *    resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_create_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    - NB_OK on success.
@@ -117,8 +231,7 @@ struct nb_callbacks {
 	 *    - NB_ERR_INCONSISTENCY when an inconsistency was detected.
 	 *    - NB_ERR for other errors.
 	 */
-	int (*create)(enum nb_event event, const struct lyd_node *dnode,
-		      union nb_resource *resource);
+	int (*create)(struct nb_cb_create_args *args);
 
 	/*
 	 * Configuration callback.
@@ -129,18 +242,9 @@ struct nb_callbacks {
 	 * modified, the northbound treats this as if the list was deleted and a
 	 * new one created with the updated key value.
 	 *
-	 * event
-	 *    The transaction phase. Refer to the documentation comments of
-	 *    nb_event for more details.
-	 *
-	 * dnode
-	 *    libyang data node that is being modified
-	 *
-	 * resource
-	 *    Pointer to store resource(s) allocated during the NB_EV_PREPARE
-	 *    phase. The same pointer can be used during the NB_EV_ABORT and
-	 *    NB_EV_APPLY phases to either release or make use of the allocated
-	 *    resource(s). It's set to NULL when the event is NB_EV_VALIDATE.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_modify_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    - NB_OK on success.
@@ -149,8 +253,7 @@ struct nb_callbacks {
 	 *    - NB_ERR_INCONSISTENCY when an inconsistency was detected.
 	 *    - NB_ERR for other errors.
 	 */
-	int (*modify)(enum nb_event event, const struct lyd_node *dnode,
-		      union nb_resource *resource);
+	int (*modify)(struct nb_cb_modify_args *args);
 
 	/*
 	 * Configuration callback.
@@ -161,12 +264,9 @@ struct nb_callbacks {
 	 * The callback is supposed to delete the entire configuration object,
 	 * including its children when they exist.
 	 *
-	 * event
-	 *    The transaction phase. Refer to the documentation comments of
-	 *    nb_event for more details.
-	 *
-	 * dnode
-	 *    libyang data node that is being deleted.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_destroy_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    - NB_OK on success.
@@ -174,7 +274,7 @@ struct nb_callbacks {
 	 *    - NB_ERR_INCONSISTENCY when an inconsistency was detected.
 	 *    - NB_ERR for other errors.
 	 */
-	int (*destroy)(enum nb_event event, const struct lyd_node *dnode);
+	int (*destroy)(struct nb_cb_destroy_args *args);
 
 	/*
 	 * Configuration callback.
@@ -182,12 +282,9 @@ struct nb_callbacks {
 	 * A list entry or leaf-list entry has been moved. Only applicable when
 	 * the "ordered-by user" statement is present.
 	 *
-	 * event
-	 *    The transaction phase. Refer to the documentation comments of
-	 *    nb_event for more details.
-	 *
-	 * dnode
-	 *    libyang data node that is being moved.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_move_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    - NB_OK on success.
@@ -195,7 +292,7 @@ struct nb_callbacks {
 	 *    - NB_ERR_INCONSISTENCY when an inconsistency was detected.
 	 *    - NB_ERR for other errors.
 	 */
-	int (*move)(enum nb_event event, const struct lyd_node *dnode);
+	int (*move)(struct nb_cb_move_args *args);
 
 	/*
 	 * Optional configuration callback.
@@ -205,10 +302,11 @@ struct nb_callbacks {
 	 * changes themselves. It's useful to perform more complex validations
 	 * that depend on the relationship between multiple nodes.
 	 *
-	 * dnode
-	 *    libyang data node associated with the 'pre_validate' callback.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_pre_validate_args for
+	 *    details.
 	 */
-	int (*pre_validate)(const struct lyd_node *dnode);
+	int (*pre_validate)(struct nb_cb_pre_validate_args *args);
 
 	/*
 	 * Optional configuration callback.
@@ -224,10 +322,11 @@ struct nb_callbacks {
 	 * once even if multiple changes occurred within the descendants of the
 	 * data node.
 	 *
-	 * dnode
-	 *    libyang data node associated with the 'apply_finish' callback.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_apply_finish_args for
+	 *    details.
 	 */
-	void (*apply_finish)(const struct lyd_node *dnode);
+	void (*apply_finish)(struct nb_cb_apply_finish_args *args);
 
 	/*
 	 * Operational data callback.
@@ -236,18 +335,15 @@ struct nb_callbacks {
 	 * leaf-list entry or inform if a typeless value (presence containers or
 	 * leafs of type empty) exists or not.
 	 *
-	 * xpath
-	 *    YANG data path of the data we want to get.
-	 *
-	 * list_entry
-	 *    Pointer to list entry (might be NULL).
+	 * args
+	 *    Refer to the documentation comments of nb_cb_get_elem_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    Pointer to newly created yang_data structure, or NULL to indicate
 	 *    the absence of data.
 	 */
-	struct yang_data *(*get_elem)(const char *xpath,
-				      const void *list_entry);
+	struct yang_data *(*get_elem)(struct nb_cb_get_elem_args *args);
 
 	/*
 	 * Operational data callback for YANG lists and leaf-lists.
@@ -256,18 +352,15 @@ struct nb_callbacks {
 	 * leaf-list. The 'list_entry' parameter will be NULL on the first
 	 * invocation.
 	 *
-	 * parent_list_entry
-	 *    Pointer to parent list entry.
-	 *
-	 * list_entry
-	 *    Pointer to (leaf-)list entry.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_get_next_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    Pointer to the next entry in the (leaf-)list, or NULL to signal
 	 *    that the end of the (leaf-)list was reached.
 	 */
-	const void *(*get_next)(const void *parent_list_entry,
-				const void *list_entry);
+	const void *(*get_next)(struct nb_cb_get_next_args *args);
 
 	/*
 	 * Operational data callback for YANG lists.
@@ -276,17 +369,14 @@ struct nb_callbacks {
 	 * given list_entry. Keyless lists don't need to implement this
 	 * callback.
 	 *
-	 * list_entry
-	 *    Pointer to list entry.
-	 *
-	 * keys
-	 *    Structure to be filled based on the attributes of the provided
-	 *    list entry.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_get_keys_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    NB_OK on success, NB_ERR otherwise.
 	 */
-	int (*get_keys)(const void *list_entry, struct yang_list_keys *keys);
+	int (*get_keys)(struct nb_cb_get_keys_args *args);
 
 	/*
 	 * Operational data callback for YANG lists.
@@ -295,17 +385,14 @@ struct nb_callbacks {
 	 * keys given as a parameter. Keyless lists don't need to implement this
 	 * callback.
 	 *
-	 * parent_list_entry
-	 *    Pointer to parent list entry.
-	 *
-	 * keys
-	 *    Structure containing the keys of the list entry.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_lookup_entry_args for
+	 *    details.
 	 *
 	 * Returns:
 	 *    Pointer to the list entry if found, or NULL if not found.
 	 */
-	const void *(*lookup_entry)(const void *parent_list_entry,
-				    const struct yang_list_keys *keys);
+	const void *(*lookup_entry)(struct nb_cb_lookup_entry_args *args);
 
 	/*
 	 * RPC and action callback.
@@ -314,20 +401,13 @@ struct nb_callbacks {
 	 * callback should fetch all the input parameters from the 'input' list,
 	 * and add output parameters to the 'output' list if necessary.
 	 *
-	 * xpath
-	 *    XPath of the YANG RPC or action.
-	 *
-	 * input
-	 *    Read-only list of input parameters.
-	 *
-	 * output
-	 *    List of output parameters to be populated by the callback.
+	 * args
+	 *    Refer to the documentation comments of nb_cb_rpc_args for details.
 	 *
 	 * Returns:
 	 *    NB_OK on success, NB_ERR otherwise.
 	 */
-	int (*rpc)(const char *xpath, const struct list *input,
-		   struct list *output);
+	int (*rpc)(struct nb_cb_rpc_args *args);
 
 	/*
 	 * Optional callback to show the CLI command associated to the given