lib: make yang_dnode_get_entry() more flexible

[mirror_frr.git] / lib / yang.h

diff --git a/lib/yang.h b/lib/yang.h
index eac9796df95a12e4f85c86196808a85fc9307d10..c920060071fd186a32c74c3a08ae9542d8267607 100644 (file)
--- a/lib/yang.h
+++ b/lib/yang.h
@@ -385,15 +385,37 @@ extern void yang_dnode_change_leaf(struct lyd_node *dnode, const char *value);
 extern void yang_dnode_set_entry(const struct lyd_node *dnode, void *entry);
 
 /*
- * Find the closest data node that contains an user pointer and return it.
+ * Find the user pointer associated to the given libyang data node.
+ *
+ * The data node is traversed by following the parent pointers until an user
+ * pointer is found or until the root node is reached.
  *
  * dnode
  *    libyang data node to operate on.
  *
+ * abort_if_not_found
+ *    When set to true, abort the program if no user pointer is found.
+ *
+ *    As a rule of thumb, this parameter should be set to true in the following
+ *    scenarios:
+ *    - Calling this function from any northbound configuration callback during
+ *      the NB_EV_APPLY phase.
+ *    - Calling this function from a 'delete' northbound configuration callback
+ *      during any phase.
+ *
+ *    In both the above cases, the libyang data node should contain an user
+ *    pointer except when there's a bug in the code, in which case it's better
+ *    to abort the program right away and eliminate the need for unnecessary
+ *    NULL checks.
+ *
+ *    In all other cases, this parameter should be set to false and the caller
+ *    should check if the function returned NULL or not.
+ *
  * Returns:
  *    User pointer if found, NULL otherwise.
  */
-extern void *yang_dnode_get_entry(const struct lyd_node *dnode);
+extern void *yang_dnode_get_entry(const struct lyd_node *dnode,
+                                 bool abort_if_not_found);
 
 /*
  * Create a new libyang data node.