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 cd5597ff8c1f5cb0e90733b2ac48798a200a3b7c..c920060071fd186a32c74c3a08ae9542d8267607 100644 (file)
--- a/lib/yang.h
+++ b/lib/yang.h
@@ -44,6 +44,13 @@ DECLARE_MTYPE(YANG_DATA)
 /* Maximum string length of an YANG value. */
 #define YANG_VALUE_MAXLEN 1024
 
+struct yang_module_embed {
+       struct yang_module_embed *next;
+       const char *mod_name, *mod_rev;
+       const char *data;
+       LYS_INFORMAT format;
+};
+
 struct yang_module {
        RB_ENTRY(yang_module) entry;
        const char *name;
@@ -132,6 +139,16 @@ extern struct yang_module *yang_module_load(const char *module_name);
  */
 extern struct yang_module *yang_module_find(const char *module_name);
 
+/*
+ * Register a YANG module embedded in the binary file.  Should be called
+ * from a constructor function.
+ *
+ * embed
+ *    YANG module embedding structure to register.  (static global provided
+ *    by caller.)
+ */
+extern void yang_module_embed(struct yang_module_embed *embed);
+
 /*
  * Iterate over all libyang schema nodes from the given YANG module.
  *
@@ -267,6 +284,22 @@ extern const struct lys_type *yang_snode_get_type(const struct lys_node *snode);
 extern void yang_dnode_get_path(const struct lyd_node *dnode, char *xpath,
                                size_t xpath_len);
 
+/*
+ * Return the schema name of the given libyang data node.
+ *
+ * dnode
+ *    libyang data node.
+ *
+ * xpath_fmt
+ *    Optional XPath expression (absolute or relative) to specify a different
+ *    data node to operate on in the same data tree.
+ *
+ * Returns:
+ *    Schema name of the libyang data node.
+ */
+extern const char *yang_dnode_get_schema_name(const struct lyd_node *dnode,
+                                             const char *xpath_fmt, ...);
+
 /*
  * Find a libyang data node by its YANG data path.
  *
@@ -352,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.