libyang  2.1.148
libyang is YANG data modelling language parser and toolkit written (and providing API) in C.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
tree_data.h File Reference

libyang representation of YANG data trees. More...

#include <arpa/inet.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include "config.h"
#include "log.h"
#include "tree.h"
#include "tree_schema.h"
Include dependency graph for tree_data.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ly_opaq_name
 Generic prefix and namespace mapping, meaning depends on the format. More...
 
union  ly_opaq_name.__unnamed__
 
union  lyd_any_value
 union for anydata/anyxml value representation. More...
 
struct  lyd_attr
 Generic attribute structure. More...
 
struct  lyd_node
 Generic structure for a data node. More...
 
struct  lyd_node_any
 Data node structure for the anydata data tree nodes - anydata or anyxml. More...
 
union  lyd_node_any.__unnamed__
 
struct  lyd_node_any.__unnamed__.__unnamed__
 
struct  lyd_node_inner
 Data node structure for the inner data tree nodes - containers, lists, RPCs, actions and Notifications. More...
 
union  lyd_node_inner.__unnamed__
 
struct  lyd_node_inner.__unnamed__.__unnamed__
 
struct  lyd_node_opaq
 Data node structure for unparsed (opaque) nodes. More...
 
union  lyd_node_opaq.__unnamed__
 
struct  lyd_node_opaq.__unnamed__.__unnamed__
 
struct  lyd_node_term
 Data node structure for the terminal data tree nodes - leaves and leaf-lists. More...
 
union  lyd_node_term.__unnamed__
 
struct  lyd_node_term.__unnamed__.__unnamed__
 
struct  lyd_value
 YANG data representation. More...
 
union  lyd_value.__unnamed__
 
struct  lyd_value_binary
 Special lyd_value structure for built-in binary values. More...
 
struct  lyd_value_bits
 Special lyd_value structure for built-in bits values. More...
 
struct  lyd_value_date_and_time
 Special lyd_value structure for ietf-yang-types date-and-time values. More...
 
struct  lyd_value_ipv4_address
 Special lyd_value structure for ietf-inet-types ipv4-address values. More...
 
struct  lyd_value_ipv4_address_no_zone
 Special lyd_value structure for ietf-inet-types ipv4-address-no-zone values. More...
 
struct  lyd_value_ipv4_prefix
 Special lyd_value structure for ietf-inet-types ipv4-prefix values. More...
 
struct  lyd_value_ipv6_address
 Special lyd_value structure for ietf-inet-types ipv6-address values. More...
 
struct  lyd_value_ipv6_address_no_zone
 Special lyd_value structure for ietf-inet-types ipv6-address-no-zone values. More...
 
struct  lyd_value_ipv6_prefix
 Special lyd_value structure for ietf-inet-types ipv6-prefix values. More...
 
struct  lyd_value_union
 Special lyd_value structure for built-in union values. More...
 
struct  lyd_value_xpath10
 Special lyd_value structure for ietf-yang-types xpath1.0 values. More...
 

Macros

#define LYD_COMPARE_DEFAULTS
 
#define LYD_COMPARE_FULL_RECURSION
 
#define LYD_COMPARE_OPAQ
 
#define LYD_CTX(node)   ((node)->schema ? (node)->schema->module->ctx : ((const struct lyd_node_opaq *)(node))->ctx)
 Macro to get context from a data tree node. More...
 
#define LYD_DEFAULT   0x01
 
#define LYD_DIFF_DEFAULTS   0x01
 
#define LYD_DIFF_MERGE_DEFAULTS   0x01
 
#define LYD_DUP_NO_EXT   0x10
 
#define LYD_DUP_NO_META   0x02
 
#define LYD_DUP_RECURSIVE   0x01
 
#define LYD_DUP_WITH_FLAGS   0x08
 
#define LYD_DUP_WITH_PARENTS   0x04
 
#define LYD_DUP_WITH_PRIV   0x20
 
#define LYD_EXT   0x08
 
#define LYD_HINT_DATA   0x01F3
 
#define LYD_HINT_SCHEMA   0x01FF
 
#define LYD_HT_MIN_ITEMS   4
 
#define LYD_IMPLICIT_NO_CONFIG   0x02
 
#define LYD_IMPLICIT_NO_DEFAULTS   0x08
 
#define LYD_IMPLICIT_NO_STATE   0x01
 
#define LYD_IMPLICIT_OUTPUT   0x04
 
#define LYD_LIST_FOR_INST(START, SCHEMA, ELEM)
 Macro to iterate via all schema node data instances in data siblings. More...
 
#define LYD_LIST_FOR_INST_SAFE(START, SCHEMA, NEXT, ELEM)
 Macro to iterate via all schema node data instances in data siblings allowing to modify the list itself. More...
 
#define LYD_MERGE_DEFAULTS   0x02
 
#define LYD_MERGE_DESTRUCT   0x01
 
#define LYD_MERGE_WITH_FLAGS   0x04
 
#define LYD_NAME(node)   ((node)->schema ? (node)->schema->name : ((struct lyd_node_opaq *)node)->name.name)
 Get the name (associated with) of a data node. Works for opaque nodes as well. More...
 
#define LYD_NEW   0x04
 
#define LYD_NEW_PATH_BIN_VALUE   0x08
 
#define LYD_NEW_PATH_CANON_VALUE   0x10
 
#define LYD_NEW_PATH_OPAQ   0x04
 
#define LYD_NEW_PATH_OUTPUT   0x02
 
#define LYD_NEW_PATH_UPDATE   0x01
 
#define LYD_NEW_PATH_WITH_OPAQ   0x20
 
#define LYD_NODE_ANY   (LYS_ANYDATA)
 
#define LYD_NODE_INNER   (LYS_CONTAINER|LYS_LIST|LYS_RPC|LYS_ACTION|LYS_NOTIF)
 
#define LYD_NODE_TERM   (LYS_LEAF|LYS_LEAFLIST)
 
#define LYD_NODEHINT_LEAFLIST   0x0100
 
#define LYD_NODEHINT_LIST   0x0080
 
#define LYD_TREE_DFS_BEGIN(START, ELEM)
 Macro to iterate via all elements in a data tree. This is the opening part to the LYD_TREE_DFS_END - they always have to be used together. More...
 
#define LYD_TREE_DFS_END(START, ELEM)
 Macro to iterate via all elements in a tree. This is the closing part to the LYD_TREE_DFS_BEGIN - they always have to be used together. More...
 
#define LYD_VALHINT_BOOLEAN   0x0020
 
#define LYD_VALHINT_DECNUM   0x0002
 
#define LYD_VALHINT_EMPTY   0x0040
 
#define LYD_VALHINT_HEXNUM   0x0008
 
#define LYD_VALHINT_NUM64   0x0010
 
#define LYD_VALHINT_OCTNUM   0x0004
 
#define LYD_VALHINT_STRING   0x0001
 
#define LYD_VALUE_GET(value, type_val)
 Get the value in format specific to the type. More...
 
#define LYD_WHEN_TRUE   0x02
 

Typedefs

typedef LY_ERR(* lyd_diff_cb )(const struct lyd_node *diff_node, struct lyd_node *data_node, void *cb_data)
 Callback for diff nodes. More...
 
typedef LY_ERR(* lyd_merge_cb )(struct lyd_node *trg_node, const struct lyd_node *src_node, void *cb_data)
 Callback for matching merge nodes. More...
 

Enumerations

enum  LY_XPATH_TYPE { LY_XPATH_NODE_SET, LY_XPATH_STRING, LY_XPATH_NUMBER, LY_XPATH_BOOLEAN }
 XPath result type. More...
 
enum  LYD_ANYDATA_VALUETYPE {
  LYD_ANYDATA_DATATREE, LYD_ANYDATA_STRING, LYD_ANYDATA_XML, LYD_ANYDATA_JSON,
  LYD_ANYDATA_LYB
}
 List of possible value types stored in lyd_node_any. More...
 
enum  LYD_FORMAT { LYD_UNKNOWN = 0, LYD_XML, LYD_JSON, LYD_LYB }
 Data input/output formats supported by libyang parser and printer functions. More...
 
enum  LYD_PATH_TYPE { LYD_PATH_STD, LYD_PATH_STD_NO_LAST_PRED }
 Types of the different data paths. More...
 

Functions

LIBYANG_API_DECL LY_ERR ly_time_str2time (const char *value, time_t *time, char **fractions_s)
 Convert date-and-time from string to UNIX timestamp and fractions of a second. More...
 
LIBYANG_API_DECL LY_ERR ly_time_str2ts (const char *value, struct timespec *ts)
 Convert date-and-time from string to timespec. More...
 
LIBYANG_API_DECL LY_ERR ly_time_time2str (time_t time, const char *fractions_s, char **str)
 Convert UNIX timestamp and fractions of a second into canonical date-and-time string value. More...
 
LIBYANG_API_DECL LY_ERR ly_time_ts2str (const struct timespec *ts, char **str)
 Convert timespec into date-and-time string value. More...
 
LIBYANG_API_DECL int ly_time_tz_offset (void)
 Get current timezone (including DST setting) UTC (GMT) time offset in seconds. More...
 
LIBYANG_API_DECL int ly_time_tz_offset_at (time_t time)
 Get UTC (GMT) timezone offset in seconds at a specific timestamp (including DST setting). More...
 
LIBYANG_API_DECL LY_ERR lyd_any_copy_value (struct lyd_node *trg, const union lyd_any_value *value, LYD_ANYDATA_VALUETYPE value_type)
 Copy anydata value from one node to another. Target value is freed first. More...
 
LIBYANG_API_DECL LY_ERR lyd_any_value_str (const struct lyd_node *any, char **value_str)
 Get anydata string value. More...
 
LIBYANG_API_DECL LY_ERR lyd_change_meta (struct lyd_meta *meta, const char *val_str)
 Change the value of a metadata instance. More...
 
LIBYANG_API_DECL LY_ERR lyd_change_term (struct lyd_node *term, const char *val_str)
 Change the value of a term (leaf or leaf-list) node to a string value. More...
 
LIBYANG_API_DECL LY_ERR lyd_change_term_bin (struct lyd_node *term, const void *value, size_t value_len)
 Change the value of a term (leaf or leaf-list) node to a binary value. More...
 
LIBYANG_API_DECL LY_ERR lyd_change_term_canon (struct lyd_node *term, const char *val_str)
 Change the value of a term (leaf or leaf-list) node to a canonical string value. More...
 
LIBYANG_API_DECL struct lyd_nodelyd_child (const struct lyd_node *node)
 Get the child pointer of a generic data node. More...
 
LIBYANG_API_DECL struct lyd_nodelyd_child_no_keys (const struct lyd_node *node)
 Get the child pointer of a generic data node but skip its keys in case it is LYS_LIST. More...
 
LIBYANG_API_DECL LY_ERR lyd_compare_meta (const struct lyd_meta *meta1, const struct lyd_meta *meta2)
 Compare 2 metadata. More...
 
LIBYANG_API_DECL LY_ERR lyd_compare_siblings (const struct lyd_node *node1, const struct lyd_node *node2, uint32_t options)
 Compare 2 lists of siblings if they are equivalent. More...
 
LIBYANG_API_DECL LY_ERR lyd_compare_single (const struct lyd_node *node1, const struct lyd_node *node2, uint32_t options)
 Compare 2 data nodes if they are equivalent. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_apply_all (struct lyd_node **data, const struct lyd_node *diff)
 Apply the whole diff tree on a data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_apply_module (struct lyd_node **data, const struct lyd_node *diff, const struct lys_module *mod, lyd_diff_cb diff_cb, void *cb_data)
 Apply the whole diff on a data tree but restrict the operation to one module. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_merge_all (struct lyd_node **diff, const struct lyd_node *src_diff, uint16_t options)
 Merge 2 diffs into each other. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_merge_module (struct lyd_node **diff, const struct lyd_node *src_diff, const struct lys_module *mod, lyd_diff_cb diff_cb, void *cb_data, uint16_t options)
 Merge 2 diffs into each other but restrict the operation to one module. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_merge_tree (struct lyd_node **diff_first, struct lyd_node *diff_parent, const struct lyd_node *src_sibling, lyd_diff_cb diff_cb, void *cb_data, uint16_t options)
 Merge 2 diff trees into each other. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_reverse_all (const struct lyd_node *src_diff, struct lyd_node **diff)
 Reverse a diff and make the opposite changes. Meaning change create to delete, delete to create, or move from place A to B to move from B to A and so on. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_siblings (const struct lyd_node *first, const struct lyd_node *second, uint16_t options, struct lyd_node **diff)
 Learn the differences between 2 data trees including all the following siblings. More...
 
LIBYANG_API_DECL LY_ERR lyd_diff_tree (const struct lyd_node *first, const struct lyd_node *second, uint16_t options, struct lyd_node **diff)
 Learn the differences between 2 data trees. More...
 
LIBYANG_API_DECL LY_ERR lyd_dup_meta_single (const struct lyd_meta *meta, struct lyd_node *parent, struct lyd_meta **dup)
 Create a copy of the metadata. More...
 
LIBYANG_API_DECL LY_ERR lyd_dup_siblings (const struct lyd_node *node, struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup)
 Create a copy of the specified data tree node with any following siblings. Schema references are kept the same. More...
 
LIBYANG_API_DECL LY_ERR lyd_dup_siblings_to_ctx (const struct lyd_node *node, const struct ly_ctx *trg_ctx, struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup)
 Create a copy of the specified data tree node with any following siblings. Schema references are assigned from trg_ctx. More...
 
LIBYANG_API_DECL LY_ERR lyd_dup_single (const struct lyd_node *node, struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup)
 Create a copy of the specified data tree node. Schema references are kept the same. More...
 
LIBYANG_API_DECL LY_ERR lyd_dup_single_to_ctx (const struct lyd_node *node, const struct ly_ctx *trg_ctx, struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup)
 Create a copy of the specified data tree node. Schema references are assigned from trg_ctx. More...
 
LIBYANG_API_DECL LY_ERR lyd_eval_xpath (const struct lyd_node *ctx_node, const char *xpath, ly_bool *result)
 Evaluate an XPath on data and return the result converted to boolean. More...
 
LIBYANG_API_DECL LY_ERR lyd_eval_xpath2 (const struct lyd_node *ctx_node, const char *xpath, const struct lyxp_var *vars, ly_bool *result)
 Evaluate an XPath on data and return the result converted to boolean. More...
 
LIBYANG_API_DECL LY_ERR lyd_eval_xpath3 (const struct lyd_node *ctx_node, const struct lys_module *cur_mod, const char *xpath, LY_VALUE_FORMAT format, void *prefix_data, const struct lyxp_var *vars, ly_bool *result)
 Evaluate an XPath on data and return the result converted to boolean. More...
 
LIBYANG_API_DECL LY_ERR lyd_eval_xpath4 (const struct lyd_node *ctx_node, const struct lyd_node *tree, const struct lys_module *cur_mod, const char *xpath, LY_VALUE_FORMAT format, void *prefix_data, const struct lyxp_var *vars, LY_XPATH_TYPE *ret_type, struct ly_set **node_set, char **string, long double *number, ly_bool *boolean)
 Evaluate an XPath on data and return the result or convert it first to an expected result type. More...
 
LIBYANG_API_DECL struct lyd_metalyd_find_meta (const struct lyd_meta *first, const struct lys_module *module, const char *name)
 Find a specific metadata. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_path (const struct lyd_node *ctx_node, const char *path, ly_bool output, struct lyd_node **match)
 Search in given data for a node uniquely identified by a path. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_sibling_dup_inst_set (const struct lyd_node *siblings, const struct lyd_node *target, struct ly_set **set)
 Search the given siblings for all the exact same instances of a specific node instance. Uses hashes to whatever extent possible. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_sibling_first (const struct lyd_node *siblings, const struct lyd_node *target, struct lyd_node **match)
 Search in the given siblings (NOT recursively) for the first target instance with the same value. Uses hashes - should be used whenever possible for best performance. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_sibling_opaq_next (const struct lyd_node *first, const char *name, struct lyd_node **match)
 Search the given siblings for an opaque node with a specific name. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_sibling_val (const struct lyd_node *siblings, const struct lysc_node *schema, const char *key_or_value, size_t val_len, struct lyd_node **match)
 Search in the given siblings for the first schema instance. Uses hashes - should be used whenever possible for best performance. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_target (const struct ly_path *path, const struct lyd_node *tree, struct lyd_node **match)
 Find the target node of a compiled path (lyd_value instance-identifier). More...
 
LIBYANG_API_DECL LY_ERR lyd_find_xpath (const struct lyd_node *ctx_node, const char *xpath, struct ly_set **set)
 Search in the given data for instances of nodes matching the provided XPath. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_xpath2 (const struct lyd_node *ctx_node, const char *xpath, const struct lyxp_var *vars, struct ly_set **set)
 Search in the given data for instances of nodes matching the provided XPath. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_xpath3 (const struct lyd_node *ctx_node, const struct lyd_node *tree, const char *xpath, const struct lyxp_var *vars, struct ly_set **set)
 Search in the given data for instances of nodes matching the provided XPath. More...
 
LIBYANG_API_DECL LY_ERR lyd_find_xpath4 (const struct lyd_node *ctx_node, const struct lyd_node *tree, const char *xpath, LY_VALUE_FORMAT format, void *prefix_data, const struct lyxp_var *vars, struct ly_set **set)
 Search in the given data for instances of nodes matching the provided XPath. More...
 
LIBYANG_API_DECL struct lyd_nodelyd_first_sibling (const struct lyd_node *node)
 Get the first sibling of the given node. More...
 
LIBYANG_API_DECL void lyd_free_all (struct lyd_node *node)
 Free all the nodes (even parents of the node) in the data tree. More...
 
LIBYANG_API_DECL void lyd_free_attr_siblings (const struct ly_ctx *ctx, struct lyd_attr *attr)
 Free the attribute with any following attributes. More...
 
LIBYANG_API_DECL void lyd_free_attr_single (const struct ly_ctx *ctx, struct lyd_attr *attr)
 Free a single attribute. More...
 
LIBYANG_API_DECL void lyd_free_meta_siblings (struct lyd_meta *meta)
 Free the metadata instance with any following instances. More...
 
LIBYANG_API_DECL void lyd_free_meta_single (struct lyd_meta *meta)
 Free a single metadata instance. More...
 
LIBYANG_API_DECL void lyd_free_siblings (struct lyd_node *node)
 Free all the sibling nodes (preceding as well as succeeding). More...
 
LIBYANG_API_DECL void lyd_free_tree (struct lyd_node *node)
 Free (and unlink) the specified data (sub)tree. More...
 
LIBYANG_API_DECL const char * lyd_get_value (const struct lyd_node *node)
 Get the (canonical) value of a data node. More...
 
LIBYANG_API_DECL LY_ERR lyd_insert_after (struct lyd_node *sibling, struct lyd_node *node)
 Insert a node after another node, can be used only for user-ordered nodes. If inserting several siblings, each of them must be inserted individually. More...
 
LIBYANG_API_DECL LY_ERR lyd_insert_before (struct lyd_node *sibling, struct lyd_node *node)
 Insert a node before another node, can be used only for user-ordered nodes. If inserting several siblings, each of them must be inserted individually. More...
 
LIBYANG_API_DECL LY_ERR lyd_insert_child (struct lyd_node *parent, struct lyd_node *node)
 Insert a child into a parent. More...
 
LIBYANG_API_DECL LY_ERR lyd_insert_sibling (struct lyd_node *sibling, struct lyd_node *node, struct lyd_node **first)
 Insert a node into siblings. More...
 
LIBYANG_API_DECL ly_bool lyd_is_default (const struct lyd_node *node)
 Check whether a node value equals to its default one. More...
 
LIBYANG_API_DECL uint32_t lyd_list_pos (const struct lyd_node *instance)
 Learn the relative position of a list or leaf-list instance within other instances of the same schema node. More...
 
LIBYANG_API_DECL int lyd_lyb_data_length (const char *data)
 Learn the length of LYB data. More...
 
LIBYANG_API_DECL LY_ERR lyd_merge_module (struct lyd_node **target, const struct lyd_node *source, const struct lys_module *mod, lyd_merge_cb merge_cb, void *cb_data, uint16_t options)
 Merge all the nodes of a module from source data tree into the target data tree. Merge may not be complete until validation called on the resulting data tree (data from more cases may be present, default and non-default values). More...
 
LIBYANG_API_DECL LY_ERR lyd_merge_siblings (struct lyd_node **target, const struct lyd_node *source, uint16_t options)
 Merge the source data tree with any following siblings into the target data tree. Merge may not be complete until validation called on the resulting data tree (data from more cases may be present, default and non-default values). More...
 
LIBYANG_API_DECL LY_ERR lyd_merge_tree (struct lyd_node **target, const struct lyd_node *source, uint16_t options)
 Merge the source data subtree into the target data tree. Merge may not be complete until validation is called on the resulting data tree (data from more cases may be present, default and non-default values). More...
 
LIBYANG_API_DECL LY_ERR lyd_new_any (struct lyd_node *parent, const struct lys_module *module, const char *name, const void *value, ly_bool use_value, LYD_ANYDATA_VALUETYPE value_type, ly_bool output, struct lyd_node **node)
 Create a new any node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_attr (struct lyd_node *parent, const char *module_name, const char *name, const char *value, struct lyd_attr **attr)
 Create new JSON attribute for an opaque data node. To create an XML attribute, use lyd_new_attr2(). More...
 
LIBYANG_API_DECL LY_ERR lyd_new_attr2 (struct lyd_node *parent, const char *module_ns, const char *name, const char *value, struct lyd_attr **attr)
 Create new XML attribute for an opaque data node. To create a JSON attribute, use lyd_new_attr(). More...
 
LIBYANG_API_DECL LY_ERR lyd_new_ext_any (const struct lysc_ext_instance *ext, const char *name, const void *value, ly_bool use_value, LYD_ANYDATA_VALUETYPE value_type, struct lyd_node **node)
 Create a new top-level any node defined in the given extension instance. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_ext_inner (const struct lysc_ext_instance *ext, const char *name, struct lyd_node **node)
 Create a new top-level inner node defined in the given extension instance. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_ext_list (const struct lysc_ext_instance *ext, const char *name, struct lyd_node **node,...)
 Create a new top-level list node defined in the given extension instance. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_ext_path (struct lyd_node *parent, const struct lysc_ext_instance *ext, const char *path, const void *value, uint32_t options, struct lyd_node **node)
 Create a new node defined in the given extension instance. In case of anyxml/anydata nodes, this function expects the value as string. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_ext_term (const struct lysc_ext_instance *ext, const char *name, const char *val_str, struct lyd_node **node)
 Create a new top-level term node defined in the given extension instance. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_implicit_all (struct lyd_node **tree, const struct ly_ctx *ctx, uint32_t implicit_options, struct lyd_node **diff)
 Add any missing implicit nodes. Default nodes with a false "when" are not added. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_implicit_module (struct lyd_node **tree, const struct lys_module *module, uint32_t implicit_options, struct lyd_node **diff)
 Add any missing implicit nodes of one module. Default nodes with a false "when" are not added. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_implicit_tree (struct lyd_node *tree, uint32_t implicit_options, struct lyd_node **diff)
 Add any missing implicit nodes into a data subtree. Default nodes with a false "when" are not added. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_inner (struct lyd_node *parent, const struct lys_module *module, const char *name, ly_bool output, struct lyd_node **node)
 Create a new inner node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list (struct lyd_node *parent, const struct lys_module *module, const char *name, ly_bool output, struct lyd_node **node,...)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list2 (struct lyd_node *parent, const struct lys_module *module, const char *name, const char *keys, ly_bool output, struct lyd_node **node)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list3 (struct lyd_node *parent, const struct lys_module *module, const char *name, const char **key_values, uint32_t *value_lengths, ly_bool output, struct lyd_node **node)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list3_bin (struct lyd_node *parent, const struct lys_module *module, const char *name, const void **key_values, uint32_t *value_lengths, ly_bool output, struct lyd_node **node)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list3_canon (struct lyd_node *parent, const struct lys_module *module, const char *name, const char **key_values, uint32_t *value_lengths, ly_bool output, struct lyd_node **node)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list_bin (struct lyd_node *parent, const struct lys_module *module, const char *name, ly_bool output, struct lyd_node **node,...)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_list_canon (struct lyd_node *parent, const struct lys_module *module, const char *name, ly_bool output, struct lyd_node **node,...)
 Create a new list node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_meta (const struct ly_ctx *ctx, struct lyd_node *parent, const struct lys_module *module, const char *name, const char *val_str, ly_bool clear_dflt, struct lyd_meta **meta)
 Create new metadata. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_meta2 (const struct ly_ctx *ctx, struct lyd_node *parent, ly_bool clear_dflt, const struct lyd_attr *attr, struct lyd_meta **meta)
 Create new metadata from an opaque node attribute if possible. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_opaq (struct lyd_node *parent, const struct ly_ctx *ctx, const char *name, const char *value, const char *prefix, const char *module_name, struct lyd_node **node)
 Create a new JSON opaque node in the data tree. To create an XML opaque node, use lyd_new_opaq2(). More...
 
LIBYANG_API_DECL LY_ERR lyd_new_opaq2 (struct lyd_node *parent, const struct ly_ctx *ctx, const char *name, const char *value, const char *prefix, const char *module_ns, struct lyd_node **node)
 Create a new XML opaque node in the data tree. To create a JSON opaque node, use lyd_new_opaq(). More...
 
LIBYANG_API_DECL LY_ERR lyd_new_path (struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const char *value, uint32_t options, struct lyd_node **node)
 Create a new node in the data tree based on a path. If creating anyxml/anydata nodes, lyd_new_path2 should be used instead, this function expects the value as string. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_path2 (struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const void *value, size_t value_len, LYD_ANYDATA_VALUETYPE value_type, uint32_t options, struct lyd_node **new_parent, struct lyd_node **new_node)
 Create a new node in the data tree based on a path. All node types can be created. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_term (struct lyd_node *parent, const struct lys_module *module, const char *name, const char *val_str, ly_bool output, struct lyd_node **node)
 Create a new term node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_term_bin (struct lyd_node *parent, const struct lys_module *module, const char *name, const void *value, size_t value_len, ly_bool output, struct lyd_node **node)
 Create a new term node in the data tree. More...
 
LIBYANG_API_DECL LY_ERR lyd_new_term_canon (struct lyd_node *parent, const struct lys_module *module, const char *name, const char *val_str, ly_bool output, struct lyd_node **node)
 Create a new term node in the data tree. More...
 
LIBYANG_API_DECL struct
lys_module
lyd_node_module (const struct lyd_node *node)
 Get the module of a node. Useful mainly for opaque nodes. More...
 
LIBYANG_API_DECL struct lysc_nodelyd_node_schema (const struct lyd_node *node)
 Get schema node of a data node. Useful especially for opaque nodes. More...
 
LIBYANG_API_DECL struct
lys_module
lyd_owner_module (const struct lyd_node *node)
 Get the owner module of the data node. It is the module of the top-level schema node. Generally, in case of augments it is the target module, recursively, otherwise it is the module where the data node is defined. More...
 
LIBYANG_API_DECL struct lyd_nodelyd_parent (const struct lyd_node *node)
 Get the generic parent pointer of a data node. More...
 
LIBYANG_API_DECL LY_ERR lyd_parse_opaq_error (const struct lyd_node *node)
 Check node parsed into an opaque node for the reason (error) why it could not be parsed as data node. More...
 
LIBYANG_API_DECL char * lyd_path (const struct lyd_node *node, LYD_PATH_TYPE pathtype, char *buffer, size_t buflen)
 Generate path of the given node in the requested format. More...
 
LIBYANG_API_DECL struct
lyd_node_term
lyd_target (const struct ly_path *path, const struct lyd_node *tree)
 Deprecated, use lyd_find_target() instead. More...
 
LIBYANG_API_DEF LY_ERR lyd_trim_xpath (struct lyd_node **tree, const char *xpath, const struct lyxp_var *vars)
 Evaluate an XPath on data and free all the nodes except the subtrees selected by the expression. More...
 
LIBYANG_API_DECL void lyd_unlink_siblings (struct lyd_node *node)
 Unlink the specified node with all the following siblings. More...
 
LIBYANG_API_DECL void lyd_unlink_tree (struct lyd_node *node)
 Unlink the specified data subtree. More...
 
LIBYANG_API_DECL LY_ERR lyd_value_compare (const struct lyd_node_term *node, const char *value, size_t value_len)
 Compare the node's value with the given string value. The string value is first validated according to the (current) node's type. More...
 
LIBYANG_API_DECL const char * lyd_value_get_canonical (const struct ly_ctx *ctx, const struct lyd_value *value)
 Get the (canonical) value of a lyd_value. More...
 
LIBYANG_API_DECL LY_ERR lyd_value_validate (const struct ly_ctx *ctx, const struct lysc_node *schema, const char *value, size_t value_len, const struct lyd_node *ctx_node, const struct lysc_type **realtype, const char **canonical)
 Check type restrictions applicable to the particular leaf/leaf-list with the given string value. More...
 
LIBYANG_API_DECL void lyxp_vars_free (struct lyxp_var *vars)
 Free the XPath variables. More...
 
LIBYANG_API_DECL LY_ERR lyxp_vars_set (struct lyxp_var **vars, const char *name, const char *value)
 Set a new XPath variable to vars. More...
 

Detailed Description

libyang representation of YANG data trees.

Author
Radek Krejci rkrej.nosp@m.ci@c.nosp@m.esnet.nosp@m..cz
Michal Vasko mvask.nosp@m.o@ce.nosp@m.snet..nosp@m.cz Copyright (c) 2015 - 2022 CESNET, z.s.p.o.

This source code is licensed under BSD 3-Clause License (the "License"). You may not use this file except in compliance with the License. You may obtain a copy of the License at

https://opensource.org/licenses/BSD-3-Clause

Definition in file tree_data.h.


Data Structure Documentation

struct ly_opaq_name

Generic prefix and namespace mapping, meaning depends on the format.

The union is used as a reference to the data's module and according to the format, it can be used as a key for ly_ctx_get_module_implemented_ns() or ly_ctx_get_module_implemented(). While the module reference is always present, the prefix member can be omitted in case it is not present in the source data as a reference to the default module/namespace.

Definition at line 719 of file tree_data.h.

Data Fields
union ly_opaq_name __unnamed__
const char * name

node name, without prefix if any was defined

const char * prefix

identifier used in the qualified name as the prefix, can be NULL

union ly_opaq_name.__unnamed__

Definition at line 723 of file tree_data.h.

Data Fields
const char * module_name

format LY_VALUE_JSON - (inherited) name of the module of the element

const char * module_ns

format LY_VALUE_XML - XML namespace of the node element

union lyd_any_value

union for anydata/anyxml value representation.

Definition at line 862 of file tree_data.h.

Data Fields
const char * json

I-JSON encoded string

char * mem

LYD_ANYDATA_LYB memory chunk

const char * str

Generic string data

struct lyd_node * tree

data tree

const char * xml

Serialized XML data

struct lyd_attr

Generic attribute structure.

Definition at line 732 of file tree_data.h.

Data Fields
LY_VALUE_FORMAT format

format of the attribute and any prefixes, LY_VALUE_XML or LY_VALUE_JSON

uint32_t hints

additional information about from the data source, see the hints list

struct ly_opaq_name name

attribute name with module information

struct lyd_attr * next

pointer to the next attribute

struct lyd_node_opaq * parent

data node where the attribute is placed

void * val_prefix_data

format-specific prefix data

const char * value

attribute value

struct lyd_node

Generic structure for a data node.

Definition at line 781 of file tree_data.h.

Data Fields
uint32_t flags

data node flags

uint32_t hash

hash of this particular node (module name + schema name + key string values if list or hashes of all nodes of subtree in case of keyless list). Note that while hash can be used to get know that nodes are not equal, it cannot be used to decide that the nodes are equal due to possible collisions.

struct lyd_meta * meta

pointer to the list of metadata of this node

struct lyd_node * next

pointer to the next sibling node (NULL if there is no one)

struct lyd_node_inner * parent

pointer to the parent node, NULL in case of root node

struct lyd_node * prev

pointer to the previous sibling node

Note
Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
void * priv

private user data, not used by libyang

struct lysc_node * schema

pointer to the schema definition of this node

struct lyd_node_any

Data node structure for the anydata data tree nodes - anydata or anyxml.

Definition at line 874 of file tree_data.h.

Data Fields
union lyd_node_any __unnamed__

common part corresponding to lyd_node

union lyd_any_value value

pointer to the stored value representation of the anydata/anyxml node

LYD_ANYDATA_VALUETYPE value_type

type of the data stored as lyd_node_any.value

union lyd_node_any.__unnamed__

Definition at line 875 of file tree_data.h.

Data Fields
__unnamed__ __unnamed__
struct lyd_node node

implicit cast for the members compatible with lyd_node

struct lyd_node_any.__unnamed__.__unnamed__

Definition at line 878 of file tree_data.h.

Data Fields
uint32_t flags

data node flags

uint32_t hash

hash of this particular node (module name + schema name + key string values if list or hashes of all nodes of subtree in case of keyless list). Note that while hash can be used to get know that nodes are not equal, it cannot be used to decide that the nodes are equal due to possible collisions.

struct lyd_meta * meta

pointer to the list of metadata of this node

struct lyd_node * next

pointer to the next sibling node (NULL if there is no one)

struct lyd_node_inner * parent

pointer to the parent node, NULL in case of root node

struct lyd_node * prev

pointer to the previous sibling node

Note
Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
void * priv

private user data, not used by libyang

struct lysc_node * schema

pointer to the schema definition of this node

struct lyd_node_inner

Data node structure for the inner data tree nodes - containers, lists, RPCs, actions and Notifications.

Definition at line 801 of file tree_data.h.

Data Fields
union lyd_node_inner __unnamed__

common part corresponding to lyd_node

struct lyd_node * child

pointer to the first child node.

struct ly_ht * children_ht

hash table with all the direct children (except keys for a list, lists without keys)

union lyd_node_inner.__unnamed__

Definition at line 802 of file tree_data.h.

Data Fields
__unnamed__ __unnamed__
struct lyd_node node

implicit cast for the members compatible with lyd_node

struct lyd_node_inner.__unnamed__.__unnamed__

Definition at line 805 of file tree_data.h.

Data Fields
uint32_t flags

data node flags

uint32_t hash

hash of this particular node (module name + schema name + key string values if list or hashes of all nodes of subtree in case of keyless list). Note that while hash can be used to get know that nodes are not equal, it cannot be used to decide that the nodes are equal due to possible collisions.

struct lyd_meta * meta

pointer to the list of metadata of this node

struct lyd_node * next

pointer to the next sibling node (NULL if there is no one)

struct lyd_node_inner * parent

pointer to the parent node, NULL in case of root node

struct lyd_node * prev

pointer to the previous sibling node

Note
Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
void * priv

private user data, not used by libyang

struct lysc_node * schema

pointer to the schema definition of this node

struct lyd_node_opaq

Data node structure for unparsed (opaque) nodes.

lydhints

Definition at line 975 of file tree_data.h.

Data Fields
union lyd_node_opaq __unnamed__

common part corresponding to lyd_node

struct lyd_attr * attr

pointer to the list of generic attributes of this node

struct lyd_node * child

pointer to the child node (compatible with lyd_node_inner)

struct ly_ctx * ctx

libyang context

LY_VALUE_FORMAT format

format of the node and any prefixes, LY_VALUE_XML or LY_VALUE_JSON

uint32_t hints

additional information about from the data source, see the hints list

struct ly_opaq_name name

node name with module information

void * val_prefix_data

format-specific prefix data

const char * value

original value

union lyd_node_opaq.__unnamed__

Definition at line 976 of file tree_data.h.

Data Fields
__unnamed__ __unnamed__
struct lyd_node node

implicit cast for the members compatible with lyd_node

struct lyd_node_opaq.__unnamed__.__unnamed__

Definition at line 979 of file tree_data.h.

Data Fields
uint32_t flags

always 0

uint32_t hash

always 0

struct lyd_meta * meta

always NULL

struct lyd_node * next

pointer to the next sibling node (NULL if there is no one)

struct lyd_node_inner * parent

pointer to the parent node, NULL in case of root node

struct lyd_node * prev

pointer to the previous sibling node

Note
Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
void * priv

private user data, not used by libyang

struct lysc_node * schema

always NULL

struct lyd_node_term

Data node structure for the terminal data tree nodes - leaves and leaf-lists.

Definition at line 833 of file tree_data.h.

Data Fields
union lyd_node_term __unnamed__

common part corresponding to lyd_node

struct lyd_value value

node's value representation

union lyd_node_term.__unnamed__

Definition at line 834 of file tree_data.h.

Data Fields
__unnamed__ __unnamed__
struct lyd_node node

implicit cast for the members compatible with lyd_node

struct lyd_node_term.__unnamed__.__unnamed__

Definition at line 837 of file tree_data.h.

Data Fields
uint32_t flags

data node flags

uint32_t hash

hash of this particular node (module name + schema name + key string values if list or hashes of all nodes of subtree in case of keyless list). Note that while hash can be used to get know that nodes are not equal, it cannot be used to decide that the nodes are equal due to possible collisions.

struct lyd_meta * meta

pointer to the list of metadata of this node

struct lyd_node * next

pointer to the next sibling node (NULL if there is no one)

struct lyd_node_inner * parent

pointer to the parent node, NULL in case of root node

struct lyd_node * prev

pointer to the previous sibling node

Note
Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
void * priv

private user data, not used by libyang

struct lysc_node * schema

pointer to the schema definition of this node

struct lyd_value

YANG data representation.

Definition at line 560 of file tree_data.h.

Data Fields
union lyd_value __unnamed__

The union is just a list of shorthands to possible values stored by a type's plugin. libyang itself uses the lyd_value.realtype plugin's callbacks to work with the data.

const char * _canonical

Should never be accessed directly, instead lyd_get_value() and lyd_get_meta_value() should be used. Serves as a cache for the canonical value or the JSON representation if no canonical value is defined.

struct lysc_type * realtype

pointer to the real type of the data stored in the value structure. This type can differ from the type in the schema node of the data node since the type's store plugin can use other types/plugins for storing data. Speaking about built-in types, this is the case of leafref which stores data as its target type. In contrast, union type also uses its subtype's callbacks, but inside an internal data stored in subvalue member of lyd_value structure, so here is the pointer to the union type. In general, this type is used to get free callback for this lyd_value structure, so it must reflect the type used to store data directly in the same lyd_value instance.

union lyd_value.__unnamed__

Definition at line 572 of file tree_data.h.

Data Fields
int8_t boolean

0 as false, 1 as true

int64_t dec64

decimal64: value = dec64 / 10^fraction-digits

void * dyn_mem

Union value with some metadata. pointer to generic data type value stored in dynamic memory

struct lysc_type_bitenum_item * enum_item

pointer to the definition of the enumeration value

uint8_t fixed_mem[LYD_VALUE_FIXED_MEM_SIZE]

fixed-size buffer for a generic data type value

struct lysc_ident * ident

pointer to the schema definition of the identityref value

int16_t int16

16-bit signed integer

int32_t int32

32-bit signed integer

int64_t int64

64-bit signed integer

int8_t int8

8-bit signed integer

struct lyd_value_union * subvalue
struct ly_path * target

Instance-identifier target path, use lyd_find_target() to evaluate it on data.

uint16_t uint16

16-bit unsigned integer

uint32_t uint32

32-bit unsigned integer

uint64_t uint64

64-bit unsigned integer

uint8_t uint8

8-bit unsigned integer

struct lyd_value_binary

Special lyd_value structure for built-in binary values.

Definition at line 642 of file tree_data.h.

Data Fields
void * data

pointer to the binary value

size_t size

size of data value in bytes

struct lyd_value_bits

Special lyd_value structure for built-in bits values.

Definition at line 631 of file tree_data.h.

Data Fields
char * bitmap

bitmap of size lyplg_type_bits_bitmap_size(), if its value is cast to an integer type of the corresponding size, can be used directly as a bitmap

struct lysc_type_bitenum_item ** items

list of set pointers to the specification of the set bits (sized array)

struct lyd_value_date_and_time

Special lyd_value structure for ietf-yang-types date-and-time values.

Definition at line 696 of file tree_data.h.

Data Fields
char * fractions_s

Optional fractions of a second

time_t time

UNIX timestamp

ly_bool unknown_tz

Whether the value is in the special -00:00 timezone.

struct lyd_value_ipv4_address

Special lyd_value structure for ietf-inet-types ipv4-address values.

Definition at line 657 of file tree_data.h.

Data Fields
struct in_addr addr

IPv4 address in binary

const char * zone

Optional address zone

struct lyd_value_ipv4_address_no_zone

Special lyd_value structure for ietf-inet-types ipv4-address-no-zone values.

Definition at line 650 of file tree_data.h.

Data Fields
struct in_addr addr

IPv4 address in binary

struct lyd_value_ipv4_prefix

Special lyd_value structure for ietf-inet-types ipv4-prefix values.

Definition at line 665 of file tree_data.h.

Data Fields
struct in_addr addr

IPv4 host address in binary

uint8_t prefix

prefix length (0 - 32)

struct lyd_value_ipv6_address

Special lyd_value structure for ietf-inet-types ipv6-address values.

Definition at line 680 of file tree_data.h.

Data Fields
struct in6_addr addr

IPv6 address in binary

const char * zone

Optional address zone

struct lyd_value_ipv6_address_no_zone

Special lyd_value structure for ietf-inet-types ipv6-address-no-zone values.

Definition at line 673 of file tree_data.h.

Data Fields
struct in6_addr addr

IPv6 address in binary

struct lyd_value_ipv6_prefix

Special lyd_value structure for ietf-inet-types ipv6-prefix values.

Definition at line 688 of file tree_data.h.

Data Fields
struct in6_addr addr

IPv6 host address in binary

uint8_t prefix

prefix length (0 - 128)

struct lyd_value_union

Special lyd_value structure for built-in union values.

Represents data with multiple types (union). The lyd_value_union.value contains representation according to one of the union's types. The lyd_value_union.prefix_data provides (possible) mappings from prefixes in the original value to YANG modules. These prefixes are necessary to parse original value to the union's subtypes.

Definition at line 615 of file tree_data.h.

Data Fields
struct lysc_node * ctx_node

Context schema node.

LY_VALUE_FORMAT format

Prefix format of the value. However, this information is also used to decide whether a value is valid for the specific format or not on later validations (instance-identifier in XML looks different than in JSON).

uint32_t hints

Value hints from the parser

size_t orig_len

Original value length.

void * original

Original value.

void * prefix_data

Format-specific data for prefix resolution (see ly_resolve_prefix())

struct lyd_value value

representation of the value according to the selected union's subtype (stored as lyd_value.realtype here)

struct lyd_value_xpath10

Special lyd_value structure for ietf-yang-types xpath1.0 values.

Definition at line 705 of file tree_data.h.

Data Fields
struct ly_ctx * ctx
struct lyxp_expr * exp
LY_VALUE_FORMAT format
void * prefix_data

Macro Definition Documentation

#define LYD_HT_MIN_ITEMS   4

minimal number of children to create lyd_node_inner.children_ht hash table.

Definition at line 827 of file tree_data.h.

#define LYD_NAME (   node)    ((node)->schema ? (node)->schema->name : ((struct lyd_node_opaq *)node)->name.name)

Get the name (associated with) of a data node. Works for opaque nodes as well.

Parameters
[in]nodeNode to examine.
Returns
Data node name.

Definition at line 907 of file tree_data.h.

#define LYD_NODE_ANY   (LYS_ANYDATA)

Schema nodetype mask for lyd_node_any

Definition at line 744 of file tree_data.h.

#define LYD_NODE_INNER   (LYS_CONTAINER|LYS_LIST|LYS_RPC|LYS_ACTION|LYS_NOTIF)

Schema nodetype mask for lyd_node_inner

Definition at line 742 of file tree_data.h.

#define LYD_NODE_TERM   (LYS_LEAF|LYS_LEAFLIST)

Schema nodetype mask for lyd_node_term

Definition at line 743 of file tree_data.h.

#define LYD_VALUE_GET (   value,
  type_val 
)
Value:
((sizeof *(type_val) > LYD_VALUE_FIXED_MEM_SIZE) \
? ((type_val) = (((value)->dyn_mem))) \
: ((type_val) = ((void *)((value)->fixed_mem))))

Get the value in format specific to the type.

Should be used for any types that do not have their specific representation in the lyd_value union.

Parameters
[in]valuePointer to the value structure to read from (struct lyd_value *).
[out]type_valPointer to the type-specific value structure.

Definition at line 603 of file tree_data.h.

Typedef Documentation

typedef LY_ERR(* lyd_diff_cb)(const struct lyd_node *diff_node, struct lyd_node *data_node, void *cb_data)

Callback for diff nodes.

Parameters
[in]diff_nodeDiff node.
[in]data_nodeMatching node in data.
[in]cb_dataArbitrary callback data.
Returns
LY_ERR value.

Definition at line 2223 of file tree_data.h.

typedef LY_ERR(* lyd_merge_cb)(struct lyd_node *trg_node, const struct lyd_node *src_node, void *cb_data)

Callback for matching merge nodes.

Parameters
[in]trg_nodeTarget data node.
[in]src_nodeSource data node, is NULL if it was actually duplicated (no target node found) and its copy is trg_node.
[in]cb_dataArbitrary callback data.
Returns
LY_ERR value.

Definition at line 2133 of file tree_data.h.

Enumeration Type Documentation

XPath result type.

Enumerator
LY_XPATH_NODE_SET 

XPath node set

LY_XPATH_STRING 

XPath string

LY_XPATH_NUMBER 

XPath number

LY_XPATH_BOOLEAN 

XPath boolean

Definition at line 2597 of file tree_data.h.

Types of the different data paths.

Enumerator
LYD_PATH_STD 

Generic data path used for logging, node searching (lyd_find_xpath(), lys_find_path()) as well as creating new nodes (lyd_new_path(), lyd_new_path2(), lyd_new_ext_path()).

LYD_PATH_STD_NO_LAST_PRED 

Similar to LYD_PATH_STD except there is never a predicate on the last node. While it can be used to search for nodes, do not use it to create new data nodes (lists).

Definition at line 2354 of file tree_data.h.

Function Documentation

LIBYANG_API_DECL LY_ERR ly_time_str2time ( const char *  value,
time_t *  time,
char **  fractions_s 
)

Convert date-and-time from string to UNIX timestamp and fractions of a second.

Parameters
[in]valueValid string date-and-time value.
[out]timeUNIX timestamp.
[out]fractions_sOptional fractions of a second, set to NULL if none.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR ly_time_str2ts ( const char *  value,
struct timespec *  ts 
)

Convert date-and-time from string to timespec.

Parameters
[in]valueValid string date-and-time value.
[out]tsTimespec.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR ly_time_time2str ( time_t  time,
const char *  fractions_s,
char **  str 
)

Convert UNIX timestamp and fractions of a second into canonical date-and-time string value.

Parameters
[in]timeUNIX timestamp.
[in]fractions_sFractions of a second, if any.
[out]strString date-and-time value in the local timezone.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR ly_time_ts2str ( const struct timespec *  ts,
char **  str 
)

Convert timespec into date-and-time string value.

Parameters
[in]tsTimespec.
[out]strString date-and-time value in the local timezone.
Returns
LY_ERR value.
LIBYANG_API_DECL int ly_time_tz_offset ( void  )

Get current timezone (including DST setting) UTC (GMT) time offset in seconds.

Returns
Timezone shift in seconds.
LIBYANG_API_DECL int ly_time_tz_offset_at ( time_t  time)

Get UTC (GMT) timezone offset in seconds at a specific timestamp (including DST setting).

Parameters
[in]timeTimestamp to get the offset at.
Returns
Timezone shift in seconds.
LIBYANG_API_DECL LY_ERR lyd_any_copy_value ( struct lyd_node trg,
const union lyd_any_value value,
LYD_ANYDATA_VALUETYPE  value_type 
)

Copy anydata value from one node to another. Target value is freed first.

Parameters
[in,out]trgTarget node.
[in]valueSource value, may be NULL when the target value is only freed.
[in]value_typeSource value type.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_any_value_str ( const struct lyd_node any,
char **  value_str 
)

Get anydata string value.

Parameters
[in]anyAnyxml/anydata node to read from.
[out]value_strString representation of the value.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_change_meta ( struct lyd_meta meta,
const char *  val_str 
)

Change the value of a metadata instance.

Parameters
[in]metaMetadata to change.
[in]val_strNew value to set, any prefixes are expected in JSON format.
Returns
LY_SUCCESS if value was changed,
LY_ENOT if the values were equal and no change occurred,
LY_ERR value on other errors.
LIBYANG_API_DECL LY_ERR lyd_change_term ( struct lyd_node term,
const char *  val_str 
)

Change the value of a term (leaf or leaf-list) node to a string value.

Node changed this way is always considered explicitly set, meaning its default flag is always cleared.

Parameters
[in]termTerm node to change.
[in]val_strNew value to set, any prefixes are expected in JSON format.
Returns
LY_SUCCESS if value was changed,
LY_EEXIST if value was the same and only the default flag was cleared,
LY_ENOT if the values were equal and no change occurred,
LY_ERR value on other errors.
LIBYANG_API_DECL LY_ERR lyd_change_term_bin ( struct lyd_node term,
const void *  value,
size_t  value_len 
)

Change the value of a term (leaf or leaf-list) node to a binary value.

Node changed this way is always considered explicitly set, meaning its default flag is always cleared.

Parameters
[in]termTerm node to change.
[in]valueNew value to set in binary format (usually a pointer), see LYB Binary Format.
[in]value_lenLength of value.
Returns
LY_SUCCESS if value was changed,
LY_EEXIST if value was the same and only the default flag was cleared,
LY_ENOT if the values were equal and no change occurred,
LY_ERR value on other errors.
LIBYANG_API_DECL LY_ERR lyd_change_term_canon ( struct lyd_node term,
const char *  val_str 
)

Change the value of a term (leaf or leaf-list) node to a canonical string value.

Node changed this way is always considered explicitly set, meaning its default flag is always cleared.

Parameters
[in]termTerm node to change.
[in]val_strNew value to set in canonical (or JSON if no defined) format. If the value is not canonical, it may lead to unexpected behavior.
Returns
LY_SUCCESS if value was changed,
LY_EEXIST if value was the same and only the default flag was cleared,
LY_ENOT if the values were equal and no change occurred,
LY_ERR value on other errors.
LIBYANG_API_DECL struct lyd_node* lyd_child ( const struct lyd_node node)

Get the child pointer of a generic data node.

Decides the node's type and in case it has a children list, returns it. Supports even the opaq nodes (lyd_node_opaq).

If you need to skip key children, use lyd_child_no_keys().

Parameters
[in]nodeNode to use.
Returns
Pointer to the first child node (if any) of the node.
LIBYANG_API_DECL struct lyd_node* lyd_child_no_keys ( const struct lyd_node node)

Get the child pointer of a generic data node but skip its keys in case it is LYS_LIST.

Decides the node's type and in case it has a children list, returns it. Supports even the opaq nodes (lyd_node_opaq).

If you need to take key children into account, use lyd_child().

Parameters
[in]nodeNode to use.
Returns
Pointer to the first child node (if any) of the node.
LIBYANG_API_DECL LY_ERR lyd_compare_meta ( const struct lyd_meta meta1,
const struct lyd_meta meta2 
)

Compare 2 metadata.

If meta1 and meta2 have different contexts, they are never equivalent.

Parameters
[in]meta1First metadata.
[in]meta2Second metadata.
Returns
LY_SUCCESS if the metadata are equivalent.
LY_ENOT if not.
LIBYANG_API_DECL LY_ERR lyd_compare_siblings ( const struct lyd_node node1,
const struct lyd_node node2,
uint32_t  options 
)

Compare 2 lists of siblings if they are equivalent.

Works correctly even if node1 and node2 have different contexts.

Parameters
[in]node1The first sibling list to compare.
[in]node2The second sibling list to compare.
[in]optionsVarious Data compare options.
Returns
LY_SUCCESS if all the siblings are equivalent.
LY_ENOT if the siblings are not equivalent.
LIBYANG_API_DECL LY_ERR lyd_compare_single ( const struct lyd_node node1,
const struct lyd_node node2,
uint32_t  options 
)

Compare 2 data nodes if they are equivalent.

Works correctly even if node1 and node2 have different contexts.

Parameters
[in]node1The first node to compare.
[in]node2The second node to compare.
[in]optionsVarious Data compare options.
Returns
LY_SUCCESS if the nodes are equivalent.
LY_ENOT if the nodes are not equivalent.
LIBYANG_API_DECL LY_ERR lyd_diff_apply_all ( struct lyd_node **  data,
const struct lyd_node diff 
)

Apply the whole diff tree on a data tree.

Details are mentioned in lyd_diff_apply_module().

Parameters
[in,out]dataData to apply the diff on.
[in]diffDiff to apply.
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_apply_module ( struct lyd_node **  data,
const struct lyd_node diff,
const struct lys_module mod,
lyd_diff_cb  diff_cb,
void *  cb_data 
)

Apply the whole diff on a data tree but restrict the operation to one module.

__!! Caution !!__ If applying a diff that was created without the LYD_DIFF_DEFAULTS flag, there may be some duplicate values created. Unless the resulting tree is validated (and default values thus consolidated), using it further (such as applying another diff) may cause unexpected results or errors.

Parameters
[in,out]dataData to apply the diff on.
[in]diffDiff to apply.
[in]modModule, whose diff/data only to consider, NULL for all modules.
[in]diff_cbOptional diff callback that will be called for every changed node.
[in]cb_dataArbitrary callback data.
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_merge_all ( struct lyd_node **  diff,
const struct lyd_node src_diff,
uint16_t  options 
)

Merge 2 diffs into each other.

Details are mentioned in lyd_diff_merge_module().

Parameters
[in,out]diffTarget diff to merge into.
[in]src_diffSource diff.
[in]optionsBitmask of options flags, see Data diff merge options..
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_merge_module ( struct lyd_node **  diff,
const struct lyd_node src_diff,
const struct lys_module mod,
lyd_diff_cb  diff_cb,
void *  cb_data,
uint16_t  options 
)

Merge 2 diffs into each other but restrict the operation to one module.

The diffs must be possible to be merged, which is guaranteed only if the source diff was created on data that had the target diff applied on them. In other words, this sequence is legal

1) get diff1 from data1 and data2 -> get data11 from apply diff1 on data1 -> get diff2 from data11 and data3 -> -> get data 33 from apply diff2 on data1

and reusing these diffs

2) get diff11 from merge diff1 and diff2 -> get data33 from apply diff11 on data1

Parameters
[in,out]diffTarget diff to merge into.
[in]src_diffSource diff.
[in]modModule, whose diff only to consider, NULL for all modules.
[in]diff_cbOptional diff callback that will be called for every merged node. Param diff_node is the source diff node while data_node is the updated target diff node. In case a whole subtree is added, the callback is called on the root with diff_node being NULL.
[in]cb_dataArbitrary callback data.
[in]optionsBitmask of options flags, see Data diff merge options..
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_merge_tree ( struct lyd_node **  diff_first,
struct lyd_node diff_parent,
const struct lyd_node src_sibling,
lyd_diff_cb  diff_cb,
void *  cb_data,
uint16_t  options 
)

Merge 2 diff trees into each other.

Details are mentioned in lyd_diff_merge_module().

Parameters
[in,out]diff_firstTarget diff first sibling to merge into.
[in]diff_parentTarget diff parent to merge into.
[in]src_siblingSource diff sibling to merge.
[in]diff_cbOptional diff callback that will be called for every merged node. Param diff_node is the source diff node while data_node is the updated target diff node. In case a whole subtree is added, the callback is called on the root with diff_node being NULL.
[in]cb_dataArbitrary callback data.
[in]optionsBitmask of options flags, see Data diff merge options..
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_reverse_all ( const struct lyd_node src_diff,
struct lyd_node **  diff 
)

Reverse a diff and make the opposite changes. Meaning change create to delete, delete to create, or move from place A to B to move from B to A and so on.

Parameters
[in]src_diffDiff to reverse.
[out]diffReversed diff.
Returns
LY_SUCCESS on success.
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_siblings ( const struct lyd_node first,
const struct lyd_node second,
uint16_t  options,
struct lyd_node **  diff 
)

Learn the differences between 2 data trees including all the following siblings.

Details are mentioned in lyd_diff_tree().

Parameters
[in]firstFirst data tree.
[in]secondSecond data tree.
[in]optionsBitmask of options flags, see Data diff options..
[out]diffGenerated diff, NULL if there are no differences.
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_diff_tree ( const struct lyd_node first,
const struct lyd_node second,
uint16_t  options,
struct lyd_node **  diff 
)

Learn the differences between 2 data trees.

The resulting diff is represented as a data tree with specific metadata from the internal 'yang' module. Most importantly, every node has an effective 'operation' metadata. If there is none defined on the node, it inherits the operation from the nearest parent. Top-level nodes must always have the 'operation' metadata defined. Additional metadata ('orig-default', 'value', 'orig-value', 'key', 'orig-key') are used for storing more information about the value in the first or the second tree.

The diff tree is completely independent on the first and second trees, meaning all the information about the change is stored in the diff and the trees are not needed.

__!! Caution !!__ The diff tree should never be validated because it may easily not be valid! For example, when data from one case branch are deleted and data from another branch created - data from both branches are then stored in the diff tree simultaneously.

Parameters
[in]firstFirst data tree.
[in]secondSecond data tree.
[in]optionsBitmask of options flags, see Data diff options..
[out]diffGenerated diff, NULL if there are no differences.
Returns
LY_SUCCESS on success,
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_dup_meta_single ( const struct lyd_meta meta,
struct lyd_node parent,
struct lyd_meta **  dup 
)

Create a copy of the metadata.

Parameters
[in]metaMetadata to copy.
[in]parentNode where to append the new metadata.
[out]dupOptional created metadata copy.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_dup_siblings ( const struct lyd_node node,
struct lyd_node_inner parent,
uint32_t  options,
struct lyd_node **  dup 
)

Create a copy of the specified data tree node with any following siblings. Schema references are kept the same.

Parameters
[in]nodeData tree node to be duplicated.
[in]parentOptional parent node where to connect the duplicated node(s). If set in combination with LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with parent.
[in]optionsBitmask of options flags, see Data duplication options.
[out]dupOptional created copy of the node. Note that in case the parents chain is duplicated for the duplicated node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_dup_siblings_to_ctx ( const struct lyd_node node,
const struct ly_ctx trg_ctx,
struct lyd_node_inner parent,
uint32_t  options,
struct lyd_node **  dup 
)

Create a copy of the specified data tree node with any following siblings. Schema references are assigned from trg_ctx.

Parameters
[in]nodeData tree node to be duplicated.
[in]trg_ctxTarget context for duplicated nodes.
[in]parentOptional parent node where to connect the duplicated node(s). If set in combination with LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with parent.
[in]optionsBitmask of options flags, see Data duplication options.
[out]dupOptional created copy of the node. Note that in case the parents chain is duplicated for the duplicated node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_dup_single ( const struct lyd_node node,
struct lyd_node_inner parent,
uint32_t  options,
struct lyd_node **  dup 
)

Create a copy of the specified data tree node. Schema references are kept the same.

Parameters
[in]nodeData tree node to be duplicated.
[in]parentOptional parent node where to connect the duplicated node(s). If set in combination with LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with parent.
[in]optionsBitmask of options flags, see Data duplication options.
[out]dupOptional created copy of the node. Note that in case the parents chain is duplicated for the duplicated node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_dup_single_to_ctx ( const struct lyd_node node,
const struct ly_ctx trg_ctx,
struct lyd_node_inner parent,
uint32_t  options,
struct lyd_node **  dup 
)

Create a copy of the specified data tree node. Schema references are assigned from trg_ctx.

Parameters
[in]nodeData tree node to be duplicated.
[in]trg_ctxTarget context for duplicated nodes.
[in]parentOptional parent node where to connect the duplicated node(s). If set in combination with LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with parent.
[in]optionsBitmask of options flags, see Data duplication options.
[out]dupOptional created copy of the node. Note that in case the parents chain is duplicated for the duplicated node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_eval_xpath ( const struct lyd_node ctx_node,
const char *  xpath,
ly_bool result 
)

Evaluate an XPath on data and return the result converted to boolean.

Optimizations similar as in lyd_find_xpath().

Parameters
[in]ctx_nodeXPath context node.
[in]xpathXPath to select.
[out]resultExpression result converted to boolean.
Returns
LY_SUCCESS on success, result is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL LY_ERR lyd_eval_xpath2 ( const struct lyd_node ctx_node,
const char *  xpath,
const struct lyxp_var *  vars,
ly_bool result 
)

Evaluate an XPath on data and return the result converted to boolean.

It is lyd_eval_xpath() with vars added.

Parameters
[in]ctx_nodeXPath context node.
[in]xpathXPath to select.
[in]varsSized array of XPath variables.
[out]resultExpression result converted to boolean.
Returns
LY_SUCCESS on success, result is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL LY_ERR lyd_eval_xpath3 ( const struct lyd_node ctx_node,
const struct lys_module cur_mod,
const char *  xpath,
LY_VALUE_FORMAT  format,
void *  prefix_data,
const struct lyxp_var *  vars,
ly_bool result 
)

Evaluate an XPath on data and return the result converted to boolean.

It is lyd_eval_xpath2() with format and prefix_data added for special use-cases.

Parameters
[in]ctx_nodeXPath context node.
[in]cur_modCurrent module of xpath, needed for some kinds of format.
[in]xpathXPath to select.
[in]formatFormat of any prefixes in xpath.
[in]prefix_dataFormat-specific prefix data.
[in]varsSized array of XPath variables.
[out]resultExpression result converted to boolean.
Returns
LY_SUCCESS on success, result is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL LY_ERR lyd_eval_xpath4 ( const struct lyd_node ctx_node,
const struct lyd_node tree,
const struct lys_module cur_mod,
const char *  xpath,
LY_VALUE_FORMAT  format,
void *  prefix_data,
const struct lyxp_var *  vars,
LY_XPATH_TYPE ret_type,
struct ly_set **  node_set,
char **  string,
long double *  number,
ly_bool boolean 
)

Evaluate an XPath on data and return the result or convert it first to an expected result type.

Either all return type parameters node_set, string, number, and boolean with ret_type are provided or exactly one of node_set, string, number, and boolean is provided with ret_type being obvious and hence optional.

Parameters
[in]ctx_nodeXPath context node, NULL for the root node.
[in]treeData tree to evaluate on.
[in]cur_modCurrent module of xpath, needed for some kinds of format.
[in]xpathXPath to select.
[in]formatFormat of any prefixes in xpath.
[in]prefix_dataFormat-specific prefix data.
[in]varsOptional sized array of XPath variables.
[out]ret_typeXPath type of the result selecting which of node_set, string, number, and boolean to use.
[out]node_setXPath node set result.
[out]stringXPath string result.
[out]numberXPath number result.
[out]booleanXPath boolean result.
Returns
LY_SUCCESS on success.
LY_ERR value on error.
LIBYANG_API_DECL struct lyd_meta* lyd_find_meta ( const struct lyd_meta first,
const struct lys_module module,
const char *  name 
)

Find a specific metadata.

Parameters
[in]firstFirst metadata to consider.
[in]moduleModule of the metadata definition, may be NULL if name includes a prefix.
[in]nameName of the metadata to find, may not include a prefix (module name) if module is set.
Returns
Found metadata,
NULL if not found.
LIBYANG_API_DECL LY_ERR lyd_find_path ( const struct lyd_node ctx_node,
const char *  path,
ly_bool  output,
struct lyd_node **  match 
)

Search in given data for a node uniquely identified by a path.

Always works in constant (O(1)) complexity. To be exact, it is O(n) where n is the depth of the path used.

Opaque nodes are NEVER found/traversed.

Parameters
[in]ctx_nodePath context node.
[in]pathPath to find.
[in]outputWhether to search in RPC/action output nodes or in input nodes.
[out]matchCan be NULL, otherwise the found data node.
Returns
LY_SUCCESS on success, match is set to the found node.
LY_EINCOMPLETE if only a parent of the node was found, match is set to this parent node.
LY_ENOTFOUND if no nodes in the path were found.
LY_ERR on other errors.
LIBYANG_API_DECL LY_ERR lyd_find_sibling_dup_inst_set ( const struct lyd_node siblings,
const struct lyd_node target,
struct ly_set **  set 
)

Search the given siblings for all the exact same instances of a specific node instance. Uses hashes to whatever extent possible.

Parameters
[in]siblingsSiblings to search in including preceding and succeeding nodes.
[in]targetTarget node instance to find.
[out]setSet with all the found instances. The first item is always the first instance.
Returns
LY_SUCCESS on success, set returned.
LY_ENOTFOUND if not found, empty set returned.
LY_ERR value if another error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_sibling_first ( const struct lyd_node siblings,
const struct lyd_node target,
struct lyd_node **  match 
)

Search in the given siblings (NOT recursively) for the first target instance with the same value. Uses hashes - should be used whenever possible for best performance.

Parameters
[in]siblingsSiblings to search in including preceding and succeeding nodes.
[in]targetTarget node to find.
[out]matchCan be NULL, otherwise the found data node.
Returns
LY_SUCCESS on success, match set.
LY_ENOTFOUND if not found, match set to NULL.
LY_ERR value if another error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_sibling_opaq_next ( const struct lyd_node first,
const char *  name,
struct lyd_node **  match 
)

Search the given siblings for an opaque node with a specific name.

Parameters
[in]firstFirst sibling to consider.
[in]nameOpaque node name to find.
[out]matchCan be NULL, otherwise the found data node.
Returns
LY_SUCCESS on success, match set.
LY_ENOTFOUND if not found, match set to NULL.
LY_ERR value is an error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_sibling_val ( const struct lyd_node siblings,
const struct lysc_node schema,
const char *  key_or_value,
size_t  val_len,
struct lyd_node **  match 
)

Search in the given siblings for the first schema instance. Uses hashes - should be used whenever possible for best performance.

Parameters
[in]siblingsSiblings to search in including preceding and succeeding nodes.
[in]schemaSchema node of the data node to find.
[in]key_or_valueIf it is NULL, the first schema node data instance is found. For nodes with many instances, it can be set based on the type of schema: LYS_LEAFLIST: Searched instance value. LYS_LIST: Searched instance key values in the form of "[key1='val1'][key2='val2']...". The keys do not have to be ordered but all of them must be set.

Note that any explicit values (leaf-list or list key values) will be canonized first before comparison. But values that do not have a canonical value are expected to be in the JSON format!

Parameters
[in]val_lenOptional length of key_or_value in case it is not 0-terminated.
[out]matchCan be NULL, otherwise the found data node.
Returns
LY_SUCCESS on success, match set.
LY_ENOTFOUND if not found, match set to NULL.
LY_EINVAL if schema is a key-less list.
LY_ERR value if another error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_target ( const struct ly_path *  path,
const struct lyd_node tree,
struct lyd_node **  match 
)

Find the target node of a compiled path (lyd_value instance-identifier).

Parameters
[in]pathCompiled path structure.
[in]treeData tree to be searched.
[out]matchCan be NULL, otherwise the found data node.
Returns
LY_SUCCESS on success, match is set to the found node.
LY_ENOTFOUND if no match was found.
LY_ERR on other errors.
LIBYANG_API_DECL LY_ERR lyd_find_xpath ( const struct lyd_node ctx_node,
const char *  xpath,
struct ly_set **  set 
)

Search in the given data for instances of nodes matching the provided XPath.

If a list instance is being selected with all its key values specified and ordered in the form list[key1=...][key2=...][key3=...] or a leaf-list instance in the form leaf-list[.=...], these instances are found using hashes with constant (O(1)) complexity (unless they are defined in top-level). Other predicates can still follow the aforementioned ones.

Opaque nodes are part of the evaluation.

Parameters
[in]ctx_nodeXPath context node.
[in]xpathXPath to select in JSON format. It must evaluate into a node set.
[out]setSet of found data nodes. In case the result is a number, a string, or a boolean, the returned set is empty.
Returns
LY_SUCCESS on success, set is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_xpath2 ( const struct lyd_node ctx_node,
const char *  xpath,
const struct lyxp_var *  vars,
struct ly_set **  set 
)

Search in the given data for instances of nodes matching the provided XPath.

It is lyd_find_xpath() with vars added.

Parameters
[in]ctx_nodeXPath context node.
[in]xpathXPath to select in JSON format.
[in]varsSized array of XPath variables.
[out]setSet of found data nodes. In case the result is a number, a string, or a boolean, the returned set is empty.
Returns
LY_SUCCESS on success, set is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_xpath3 ( const struct lyd_node ctx_node,
const struct lyd_node tree,
const char *  xpath,
const struct lyxp_var *  vars,
struct ly_set **  set 
)

Search in the given data for instances of nodes matching the provided XPath.

It is lyd_find_xpath2() with tree added so that ctx_node may be the root.

Parameters
[in]ctx_nodeXPath context node, NULL for the root node.
[in]treeData tree to evaluate on.
[in]xpathXPath to select in JSON format.
[in]varsSized array of XPath variables.
[out]setSet of found data nodes. In case the result is a number, a string, or a boolean, the returned set is empty.
Returns
LY_SUCCESS on success, set is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL LY_ERR lyd_find_xpath4 ( const struct lyd_node ctx_node,
const struct lyd_node tree,
const char *  xpath,
LY_VALUE_FORMAT  format,
void *  prefix_data,
const struct lyxp_var *  vars,
struct ly_set **  set 
)

Search in the given data for instances of nodes matching the provided XPath.

It is lyd_find_xpath3() with format and prefix_data added for special use-cases.

Parameters
[in]ctx_nodeXPath context node, NULL for the root node.
[in]treeData tree to evaluate on.
[in]xpathXPath to select with prefix in format.
[in]formatFormat of any prefixes in xpath.
[in]prefix_dataFormat-specific prefix data.
[in]varsSized array of XPath variables.
[out]setSet of found data nodes. In case the result is a number, a string, or a boolean, the returned set is empty.
Returns
LY_SUCCESS on success, set is returned.
LY_ERR value if an error occurred.
LIBYANG_API_DECL struct lyd_node* lyd_first_sibling ( const struct lyd_node node)

Get the first sibling of the given node.

Parameters
[in]nodeNode which first sibling is going to be the result.
Returns
The first sibling of the given node or the node itself if it is the first child of the parent.
LIBYANG_API_DECL void lyd_free_all ( struct lyd_node node)

Free all the nodes (even parents of the node) in the data tree.

Parameters
[in]nodeAny of the nodes inside the tree.
LIBYANG_API_DECL void lyd_free_attr_siblings ( const struct ly_ctx ctx,
struct lyd_attr attr 
)

Free the attribute with any following attributes.

Parameters
[in]ctxContext where the attributes were created.
[in]attrFirst attribute to free.
LIBYANG_API_DECL void lyd_free_attr_single ( const struct ly_ctx ctx,
struct lyd_attr attr 
)

Free a single attribute.

Parameters
[in]ctxContext where the attributes were created.
[in]attrAttribute to free.
LIBYANG_API_DECL void lyd_free_meta_siblings ( struct lyd_meta meta)

Free the metadata instance with any following instances.

Parameters
[in]metaMetadata to free.
LIBYANG_API_DECL void lyd_free_meta_single ( struct lyd_meta meta)

Free a single metadata instance.

Parameters
[in]metaMetadata to free.
LIBYANG_API_DECL void lyd_free_siblings ( struct lyd_node node)

Free all the sibling nodes (preceding as well as succeeding).

Parameters
[in]nodeAny of the sibling nodes to free.
LIBYANG_API_DECL void lyd_free_tree ( struct lyd_node node)

Free (and unlink) the specified data (sub)tree.

Parameters
[in]nodeRoot of the (sub)tree to be freed.
LIBYANG_API_DECL const char* lyd_get_value ( const struct lyd_node node)

Get the (canonical) value of a data node.

Parameters
[in]nodeData node to use.
Returns
Canonical value.
LIBYANG_API_DECL LY_ERR lyd_insert_after ( struct lyd_node sibling,
struct lyd_node node 
)

Insert a node after another node, can be used only for user-ordered nodes. If inserting several siblings, each of them must be inserted individually.

  • if the node is part of some other tree, it is automatically unlinked.
Parameters
[in]siblingSibling node to insert after.
[in]nodeNode to insert.
Returns
LY_SUCCESS on success.
LY_ERR error on error.
LIBYANG_API_DECL LY_ERR lyd_insert_before ( struct lyd_node sibling,
struct lyd_node node 
)

Insert a node before another node, can be used only for user-ordered nodes. If inserting several siblings, each of them must be inserted individually.

  • if the node is part of some other tree, it is automatically unlinked.
Parameters
[in]siblingSibling node to insert before.
[in]nodeNode to insert.
Returns
LY_SUCCESS on success.
LY_ERR error on error.
LIBYANG_API_DECL LY_ERR lyd_insert_child ( struct lyd_node parent,
struct lyd_node node 
)

Insert a child into a parent.

  • if the node is part of some other tree, it is automatically unlinked.
  • if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
Parameters
[in]parentParent node to insert into.
[in]nodeNode to insert.
Returns
LY_SUCCESS on success.
LY_ERR error on error.
LIBYANG_API_DECL LY_ERR lyd_insert_sibling ( struct lyd_node sibling,
struct lyd_node node,
struct lyd_node **  first 
)

Insert a node into siblings.

  • if the node is part of some other tree, it is automatically unlinked.
  • if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
Parameters
[in]siblingSiblings to insert into, can even be NULL.
[in]nodeNode to insert.
[out]firstOptionally return the first sibling after insertion. Can be the address of sibling.
Returns
LY_SUCCESS on success.
LY_ERR error on error.
LIBYANG_API_DECL ly_bool lyd_is_default ( const struct lyd_node node)

Check whether a node value equals to its default one.

Parameters
[in]nodeTerm node to test.
Returns
false (no, it is not a default node) or true (yes, it is default)
LIBYANG_API_DECL uint32_t lyd_list_pos ( const struct lyd_node instance)

Learn the relative position of a list or leaf-list instance within other instances of the same schema node.

Parameters
[in]instanceList or leaf-list instance to get the position of.
Returns
0 on error.
Positive integer of the instance position.
LIBYANG_API_DECL int lyd_lyb_data_length ( const char *  data)

Learn the length of LYB data.

Parameters
[in]dataLYB data to examine.
Returns
Length of the LYB data chunk,
-1 on error.
LIBYANG_API_DECL LY_ERR lyd_merge_module ( struct lyd_node **  target,
const struct lyd_node source,
const struct lys_module mod,
lyd_merge_cb  merge_cb,
void *  cb_data,
uint16_t  options 
)

Merge all the nodes of a module from source data tree into the target data tree. Merge may not be complete until validation called on the resulting data tree (data from more cases may be present, default and non-default values).

Parameters
[in,out]targetTarget data tree to merge into, must be a top-level tree. Always points to the first sibling.
[in]sourceSource data tree to merge, must be a top-level tree.
[in]modModule, whose source data only to consider, NULL for all modules.
[in]merge_cbOptional merge callback that will be called for every merged node, before merging its descendants. If a subtree is being added into target (no matching node found), callback is called only once with the subtree root.
[in]cb_dataArbitrary callback data.
[in]optionsBitmask of option flags, see Data merge options..
Returns
LY_SUCCESS on success,
LY_ERR value on error.
LIBYANG_API_DECL LY_ERR lyd_merge_siblings ( struct lyd_node **  target,
const struct lyd_node source,
uint16_t  options 
)

Merge the source data tree with any following siblings into the target data tree. Merge may not be complete until validation called on the resulting data tree (data from more cases may be present, default and non-default values).

Example input:

source (A1) - A2 - A3 target (B1) - B2 - B3 /\ /\ /\ /\ /\ /\ .... .... .... .... .... ....

result target (A1) - A2 - A3 - B1 - B2 - B3 /\ /\ /\ /\ /\ /\ .... .... .... .... .... ....

Parameters
[in,out]targetTarget data tree to merge into, must be a top-level tree. Always points to the first sibling.
[in]sourceSource data tree to merge, must be a top-level tree.
[in]optionsBitmask of option flags, see Data merge options..
Returns
LY_SUCCESS on success,
LY_ERR value on error.
LIBYANG_API_DECL LY_ERR lyd_merge_tree ( struct lyd_node **  target,
const struct lyd_node source,
uint16_t  options 
)

Merge the source data subtree into the target data tree. Merge may not be complete until validation is called on the resulting data tree (data from more cases may be present, default and non-default values).

Example input:

source (A1) - A2 - A3 target (B1) - B2 - B3 /\ /\ /\ /\ /\ /\ .... .... .... .... .... ....

result target (A1) - B1 - B2 - B3 /\ /\ /\ /\ .... .... .... ....

Parameters
[in,out]targetTarget data tree to merge into, must be a top-level tree. Always points to the first sibling.
[in]sourceSource data tree to merge, must be a top-level tree.
[in]optionsBitmask of option flags, see Data merge options..
Returns
LY_SUCCESS on success,
LY_ERR value on error.
LIBYANG_API_DECL LY_ERR lyd_new_any ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const void *  value,
ly_bool  use_value,
LYD_ANYDATA_VALUETYPE  value_type,
ly_bool  output,
struct lyd_node **  node 
)

Create a new any node in the data tree.

To create a top-level any node defined in an extension instance, use lyd_new_ext_any().

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node can be LYS_ANYDATA or LYS_ANYXML.
[in]valueValue for the node. Expected type is determined by value_type.
[in]use_valueWhether to use dynamic value or make a copy.
[in]value_typeType of the provided value in value.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_attr ( struct lyd_node parent,
const char *  module_name,
const char *  name,
const char *  value,
struct lyd_attr **  attr 
)

Create new JSON attribute for an opaque data node. To create an XML attribute, use lyd_new_attr2().

Note that for an attribute to be later resolved as YANG metadata, it needs module_nane and a prefix in name.

Parameters
[in]parentParent opaque node for the attribute.
[in]module_nameOptional name of the module of the attribute.
[in]nameAttribute name with optional prefix, which is a module name. If the prefix is set, it is also stored as the explicit module name if module_name is not set.
[in]valueOptional attribute value.
[out]attrOptional created attribute.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_attr2 ( struct lyd_node parent,
const char *  module_ns,
const char *  name,
const char *  value,
struct lyd_attr **  attr 
)

Create new XML attribute for an opaque data node. To create a JSON attribute, use lyd_new_attr().

Note that for an attribute to be later resolved as YANG metadata, it needs module_ns and a prefix in name.

Parameters
[in]parentParent opaque node for the attribute being created.
[in]module_nsOptional namespace of the module of the attribute.
[in]nameAttribute name with optional prefix, which is an XML prefix.
[in]valueOptional attribute value.
[out]attrOptional created attribute.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_ext_any ( const struct lysc_ext_instance ext,
const char *  name,
const void *  value,
ly_bool  use_value,
LYD_ANYDATA_VALUETYPE  value_type,
struct lyd_node **  node 
)

Create a new top-level any node defined in the given extension instance.

To create an any node with parent (no matter if defined inside extension instance or a standard tree) or a top-level any node of a standard module's tree, use lyd_new_any().

Parameters
[in]extExtension instance where the any node being created is defined.
[in]nameSchema node name of the new data node. The node can be LYS_ANYDATA or LYS_ANYXML.
[in]valueValue for the node. Expected type is determined by value_type.
[in]use_valueWhether to use dynamic value or make a copy.
[in]value_typeType of the provided value in value.
[out]nodeThe created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_ext_inner ( const struct lysc_ext_instance ext,
const char *  name,
struct lyd_node **  node 
)

Create a new top-level inner node defined in the given extension instance.

To create list, use lyd_new_list() or lyd_new_list2().

To create an inner node with parent (no matter if defined inside extension instance or a standard tree) or a top-level node of a standard module's tree, use lyd_new_inner().

Parameters
[in]extExtension instance where the inner node being created is defined.
[in]nameSchema node name of the new data node. The node can be LYS_CONTAINER, LYS_NOTIF, LYS_RPC, or LYS_ACTION.
[out]nodeThe created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_ext_list ( const struct lysc_ext_instance ext,
const char *  name,
struct lyd_node **  node,
  ... 
)

Create a new top-level list node defined in the given extension instance.

To create a list node with parent (no matter if defined inside extension instance or a standard tree) or a top-level list node of a standard module's tree, use lyd_new_list() or lyd_new_list2().

Parameters
[in]extExtension instance where the list node being created is defined.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[out]nodeThe created node.
[in]...Ordered key values of the new list instance, all must be set. In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for key-less lists.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_ext_path ( struct lyd_node parent,
const struct lysc_ext_instance ext,
const char *  path,
const void *  value,
uint32_t  options,
struct lyd_node **  node 
)

Create a new node defined in the given extension instance. In case of anyxml/anydata nodes, this function expects the value as string.

If creating data nodes defined in a module's standard tree, use lyd_new_path() or lyd_new_path2().

Details are mentioned in lyd_new_path().

Parameters
[in]parentData parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used, it may no longer be first if path is absolute and starts with a non-existing top-level node inserted before parent. Use lyd_first_sibling() to adjust parent in these cases.
[in]extExtension instance where the node being created is defined.
[in]pathPath to create.
[in]valueValue of the new leaf/leaf-list. For other node types, it should be NULL.
[in]optionsBitmask of options, see Data path creation options.
[out]nodeOptional first created node.
Returns
LY_SUCCESS on success.
LY_EEXIST if the final node to create exists (unless LYD_NEW_PATH_UPDATE is used).
LY_EINVAL on invalid arguments including invalid path.
LY_EVALID on invalid value.
LY_ERR on other errors.
LIBYANG_API_DECL LY_ERR lyd_new_ext_term ( const struct lysc_ext_instance ext,
const char *  name,
const char *  val_str,
struct lyd_node **  node 
)

Create a new top-level term node defined in the given extension instance.

To create a term node with parent (no matter if defined inside extension instance or a standard tree) or a top-level node of a standard module's tree, use lyd_new_term().

Parameters
[in]extExtension instance where the term node being created is defined.
[in]nameSchema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]val_strString form of the value of the node being created. In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes).
[out]nodeThe created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_implicit_all ( struct lyd_node **  tree,
const struct ly_ctx ctx,
uint32_t  implicit_options,
struct lyd_node **  diff 
)

Add any missing implicit nodes. Default nodes with a false "when" are not added.

Parameters
[in,out]treeTree to add implicit nodes into. Note that in case a first top-level sibling is used, it may no longer be first if an implicit node was inserted before tree. Use lyd_first_sibling() to adjust tree in these cases.
[in]ctxlibyang context, must be set only if tree is an empty tree.
[in]implicit_optionsOptions for implicit node creation, see Implicit node creation options.
[out]diffOptional diff with any created nodes.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_implicit_module ( struct lyd_node **  tree,
const struct lys_module module,
uint32_t  implicit_options,
struct lyd_node **  diff 
)

Add any missing implicit nodes of one module. Default nodes with a false "when" are not added.

Parameters
[in,out]treeTree to add implicit nodes into. Note that in case a first top-level sibling is used, it may no longer be first if an implicit node was inserted before tree. Use lyd_first_sibling() to adjust tree in these cases.
[in]moduleModule whose implicit nodes to create.
[in]implicit_optionsOptions for implicit node creation, see Implicit node creation options.
[out]diffOptional diff with any created nodes.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_implicit_tree ( struct lyd_node tree,
uint32_t  implicit_options,
struct lyd_node **  diff 
)

Add any missing implicit nodes into a data subtree. Default nodes with a false "when" are not added.

Parameters
[in]treeTree to add implicit nodes into.
[in]implicit_optionsOptions for implicit node creation, see Implicit node creation options.
[out]diffOptional diff with any created nodes.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_inner ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
ly_bool  output,
struct lyd_node **  node 
)

Create a new inner node in the data tree.

To create list, use lyd_new_list() or lyd_new_list2().

To create a top-level inner node defined in an extension instance, use lyd_new_ext_inner().

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node can be LYS_CONTAINER, LYS_NOTIF, LYS_RPC, or LYS_ACTION.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
ly_bool  output,
struct lyd_node **  node,
  ... 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
[in]...Ordered key values of the new list instance, all must be set. In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for key-less lists.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list2 ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const char *  keys,
ly_bool  output,
struct lyd_node **  node 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]keysAll key values predicate in the form of "[key1='val1'][key2='val2']...", they do not have to be ordered. In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes). Use NULL or string of length 0 in case of key-less list.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list3 ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const char **  key_values,
uint32_t *  value_lengths,
ly_bool  output,
struct lyd_node **  node 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]formatFormat of key values.
[in]key_valuesOrdered key string values of the new list instance, all must be set.
[in]value_lengthsArray of lengths of each key_values, may be NULL if key_values are 0-terminated strings.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list3_bin ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const void **  key_values,
uint32_t *  value_lengths,
ly_bool  output,
struct lyd_node **  node 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]formatFormat of key values.
[in]key_valuesOrdered key binary (LYB) values of the new list instance, all must be set.
[in]value_lengthsArray of lengths of each key_values.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list3_canon ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const char **  key_values,
uint32_t *  value_lengths,
ly_bool  output,
struct lyd_node **  node 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]formatFormat of key values.
[in]key_valuesOrdered key canonical values of the new list instance, all must be set.
[in]value_lengthsArray of lengths of each key_values, may be NULL if key_values are 0-terminated strings.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list_bin ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
ly_bool  output,
struct lyd_node **  node,
  ... 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
[in]...Ordered binary key values of the new list instance, all must be set. Every key value must be followed by its length. No keys are expected for key-less lists.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_list_canon ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
ly_bool  output,
struct lyd_node **  node,
  ... 
)

Create a new list node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node must be LYS_LIST.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
[in]...Ordered canonical key values of the new list instance, all must be set. No keys are expected for key-less lists.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_meta ( const struct ly_ctx ctx,
struct lyd_node parent,
const struct lys_module module,
const char *  name,
const char *  val_str,
ly_bool  clear_dflt,
struct lyd_meta **  meta 
)

Create new metadata.

Parameters
[in]ctxlibyang context,
[in]parentOptional parent node for the metadata being created. Must be set if meta is NULL.
[in]moduleModule of the metadata being created. If NULL, name must include module name as the prefix.
[in]nameAnnotation name of the new metadata. It can include the annotation module as the prefix. If the prefix is specified it is always used but if not specified, module must be set.
[in]val_strString form of the value of the metadata. In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes).
[in]clear_dfltWhether to clear the default flag starting from parent, recursively all NP containers.
[out]metaOptional created metadata. Must be set if parent is NULL.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_meta2 ( const struct ly_ctx ctx,
struct lyd_node parent,
ly_bool  clear_dflt,
const struct lyd_attr attr,
struct lyd_meta **  meta 
)

Create new metadata from an opaque node attribute if possible.

Parameters
[in]ctxlibyang context.
[in]parentOptional parent node for the metadata being created. Must be set if meta is NULL.
[in]clear_dfltWhether to clear the default flag starting from parent, recursively all NP containers.
[in]attrOpaque node attribute to parse into metadata.
[out]metaOptional created metadata. Must be set if parent is NULL.
Returns
LY_SUCCESS on success.
LY_ENOT if the attribute could not be parsed into any metadata.
LY_ERR on error.
LIBYANG_API_DECL LY_ERR lyd_new_opaq ( struct lyd_node parent,
const struct ly_ctx ctx,
const char *  name,
const char *  value,
const char *  prefix,
const char *  module_name,
struct lyd_node **  node 
)

Create a new JSON opaque node in the data tree. To create an XML opaque node, use lyd_new_opaq2().

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]ctxlibyang context. If NULL, parent context will be used.
[in]nameNode name.
[in]valueOptional node value.
[in]prefixOptional node prefix, must be equal to module_name if set.
[in]module_nameNode module name.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_opaq2 ( struct lyd_node parent,
const struct ly_ctx ctx,
const char *  name,
const char *  value,
const char *  prefix,
const char *  module_ns,
struct lyd_node **  node 
)

Create a new XML opaque node in the data tree. To create a JSON opaque node, use lyd_new_opaq().

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]ctxlibyang context. If NULL, parent context will be used.
[in]nameNode name.
[in]valueOptional node value.
[in]prefixOptional node prefix.
[in]module_nsNode module namespace.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_path ( struct lyd_node parent,
const struct ly_ctx ctx,
const char *  path,
const char *  value,
uint32_t  options,
struct lyd_node **  node 
)

Create a new node in the data tree based on a path. If creating anyxml/anydata nodes, lyd_new_path2 should be used instead, this function expects the value as string.

If creating data nodes defined inside an extension instance, use lyd_new_ext_path().

If path points to a list key, the key value from the predicate is used and value is ignored. Also, if a leaf-list is being created and both a predicate is defined in path and value is set, the predicate is preferred.

For key-less lists, positional predicates must be used (indices starting from 1). For non-configuration leaf-lists either positional predicate can be used or leaf-list predicate, when an instance is always created at the end. If no predicate is used for these nodes, they are always created.

Parameters
[in]parentData parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used, it may no longer be first if path is absolute and starts with a non-existing top-level node inserted before parent. Use lyd_first_sibling() to adjust parent in these cases.
[in]ctxlibyang context, must be set if parent is NULL.
[in]pathPath to create.
[in]valueString value of the new leaf/leaf-list. If it varies based on the format, LY_VALUE_JSON is expected. For other node types, it should be NULL.
[in]optionsBitmask of options, see Data path creation options.
[out]nodeOptional first created node.
Returns
LY_SUCCESS on success.
LY_EEXIST if the final node to create exists (unless LYD_NEW_PATH_UPDATE is used).
LY_EINVAL on invalid arguments including invalid path.
LY_EVALID on invalid value.
LY_ERR on other errors.
LIBYANG_API_DECL LY_ERR lyd_new_path2 ( struct lyd_node parent,
const struct ly_ctx ctx,
const char *  path,
const void *  value,
size_t  value_len,
LYD_ANYDATA_VALUETYPE  value_type,
uint32_t  options,
struct lyd_node **  new_parent,
struct lyd_node **  new_node 
)

Create a new node in the data tree based on a path. All node types can be created.

Details are mentioned in lyd_new_path().

Parameters
[in]parentData parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used, it may no longer be first if path is absolute and starts with a non-existing top-level node inserted before parent. Use lyd_first_sibling() to adjust parent in these cases.
[in]ctxlibyang context, must be set if parent is NULL.
[in]pathPath to create.
[in]valueValue of the new leaf/leaf-list (const char *) in LY_VALUE_JSON format. If creating an anyxml/anydata node, the expected type depends on value_type. For other node types, it should be NULL.
[in]value_lenLength of value in bytes. May be 0 if value is a zero-terminated string. Ignored when creating anyxml/anydata nodes.
[in]value_typeAnyxml/anydata node value type.
[in]optionsBitmask of options, see Data path creation options.
[out]new_parentOptional first parent node created. If only one node was created, equals to new_node.
[out]new_nodeOptional last node created.
Returns
LY_SUCCESS on success.
LY_EEXIST if the final node to create exists (unless LYD_NEW_PATH_UPDATE is used).
LY_EINVAL on invalid arguments including invalid path.
LY_EVALID on invalid value.
LY_ERR on other errors.
LIBYANG_API_DECL LY_ERR lyd_new_term ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const char *  val_str,
ly_bool  output,
struct lyd_node **  node 
)

Create a new term node in the data tree.

To create a top-level term node defined in an extension instance, use lyd_new_ext_term().

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]val_strString value of the node. If it varies based on the format, LY_VALUE_JSON is expected.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_term_bin ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const void *  value,
size_t  value_len,
ly_bool  output,
struct lyd_node **  node 
)

Create a new term node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]valueBinary value of the node. To learn what exactly is expected see LYB Binary Format.
[in]value_lenLength of value.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL LY_ERR lyd_new_term_canon ( struct lyd_node parent,
const struct lys_module module,
const char *  name,
const char *  val_str,
ly_bool  output,
struct lyd_node **  node 
)

Create a new term node in the data tree.

Parameters
[in]parentParent node for the node being created. NULL in case of creating a top level element.
[in]moduleModule of the node being created. If NULL, parent module will be used.
[in]nameSchema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]val_strCanonical string value of the node. If it is not, it may lead to unexpected behavior.
[in]outputFlag in case the parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are taken into consideration. Otherwise, the output's data node is going to be created.
[out]nodeOptional created node.
Returns
LY_ERR value.
LIBYANG_API_DECL struct lys_module* lyd_node_module ( const struct lyd_node node)

Get the module of a node. Useful mainly for opaque nodes.

Parameters
[in]nodeNode to examine.
Returns
Module of the node.
LIBYANG_API_DECL struct lysc_node* lyd_node_schema ( const struct lyd_node node)

Get schema node of a data node. Useful especially for opaque nodes.

Parameters
[in]nodeData node to use.
Returns
Schema node represented by data node, NULL if there is none.
LIBYANG_API_DECL struct lys_module* lyd_owner_module ( const struct lyd_node node)

Get the owner module of the data node. It is the module of the top-level schema node. Generally, in case of augments it is the target module, recursively, otherwise it is the module where the data node is defined.

Also works for opaque nodes, if it is possible to resolve the module.

Parameters
[in]nodeData node to examine.
Returns
Module owner of the node.
LIBYANG_API_DECL struct lyd_node* lyd_parent ( const struct lyd_node node)

Get the generic parent pointer of a data node.

Parameters
[in]nodeNode whose parent pointer to get.
Returns
Pointer to the parent node of the node.
NULL in case of the top-level node or if the node is NULL itself.
LIBYANG_API_DECL LY_ERR lyd_parse_opaq_error ( const struct lyd_node node)

Check node parsed into an opaque node for the reason (error) why it could not be parsed as data node.

The node is expected to be produced by a parser and must either have no parent or a data node parent (not opaque).

Parameters
[in]nodeOpaque node to check.
Returns
LY_EINVAL if node is in some way unexpected (even valid);
LY_ERR value of the reason.
LIBYANG_API_DECL char* lyd_path ( const struct lyd_node node,
LYD_PATH_TYPE  pathtype,
char *  buffer,
size_t  buflen 
)

Generate path of the given node in the requested format.

The path is constructed based on the parent node(s) of this node. When run on a node which is disconnected from its parent(s), this function might yield unexpected results such as /example:b instead of the expected /example:a/b.

Parameters
[in]nodeData path of this node will be generated.
[in]pathtypeFormat of the path to generate.
[in,out]bufferPrepared buffer of the buflen length to store the generated path. If NULL, memory for the complete path is allocated.
[in]buflenSize of the provided buffer.
Returns
NULL in case of memory allocation error, path of the node otherwise. In case the buffer is NULL, the returned string is dynamically allocated and caller is responsible to free it.
LIBYANG_API_DECL struct lyd_node_term* lyd_target ( const struct ly_path *  path,
const struct lyd_node tree 
)

Deprecated, use lyd_find_target() instead.

Parameters
[in]pathCompiled path structure.
[in]treeData tree to be searched.
Returns
Found target node,
NULL if not found.
LIBYANG_API_DEF LY_ERR lyd_trim_xpath ( struct lyd_node **  tree,
const char *  xpath,
const struct lyxp_var *  vars 
)

Evaluate an XPath on data and free all the nodes except the subtrees selected by the expression.

Parameters
[in,out]treeData tree to evaluate on and trim.
[in]xpathXPath to select in JSON format.
[in]varsOptional sized array of XPath variables.
Returns
LY_SUCCESS on success.
LY_ERR value on error.
LIBYANG_API_DECL void lyd_unlink_siblings ( struct lyd_node node)

Unlink the specified node with all the following siblings.

Parameters
[in]nodeData tree node to be unlinked (together with all the children and following siblings).
LIBYANG_API_DECL void lyd_unlink_tree ( struct lyd_node node)

Unlink the specified data subtree.

Parameters
[in]nodeData tree node to be unlinked (together with all the children).
LIBYANG_API_DECL LY_ERR lyd_value_compare ( const struct lyd_node_term node,
const char *  value,
size_t  value_len 
)

Compare the node's value with the given string value. The string value is first validated according to the (current) node's type.

Parameters
[in]nodeData node to compare.
[in]valueString value to be compared. It does not need to be in a canonical form - as part of the process, it is validated and canonized if possible. But it is expected to be in JSON format.
[in]value_lenLength of the given value (mandatory).
Returns
LY_SUCCESS on success,
LY_ENOT if the values do not match,
LY_ERR value if an error occurred.
LIBYANG_API_DECL const char* lyd_value_get_canonical ( const struct ly_ctx ctx,
const struct lyd_value value 
)

Get the (canonical) value of a lyd_value.

Whenever possible, lyd_get_value() or lyd_get_meta_value() should be used instead.

Parameters
[in]ctxContext for the value
[in]valueValue structure to use.
Returns
Canonical value.
LIBYANG_API_DECL LY_ERR lyd_value_validate ( const struct ly_ctx ctx,
const struct lysc_node schema,
const char *  value,
size_t  value_len,
const struct lyd_node ctx_node,
const struct lysc_type **  realtype,
const char **  canonical 
)

Check type restrictions applicable to the particular leaf/leaf-list with the given string value.

The given node is not modified in any way - it is just checked if the value can be set to the node.

Parameters
[in]ctxlibyang context for logging (function does not log errors when ctx is NULL)
[in]schemaSchema node of the value.
[in]valueString value to be checked, it is expected to be in JSON format.
[in]value_lenLength of the given value (mandatory).
[in]ctx_nodeOptional data tree context node for the value (leafref target, instance-identifier). If not set and is required for the validation to complete, LY_EINCOMPLETE is be returned.
[out]realtypeOptional real type of value.
[out]canonicalOptional canonical value of value (in the dictionary).
Returns
LY_SUCCESS on success
LY_EINCOMPLETE in case the ctx_node is not provided and it was needed to finish the validation (e.g. due to require-instance).
LY_ERR value if an error occurred.
LIBYANG_API_DECL void lyxp_vars_free ( struct lyxp_var *  vars)

Free the XPath variables.

Parameters
[in]varsSized array of XPath variables.
LIBYANG_API_DECL LY_ERR lyxp_vars_set ( struct lyxp_var **  vars,
const char *  name,
const char *  value 
)

Set a new XPath variable to vars.

Parameters
[in,out]varsPointer to sized array of XPath variables. To create a new array, set the vars target pointer to NULL. Otherwise variable named name with a value value will be added to the vars or its value will be changed if the variable is already defined.
[in]nameName of the added/edited variable.
[in]valueValue of the variable.
Returns
LY_ERR value.