libyang representation of YANG data trees. More...

#include <arpa/inet.h>
#include <pcre2.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include "log.h"
#include "ly_config.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_leafref_links_rec
	Structure of leafref links record. 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_lyds_tree
	Special lyd_value structure for lyds tree value. 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_LYDS 0x40

#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 0x03F3

#define	LYD_HINT_SCHEMA 0x03FF

#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_ANY_USE_VALUE 0x100

#define	LYD_NEW_META_CLEAR_DFLT 0x10

#define	LYD_NEW_PATH_OPAQ 0x40

#define	LYD_NEW_PATH_UPDATE 0x20

#define	LYD_NEW_PATH_WITH_OPAQ 0x80

#define	LYD_NEW_VAL_BIN 0x04

#define	LYD_NEW_VAL_CANON 0x08

#define	LYD_NEW_VAL_OUTPUT 0x01

#define	LYD_NEW_VAL_STORE_ONLY 0x02

#define	LYD_NODE_ANY (LYS_ANYDATA)

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

#define	LYD_NODE_IS_ALONE(NODE)
	Find out if the node is the only instance, i.e. it has no siblings with the same schema. More...

#define	LYD_NODE_TERM (LYS_LEAF\|LYS_LEAFLIST)

#define	LYD_NODEHINT_CONTAINER 0x0200

#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

#define	PCRE2_CODE_UNIT_WIDTH 8

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_pattern_compile (const struct ly_ctx ctx, const char pattern, pcre2_code **pcode)
	Compile an XML Schema regex pattern prior to matching. More...

LIBYANG_API_DECL LY_ERR	ly_pattern_match (const struct ly_ctx ctx, const char pattern, const char string, uint32_t str_len, pcre2_code *pcode)
	Check a string matches an XML Schema regex used in YANG. More...

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_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. 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_meta *	lyd_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, 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_node *	lyd_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 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 LY_ERR	lyd_leafref_get_links (const struct lyd_node_term node, const struct lyd_leafref_links_rec *record)
	Gets the leafref links record for given node. More...

LIBYANG_API_DECL LY_ERR	lyd_leafref_link_node_tree (const struct lyd_node *tree)
	Traverse through data tree including root node siblings and adds leafrefs links to the given nodes. 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_bool	lyd_meta_is_internal (const struct lyd_meta *meta)
	Check whether metadata are not an instance of internal metadata. More...

LIBYANG_API_DECL LY_ERR	lyd_new_any (struct lyd_node parent, const struct lys_module module, const char name, const void value, LYD_ANYDATA_VALUETYPE value_type, uint32_t options, 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, LYD_ANYDATA_VALUETYPE value_type, uint32_t options, 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, uint32_t options, 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 void value, size_t value_len, uint32_t options, 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, uint32_t options, 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, uint32_t options, 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, uint32_t options, 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, uint32_t options, struct lyd_meta *meta)
	Create a new metadata. More...

LIBYANG_API_DECL LY_ERR	lyd_new_meta2 (const struct ly_ctx ctx, struct lyd_node parent, uint32_t options, 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 value, uint32_t options, 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, uint32_t options, struct lyd_node **node)
	Create a new term node in the data tree based on binary value. 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_node *	lyd_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 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_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 LY_ERR	lyd_unlink_siblings (struct lyd_node *node)
	Unlink the specified node with all the following siblings. More...

LIBYANG_API_DECL LY_ERR	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 - 2024 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 741 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 745 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 884 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 754 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_leafref_links_rec

Structure of leafref links record.

Definition at line 1032 of file tree_data.h.

Data Fields
struct lyd_node_term **	leafref_nodes	pointer to the data node itself
struct lyd_node_term *	node
struct lyd_node_term **	target_nodes	list of the leafref pointing to this data node sized array), By default it is empty. It is filled automatically by validation function of leafref nodes, which are valid and are not using 'require-instance false;'. It can also be populated based on manual request using link api. Freeing of the resources is automatic.

struct lyd_node

Generic structure for a data node.

Definition at line 803 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 896 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 897 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 900 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 823 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 824 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 827 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 998 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 999 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 1002 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 855 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 856 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 859 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 575 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 587 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 657 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 646 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 711 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 672 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 665 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 680 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 695 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 688 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 703 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_lyds_tree

Special lyd_value structure for lyds tree value.

Definition at line 730 of file tree_data.h.

Data Fields
struct rb_node *	rbt	Root of the Red-black tree.

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 630 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 720 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 849 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] node Node to examine.

Returns: Data node name.

Definition at line 929 of file tree_data.h.

#define LYD_NODE_ANY (LYS_ANYDATA)

Schema nodetype mask for lyd_node_any

Definition at line 766 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 764 of file tree_data.h.

#define LYD_NODE_TERM (LYS_LEAF|LYS_LEAFLIST)

Schema nodetype mask for lyd_node_term

Definition at line 765 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]	value	Pointer to the value structure to read from (struct lyd_value *).
[out]	type_val	Pointer to the type-specific value structure.

Definition at line 618 of file tree_data.h.

#define PCRE2_CODE_UNIT_WIDTH 8

Definition at line 30 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_node	Diff node.
[in]	data_node	Matching node in data.
[in]	cb_data	Arbitrary callback data.

Returns: LY_ERR value.

Definition at line 2248 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_node	Target data node.
[in]	src_node	Source data node, is NULL if it was actually duplicated (no target node found) and its copy is `trg_node`.
[in]	cb_data	Arbitrary callback data.

Returns: LY_ERR value.

Definition at line 2158 of file tree_data.h.

Enumeration Type Documentation

enum LY_XPATH_TYPE

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 2596 of file tree_data.h.

enum LYD_PATH_TYPE

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 2369 of file tree_data.h.

Function Documentation

LIBYANG_API_DECL LY_ERR ly_pattern_compile	(	const struct ly_ctx *	ctx,
		const char *	pattern,
		pcre2_code **	pcode
	)

Compile an XML Schema regex pattern prior to matching.

Parameters

[in]	ctx	Optional context for storing errors.
[in]	pattern	Regular expression pattern to use.
[out]	pcode	Compiled `pattern` to be used by ly_pattern_match(). Free it using pcre2_code_free().

Returns: LY_SUCCESS on success;; LY_ERR on error.

LIBYANG_API_DECL LY_ERR ly_pattern_match	(	const struct ly_ctx *	ctx,
		const char *	pattern,
		const char *	string,
		uint32_t	str_len,
		pcre2_code **	pcode
	)

Check a string matches an XML Schema regex used in YANG.

Parameters

[in]	ctx	Optional context for storing errors.
[in]	pattern	Regular expression pattern to use.
[in]	string	String to match.
[in]	str_len	Length of `string`, may be 0 if string is 0-terminated.
[in,out]	pcode	Optional pointer to PCRE2 code. If set and NULL, it is returned. If set and non-NULL, it is used directly for matching instead of compiling `pattern`. Free it using pcre2_code_free().

Returns: LY_SUCCESS on a match;; LY_ENOT if the string does not match;; LY_ERR on error.

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]	value	Valid string date-and-time value.
[out]	time	UNIX timestamp.
[out]	fractions_s	Optional 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]	value	Valid string date-and-time value.
[out]	ts	Timespec.

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]	time	UNIX timestamp.
[in]	fractions_s	Fractions of a second, if any.
[out]	str	String 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]	ts	Timespec.
[out]	str	String 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] time Timestamp 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]	trg	Target node.
[in]	value	Source value, may be NULL when the target value is only freed.
[in]	value_type	Source 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]	any	Anyxml/anydata node to read from.
[out]	value_str	String 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]	meta	Metadata to change.
[in]	val_str	New 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]	term	Term node to change.
[in]	val_str	New 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]	term	Term node to change.
[in]	value	New value to set in binary format (usually a pointer), see LYB Binary Format.
[in]	value_len	Length 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]	term	Term node to change.
[in]	val_str	New 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_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] node Node 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]	meta1	First metadata.
[in]	meta2	Second 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]	node1	The first sibling list to compare.
[in]	node2	The second sibling list to compare.
[in]	options	Various 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]	node1	The first node to compare.
[in]	node2	The second node to compare.
[in]	options	Various 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]	data	Data to apply the diff on.
[in]	diff	Diff 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]	data	Data to apply the diff on.
[in]	diff	Diff to apply.
[in]	mod	Module, whose diff/data only to consider, NULL for all modules.
[in]	diff_cb	Optional diff callback that will be called for every changed node.
[in]	cb_data	Arbitrary 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]	diff	Target diff to merge into.
[in]	src_diff	Source diff.
[in]	options	Bitmask 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]	diff	Target diff to merge into.
[in]	src_diff	Source diff.
[in]	mod	Module, whose diff only to consider, NULL for all modules.
[in]	diff_cb	Optional 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_data	Arbitrary callback data.
[in]	options	Bitmask 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_first	Target diff first sibling to merge into.
[in]	diff_parent	Target diff parent to merge into.
[in]	src_sibling	Source diff sibling to merge.
[in]	diff_cb	Optional 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_data	Arbitrary callback data.
[in]	options	Bitmask 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_diff	Diff to reverse.
[out]	diff	Reversed 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]	first	First data tree.
[in]	second	Second data tree.
[in]	options	Bitmask of options flags, see Data diff options..
[out]	diff	Generated 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]	first	First data tree.
[in]	second	Second data tree.
[in]	options	Bitmask of options flags, see Data diff options..
[out]	diff	Generated 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]	meta	Metadata to copy.
[in]	parent	Node where to append the new metadata.
[out]	dup	Optional 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]	node	Data tree node to be duplicated.
[in]	parent	Optional 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]	options	Bitmask of options flags, see Data duplication options.
[out]	dup	Optional 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]	node	Data tree node to be duplicated.
[in]	trg_ctx	Target context for duplicated nodes.
[in]	parent	Optional 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]	options	Bitmask of options flags, see Data duplication options.
[out]	dup	Optional 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]	node	Data tree node to be duplicated.
[in]	parent	Optional 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]	options	Bitmask of options flags, see Data duplication options.
[out]	dup	Optional 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]	node	Data tree node to be duplicated.
[in]	trg_ctx	Target context for duplicated nodes.
[in]	parent	Optional 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]	options	Bitmask of options flags, see Data duplication options.
[out]	dup	Optional 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_node	XPath context node.
[in]	xpath	XPath to select in JSON format.
[out]	result	Expression 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_node	XPath context node.
[in]	xpath	XPath to select in JSON format.
[in]	vars	Sized array of XPath variables.
[out]	result	Expression 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_node	XPath context node.
[in]	cur_mod	Current module of `xpath`, needed for some kinds of `format`.
[in]	xpath	XPath to select with prefixes in in `format`.
[in]	format	Format of any prefixes in `xpath`.
[in]	prefix_data	Format-specific prefix data.
[in]	vars	Sized array of XPath variables.
[out]	result	Expression 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_node	XPath context node, NULL for the root node.
[in]	tree	Data tree to evaluate on.
[in]	cur_mod	Current module of `xpath`, needed for some kinds of `format`.
[in]	xpath	XPath to select.
[in]	format	Format of any prefixes in `xpath`.
[in]	prefix_data	Format-specific prefix data.
[in]	vars	Optional sized array of XPath variables.
[out]	ret_type	XPath type of the result selecting which of `node_set`, `string`, `number`, and `boolean` to use.
[out]	node_set	XPath node set result.
[out]	string	XPath string result.
[out]	number	XPath number result.
[out]	boolean	XPath 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]	first	First metadata to consider.
[in]	module	Module of the metadata definition, may be NULL if `name` includes a prefix.
[in]	name	Name 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_node	Path context node.
[in]	path	Path to find.
[in]	output	Whether to search in RPC/action output nodes or in input nodes.
[out]	match	Can 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]	siblings	Siblings to search in including preceding and succeeding nodes.
[in]	target	Target node instance to find.
[out]	set	Set 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]	siblings	Siblings to search in including preceding and succeeding nodes.
[in]	target	Target node to find.
[out]	match	Can 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]	first	First sibling to consider.
[in]	name	Opaque node name to find.
[out]	match	Can 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]	siblings	Siblings to search in including preceding and succeeding nodes.
[in]	schema	Schema node of the data node to find.
[in]	key_or_value	If 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_len	Optional length of `key_or_value` in case it is not 0-terminated.
[out]	match	Can 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]	path	Compiled path structure.
[in]	tree	Data tree to be searched.
[out]	match	Can 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_node	XPath context node.
[in]	xpath	XPath to select in JSON format. It must evaluate into a node set.
[out]	set	Set 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_node	XPath context node.
[in]	xpath	XPath to select in JSON format.
[in]	vars	Sized array of XPath variables.
[out]	set	Set 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,
		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_xpath2() with tree added so that ctx_node may be the root and also format and prefix_data added for expressions in different formats than JSON.

Parameters

[in]	ctx_node	XPath context node, NULL for the root node.
[in]	tree	Data tree to evaluate on.
[in]	xpath	XPath to select with prefixes in `format`.
[in]	format	Format of any prefixes in `xpath`.
[in]	prefix_data	Format-specific prefix data.
[in]	vars	Sized array of XPath variables.
[out]	set	Set 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] node Node 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] node Any 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]	ctx	Context where the attributes were created.
[in]	attr	First 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]	ctx	Context where the attributes were created.
[in]	attr	Attribute to free.

LIBYANG_API_DECL void lyd_free_meta_siblings ( struct lyd_meta * meta )

Free the metadata instance with any following instances.

Parameters

[in] meta Metadata to free.

LIBYANG_API_DECL void lyd_free_meta_single ( struct lyd_meta * meta )

Free a single metadata instance.

Parameters

[in] meta Metadata 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] node Any 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] node Root of the (sub)tree to be freed.

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]	sibling	Sibling node to insert after.
[in]	node	Node 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]	sibling	Sibling node to insert before.
[in]	node	Node 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]	parent	Parent node to insert into.
[in]	node	Node 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]	sibling	Siblings to insert into, can even be NULL.
[in]	node	Node to insert.
[out]	first	Optionally 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] node Term node to test.

Returns: false (no, it is not a default node) or true (yes, it is default)

LIBYANG_API_DECL LY_ERR lyd_leafref_get_links	(	const struct lyd_node_term *	node,
		const struct lyd_leafref_links_rec **	record
	)

Gets the leafref links record for given node.

This API requires usage of LY_CTX_LEAFREF_LINKING context flag.

Parameters

[in]	node	The term data node.
[out]	record	The leafref links record

Returns: LY_SUCCESS on success.; LY_ERR value on error.

LIBYANG_API_DECL LY_ERR lyd_leafref_link_node_tree ( const struct lyd_node * tree )

Traverse through data tree including root node siblings and adds leafrefs links to the given nodes.

This API requires usage of LY_CTX_LEAFREF_LINKING context flag.

Parameters

[in] tree The data tree root node.

Returns: LY_SUCCESS on success.; LY_ERR value on error.

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] instance List 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] data LYB 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]	target	Target data tree to merge into, must be a top-level tree. Always points to the first sibling.
[in]	source	Source data tree to merge, must be a top-level tree.
[in]	mod	Module, whose source data only to consider, NULL for all modules.
[in]	merge_cb	Optional 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_data	Arbitrary callback data.
[in]	options	Bitmask 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]	target	Target data tree to merge into, must be a top-level tree. Always points to the first sibling.
[in]	source	Source data tree to merge, must be a top-level tree.
[in]	options	Bitmask 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]	target	Target data tree to merge into, must be a top-level tree. Always points to the first sibling.
[in]	source	Source data tree to merge, must be a top-level tree.
[in]	options	Bitmask of option flags, see Data merge options..

Returns: LY_SUCCESS on success,; LY_ERR value on error.

LIBYANG_API_DECL ly_bool lyd_meta_is_internal ( const struct lyd_meta * meta )

Check whether metadata are not an instance of internal metadata.

Parameters

[in] meta Metadata to check.

Returns: 1 if meta are internal.; 0 if meta are not internal.

LIBYANG_API_DECL LY_ERR lyd_new_any	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name,
		const void *	value,
		LYD_ANYDATA_VALUETYPE	value_type,
		uint32_t	options,
		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]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node can be LYS_ANYDATA or LYS_ANYXML.
[in]	value	Value for the node. Expected type is determined by `value_type`.
[in]	value_type	Type of the provided value in `value`.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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]	parent	Parent opaque node for the attribute.
[in]	module_name	Optional name of the module of the attribute.
[in]	name	Attribute 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]	value	Optional attribute value.
[out]	attr	Optional 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]	parent	Parent opaque node for the attribute being created.
[in]	module_ns	Optional namespace of the module of the attribute.
[in]	name	Attribute name with optional prefix, which is an XML prefix.
[in]	value	Optional attribute value.
[out]	attr	Optional 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,
		LYD_ANYDATA_VALUETYPE	value_type,
		uint32_t	options,
		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]	ext	Extension instance where the any node being created is defined.
[in]	name	Schema node name of the new data node. The node can be LYS_ANYDATA or LYS_ANYXML.
[in]	value	Value for the node. Expected type is determined by `value_type`.
[in]	value_type	Type of the provided value in `value`.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	The 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]	ext	Extension instance where the inner node being created is defined.
[in]	name	Schema node name of the new data node. The node can be LYS_CONTAINER, LYS_NOTIF, LYS_RPC, or LYS_ACTION.
[out]	node	The created node.

Returns: LY_ERR value.

LIBYANG_API_DECL LY_ERR lyd_new_ext_list	(	const struct lysc_ext_instance *	ext,
		const char *	name,
		uint32_t	options,
		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]	ext	Extension instance where the list node being created is defined.
[in]	name	Schema node name of the new data node. The node must be LYS_LIST.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	The 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. In case options include LYD_NEW_VAL_BIN, every key value must be followed by its length.

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]	parent	Data 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]	ext	Extension instance where the node being created is defined.
[in]	path	Path to create.
[in]	value	Value of the new leaf/leaf-list. For other node types, it should be NULL.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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 void *	value,
		size_t	value_len,
		uint32_t	options,
		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]	ext	Extension instance where the term node being created is defined.
[in]	name	Schema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]	value	Value of the node in JSON format unless changed by `options`.
[in]	value_len	Length of `value`.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	The 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]	tree	Tree 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]	ctx	libyang context, must be set only if `tree` is an empty tree.
[in]	implicit_options	Options for implicit node creation, see Implicit node creation options.
[out]	diff	Optional 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]	tree	Tree 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]	module	Module whose implicit nodes to create.
[in]	implicit_options	Options for implicit node creation, see Implicit node creation options.
[out]	diff	Optional 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]	tree	Tree to add implicit nodes into.
[in]	implicit_options	Options for implicit node creation, see Implicit node creation options.
[out]	diff	Optional 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]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node can be LYS_CONTAINER, LYS_NOTIF, LYS_RPC, or LYS_ACTION.
[in]	output	Flag 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]	node	Optional 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,
		uint32_t	options,
		struct lyd_node **	node,
			...
	)

Create a new list node in the data tree.

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node must be LYS_LIST.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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. In case options include LYD_NEW_VAL_BIN, every key value must be followed by its length.

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,
		uint32_t	options,
		struct lyd_node **	node
	)

Create a new list node in the data tree.

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node must be LYS_LIST.
[in]	keys	All 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]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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,
		uint32_t	options,
		struct lyd_node **	node
	)

Create a new list node in the data tree.

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node must be LYS_LIST.
[in]	key_values	Ordered key string values of the new list instance, all must be set.
[in]	value_lengths	Array of lengths of each `key_values`, may be NULL if `key_values` are 0-terminated strings.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional created node.

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,
		uint32_t	options,
		struct lyd_meta **	meta
	)

Create a new metadata.

Parameters

[in]	ctx	libyang context.
[in]	parent	Optional parent node for the metadata being created. Must be set if `meta` is NULL.
[in]	module	Module of the metadata being created. If NULL, `name` must include module name as the prefix.
[in]	name	Annotation 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_str	String 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]	options	Bitmask of options, see New value creation options.
[out]	meta	Optional 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,
		uint32_t	options,
		const struct lyd_attr *	attr,
		struct lyd_meta **	meta
	)

Create new metadata from an opaque node attribute if possible.

Parameters

[in]	ctx	libyang context.
[in]	parent	Optional parent node for the metadata being created. Must be set if `meta` is NULL.
[in]	options	Bitmask of options, see New value creation options.
[in]	attr	Opaque node attribute to parse into metadata.
[out]	meta	Optional 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]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	ctx	libyang context. If NULL, `parent` context will be used.
[in]	name	Node name.
[in]	value	Optional node value.
[in]	prefix	Optional node prefix, must be equal to `module_name` if set.
[in]	module_name	Node module name.
[out]	node	Optional 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]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	ctx	libyang context. If NULL, `parent` context will be used.
[in]	name	Node name.
[in]	value	Optional node value.
[in]	prefix	Optional node prefix.
[in]	module_ns	Node module namespace.
[out]	node	Optional 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]	parent	Data 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]	ctx	libyang context, must be set if `parent` is NULL.
[in]	path	Path to create.
[in]	value	String value of the new leaf/leaf-list in JSON format. For other node types it should be NULL.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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]	parent	Data 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]	ctx	libyang context, must be set if `parent` is NULL.
[in]	path	Path to create.
[in]	value	Value 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_len	Length of `value` in bytes. May be 0 if `value` is a zero-terminated string. Ignored when creating anyxml/anydata nodes.
[in]	value_type	Anyxml/anydata node `value` type.
[in]	options	Bitmask of options, see New value creation options.
[out]	new_parent	Optional first parent node created. If only one node was created, equals to `new_node`.
[out]	new_node	Optional 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 *	value,
		uint32_t	options,
		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(). To create a term node based on binary value, use lyd_new_term_bin().

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]	value	Value of the node in JSON format unless changed by `options`.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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,
		uint32_t	options,
		struct lyd_node **	node
	)

Create a new term node in the data tree based on binary value.

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating a top level element.
[in]	module	Module of the node being created. If NULL, `parent` module will be used.
[in]	name	Schema node name of the new data node. The node can be LYS_LEAF or LYS_LEAFLIST.
[in]	value	Binary value of the node. To learn what exactly is expected see LYB Binary Format.
[in]	value_len	Length of `value`.
[in]	options	Bitmask of options, see New value creation options.
[out]	node	Optional 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] node Node 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] node Data 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] node Data node to examine.

Returns: Module owner of the node.

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] node Opaque 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]	node	Data path of this node will be generated.
[in]	pathtype	Format of the path to generate.
[in,out]	buffer	Prepared buffer of the `buflen` length to store the generated path. If NULL, memory for the complete path is allocated.
[in]	buflen	Size 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_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]	tree	Data tree to evaluate on and trim.
[in]	xpath	XPath to select in JSON format.
[in]	vars	Optional sized array of XPath variables.

Returns: LY_SUCCESS on success.; LY_ERR value on error.

LIBYANG_API_DECL LY_ERR lyd_unlink_siblings ( struct lyd_node * node )

Unlink the specified node with all the following siblings.

Parameters

[in] node Data tree node to be unlinked (together with all the children and following siblings).

Returns: LYS_SUCCESS on success.; LY_ERR error on error.

LIBYANG_API_DECL LY_ERR lyd_unlink_tree ( struct lyd_node * node )

Unlink the specified data subtree.

Parameters

[in] node Data tree node to be unlinked (together with all the children).

Returns: LYS_SUCCESS on success.; LY_ERR error on error.

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]	node	Data node to compare.
[in]	value	String 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_len	Length 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]	ctx	Context for the value
[in]	value	Value 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]	ctx	libyang context for logging (function does not log errors when `ctx` is NULL)
[in]	schema	Schema node of the `value`.
[in]	value	String value to be checked, it is expected to be in JSON format.
[in]	value_len	Length of the given `value` (mandatory).
[in]	ctx_node	Optional 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]	realtype	Optional real type of `value`.
[out]	canonical	Optional 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] vars Sized 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]	vars	Pointer 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]	name	Name of the added/edited variable.
[in]	value	Value of the variable.

Returns: LY_ERR value.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation