blob: 65780d7c5cdf99510b266a912350b728790f7ef7 [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
2 * @file tree_data.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief libyang representation of YANG data trees.
5 *
6 * Copyright (c) 2015 - 2019 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_TREE_DATA_H_
16#define LY_TREE_DATA_H_
17
18#include <stddef.h>
19#include <stdint.h>
20
21#include "log.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020022
Radek Krejcica376bd2020-06-11 16:04:06 +020023#ifdef __cplusplus
24extern "C" {
25#endif
26
Radek Krejcie7b95092019-05-15 11:03:07 +020027struct ly_ctx;
Michal Vasko004d3152020-06-11 19:59:22 +020028struct ly_path;
Radek Krejci535ea9f2020-05-29 16:01:05 +020029struct ly_set;
30struct lyd_node;
31struct lyd_node_opaq;
Radek Krejci47fab892020-11-05 17:02:41 +010032struct lyd_node_term;
Radek Krejci535ea9f2020-05-29 16:01:05 +020033struct lys_module;
34struct lysc_node;
Radek Krejci47fab892020-11-05 17:02:41 +010035struct lysc_type;
Radek Krejcie7b95092019-05-15 11:03:07 +020036
Radek Krejcie7b95092019-05-15 11:03:07 +020037/**
Radek Krejci8678fa42020-08-18 16:07:28 +020038 * @page howtoData Data Instances
39 *
40 * All the nodes in data tree comes are based on ::lyd_node structure. According to the content of the ::lyd_node.schema
41 * it can be cast to several other structures.
42 *
43 * In case the ::lyd_node.schema pointer is NULL, the node is actually __opaq__ and can be safely cast to ::lyd_node_opaq.
44 * The opaq node represent an unknown node which wasn't mapped to any [(compiled) schema](@ref howtoSchema) node in the
45 * context. Such a node can appear in several places in the data tree.
46 * - As a part of the tree structure, but only in the case the ::LYD_PARSE_OPAQ option was used when input data were
47 * [parsed](@ref howtoDataParsers), because unknown data instances are ignored by default. The same way, the opaq nodes can
48 * appear as a node's attributes.
49 * - As a representation of YANG anydata/anyxml content.
50 * - As envelopes of standard data tree instances (RPCs, actions or Notifications).
51 *
52 * In case the data node has its definition in a [compiled schema tree](@ref howtoSchema), the structure of the data node is
53 * actually one of the followings according to the schema node's nodetype (::lysc_node.nodetype).
54 * - ::lyd_node_inner - represents data nodes corresponding to schema nodes matching ::LYD_NODE_INNER nodetypes. They provide
55 * structure of the tree by having children nodes.
56 * - ::lyd_node_term - represents data nodes corresponding to schema nodes matching ::LYD_NODE_TERM nodetypes. The terminal
57 * nodes provide values of the particular configuration/status information. The values are represented as ::lyd_value
58 * structure with string representation of the value (::lyd_value.canonical) and the type specific data stored in the
59 * structure's union according to the real type of the value (::lyd_value.realtype). The string representation provides
60 * canonical representation of the value in case the type has the canonical representation specified. Otherwise, it is the
61 * original value or, in case the value can contain prefixes, the JSON format is used to make the value unambiguous.
62 * - ::lyd_node_any - represents data nodes corresponding to schema nodes matching ::LYD_NODE_ANY nodetypes.
63 *
64 * Despite all the aforementioned structures and their members are available as part of the libyang API and callers can use
65 * it to navigate through the data tree structure or to obtain various information, we recommend to use the following macros
66 * and functions.
67 * - ::lyd_child() (or ::lyd_child_no_keys()) and ::lyd_parent() to get the node's child/parent node.
68 * - ::LYD_CTX to get libyang context from a data node.
69 * - ::LYD_CANON_VALUE to get canonical string value from a terminal node.
70 * - ::LYD_TREE_DFS_BEGIN and ::LYD_TREE_DFS_END to traverse the data tree (depth-first).
71 * - ::LY_LIST_FOR and ::LY_ARRAY_FOR as described on @ref howtoStructures page.
72 *
73 * Instead of going through the data tree on your own, a specific data node can be also located using a wide set of
74 * \b lyd_find_*() functions.
75 *
76 * More information about specific operations with data instances can be found on the following pages:
77 * - @subpage howtoDataParsers
78 * - @subpage howtoDataValidation
79 * - @subpage howtoDataWD
80 * - @subpage howtoDataManipulation
81 * - @subpage howtoDataPrinters
82 *
83 * \note API for this group of functions is described in the [Data Instances module](@ref datatree).
84 *
85 * Functions List (not assigned to above subsections)
86 * --------------------------------------------------
87 * - ::lyd_child()
88 * - ::lyd_child_no_keys()
89 * - ::lyd_parent()
90 * - ::lyd_owner_module()
91 * - ::lyd_find_xpath()
92 * - ::lyd_find_sibling_val()
93 * - ::lyd_find_sibling_first()
94 * - ::lyd_find_meta()
95 *
96 * - ::lyd_path()
97 * - ::lyd_target()
98 *
99 * - ::lyd_lyb_data_length()
100 */
101
102/**
103 * @page howtoDataManipulation Manipulating Data
104 *
105 * There are many functions to create or modify an existing data tree. You can add new nodes, reconnect nodes from
106 * one tree to another (or e.g. from one list instance to another) or remove nodes. The functions doesn't allow you
107 * to put a node to a wrong place (by checking the YANG module structure), but not all validation checks can be made directly
108 * (or you have to make a valid change by multiple tree modifications) when the tree is being changed. Therefore,
109 * the [validation process](@ref howtoDataValidation) is expected to be invoked after changing the data tree to make sure
110 * that the changed data tree is valid.
111 *
112 * When inserting a node into data tree (no matter if the node already exists, via ::lyd_insert_child() and
113 * ::lyd_insert_sibling(), or a new node is being created), the node is automatically inserted to the place respecting the
114 * nodes order from the YANG schema. So the node is not inserted to the end or beginning of the siblings list, but after the
115 * existing instance of the closest preceding sibling node from the schema. In case the node is opaq (it is not connected
116 * with any schema node), it is placed to the end of the sibling node in the order they are inserted in. The only situation
117 * when it is possible to influence the order of the nodes is the order of user-ordered list/leaf-list instances. In such
118 * a case the ::lyd_insert_after() or ::lyd_insert_before() can be used.
119 *
120 * Creating data is generally possible in two ways, they can be combined. You can add nodes one-by-one based on
121 * the node name and/or its parent (::lyd_new_inner(), ::lyd_new_term(), ::lyd_new_any(), ::lyd_new_list(), ::lyd_new_list2()
122 * and ::lyd_new_opaq()) or address the nodes using a [simple XPath addressing](@ref howtoXPath) (::lyd_new_path(),
123 * ::lyd_new_path2() and ::lyd_new_path_any()). The latter enables to create a whole path of nodes, requires less information
124 * about the modified data, and is generally simpler to use. Actually the third way is duplicating the existing data using
125 * ::lyd_dup_single(), ::lyd_dup_siblings() and ::lyd_dup_meta_single().
126 *
127 * The [metadata](@ref howtoPluginsExtensionsMetadata) (and attributes in opaq nodes) can be created with ::lyd_new_meta()
128 * and ::lyd_new_attr().
129 *
130 * Changing value of a terminal node (leaf, leaf-list) is possible with ::lyd_change_term(). Similarly, the metadata value
131 * can be changed with ::lyd_change_meta(). Before changing the value, it might be useful to compare the node's value
132 * with a string value (::lyd_value_compare()) or verify that the new string value is correct for the specific data node
133 * (::lyd_value_validate()).
134 *
135 * Working with two existing subtrees can also be performed two ways. Usually, you would use lyd_insert*() functions.
136 * They are generally meant for simple inserts of a node into a data tree. For more complicated inserts and when
137 * merging 2 trees use ::lyd_merge_tree() or ::lyd_merge_siblings(). It offers additional options and is basically a more
138 * powerful insert.
139 *
140 * Besides merging, libyang is also capable to provide information about differences between two data trees. For this purpose,
141 * ::lyd_diff_tree() and ::lyd_diff_siblings() generates annotated data trees which can be, in addition, used to change one
142 * data tree to another one using ::lyd_diff_apply_all(), ::lyd_diff_apply_module() and ::lyd_diff_reverse_all(). Multiple
143 * diff data trees can be also put together for further work using ::lyd_diff_merge_all(), ::lyd_diff_merge_module() and
144 * ::lyd_diff_merge_tree() functions. To just check equivalence of the data nodes, ::lyd_compare_single(),
145 * ::lyd_compare_siblings() and ::lyd_compare_meta() can be used.
146 *
147 * To remove a node or subtree from a data tree, use ::lyd_unlink_tree() and then free the unwanted data using
148 * ::lyd_free_all() (or other \b lyd_free_*() functions).
149 *
150 * Also remember, that when you are creating/inserting a node, all the objects in that operation must belong to the
151 * same context.
152 *
153 * Modifying the single data tree in multiple threads is not safe.
154 *
155 * Functions List
156 * --------------
157 * - ::lyd_new_inner()
158 * - ::lyd_new_term()
159 * - ::lyd_new_list()
160 * - ::lyd_new_list2()
161 * - ::lyd_new_any()
162 * - ::lyd_new_opaq()
163 * - ::lyd_new_attr()
164 * - ::lyd_new_meta()
165 * - ::lyd_new_path()
166 * - ::lyd_new_path2()
167 * - ::lyd_new_path_any()
168 *
169 * - ::lyd_dup_single()
170 * - ::lyd_dup_siblings()
171 * - ::lyd_dup_meta_single()
172 *
173 * - ::lyd_insert_child()
174 * - ::lyd_insert_sibling()
175 * - ::lyd_insert_after()
176 * - ::lyd_insert_before()
177 *
178 * - ::lyd_value_compare()
179 * - ::lyd_value_validate()
180 *
181 * - ::lyd_change_term()
182 * - ::lyd_change_meta()
183 *
184 * - ::lyd_compare_single()
185 * - ::lyd_compare_siblings()
186 * - ::lyd_compare_meta()
187 * - ::lyd_diff_tree()
188 * - ::lyd_diff_siblings()
189 * - ::lyd_diff_apply_all()
190 * - ::lyd_diff_apply_module()
191 * - ::lyd_diff_reverse_all()
192 * - ::lyd_diff_merge_all()
193 * - ::lyd_diff_merge_module()
194 * - ::lyd_diff_merge_tree()
195 *
196 * - ::lyd_merge_tree()
197 * - ::lyd_merge_siblings()
198 *
199 * - ::lyd_unlink_tree()
200 *
201 * - ::lyd_free_all()
202 * - ::lyd_free_siblings()
203 * - ::lyd_free_tree()
204 * - ::lyd_free_meta_single()
205 * - ::lyd_free_meta_siblings()
206 * - ::lyd_free_attr_single()
207 * - ::lyd_free_attr_siblings()
208 *
209 * - ::lyd_any_copy_value()
210 */
211
212/**
213 * @page howtoDataWD Default Values
214 *
215 * libyang provides support for work with default values as defined in [RFC 6243](https://tools.ietf.org/html/rfc6243).
216 * However, libyang context do not contains the *ietf-netconf-with-defaults* module on its own and caller is supposed to
217 * add this YANG module to enable full support of the *with-defaults* features described below. Without presence of the
218 * mentioned module in the context, the default nodes are still present and handled in the data trees, but the metadata
219 * providing the information about the default values cannot be used. It means that when parsing data, the default nodes
220 * marked with the metadata as implicit default nodes are handled as explicit data and when printing data tree, the expected
221 * nodes are printed without the ietf-netconf-with-defaults metadata.
222 *
223 * The RFC document defines 4 modes for handling default nodes in a data tree, libyang adds the fifth mode and use them
224 * via @ref dataprinterflags when printing data trees.
225 * - \b explicit - Only the explicitly set configuration data. But in the case of status data, missing default
226 * data are added into the tree. In libyang, this mode is represented by ::LYD_PRINT_WD_EXPLICIT option.
227 * This is the default with-defaults mode of the printer. The data nodes do not contain any additional
228 * metadata information.
229 * - \b trim - Data nodes containing the default value are removed. This mode is applied with ::LYD_PRINT_WD_TRIM option.
230 * - \b report-all - This mode provides all the default data nodes despite they were explicitly present in source data or
231 * they were added by libyang's [validation process](@ref howtoDataValidation). This mode is activated by
232 * ::LYD_PRINT_WD_ALL option.
233 * - \b report-all-tagged - In this case, all the data nodes (implicit as well the explicit) containing the default value
234 * are printed and tagged (see the note below). Printers accept ::LYD_PRINT_WD_ALL_TAG option for this mode.
235 * - \b report-implicit-tagged - The last mode is similar to the previous one, except only the implicitly added nodes
236 * are tagged. This is the libyang's extension and it is activated by ::LYD_PRINT_WD_IMPL_TAG option.
237 *
238 * Internally, libyang adds the default nodes into the data tree as part of the [validation process](@ref howtoDataValidation).
239 * When [parsing data](@ref howtoDataParsers) from an input source, adding default nodes can be avoided only by avoiding
240 * the whole [validation process](@ref howtoDataValidation). In case the ietf-netconf-with-defaults module is present in the
241 * context, the [parser process](@ref howtoDataParsers) also supports to recognize the implicit default nodes marked with the
242 * appropriate metadata.
243 *
244 * Note, that in a modified data tree (via e.g. \b lyd_insert_*() or \b lyd_free_*() functions), some of the default nodes
245 * can be missing or they can be present by mistake. Such a data tree is again corrected during the next run of the
246 * [validation process](@ref howtoDataValidation) or manualy using \b lyd_new_implicit_*() functions.
247 *
248 * The implicit (default) nodes, created by libyang, are marked with the ::LYD_DEFAULT flag in ::lyd_node.flags member
249 * Note, that besides leafs and leaf-lists, the flag can appear also in containers, where it means that the container
250 * holds only a default node(s) or it is implicitly added empty container (according to YANG 1.1 spec, all such containers are part of
251 * the accessible data tree). When printing data trees, the presence of empty containers (despite they were added
252 * explicitly or implicitly as part of accessible data tree) depends on ::LYD_PRINT_KEEPEMPTYCONT option.
253 *
254 * To get know if the particular leaf or leaf-list node contains default value (despite implicit or explicit), you can
255 * use ::lyd_is_default() function.
256 *
257 * Functions List
258 * --------------
259 * - ::lyd_is_default()
260 * - ::lyd_new_implicit_all()
261 * - ::lyd_new_implicit_module()
262 * - ::lyd_new_implicit_tree()
263 */
264
265/**
Radek Krejci2ff0d572020-05-21 15:27:28 +0200266 * @ingroup trees
Radek Krejci8678fa42020-08-18 16:07:28 +0200267 * @defgroup datatree Data Tree
Radek Krejcie7b95092019-05-15 11:03:07 +0200268 * @{
269 *
270 * Data structures and functions to manipulate and access instance data tree.
271 */
272
Michal Vasko64246d82020-08-19 12:35:00 +0200273/* *INDENT-OFF* */
274
Michal Vaskoa276cd92020-08-10 15:10:08 +0200275/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200276 * @brief Macro to iterate via all elements in a data tree. This is the opening part
277 * to the #LYD_TREE_DFS_END - they always have to be used together.
278 *
279 * The function follows deep-first search algorithm:
280 * <pre>
281 * 1
282 * / \
Michal Vaskoc193ce92020-03-06 11:04:48 +0100283 * 2 4
Radek Krejcie7b95092019-05-15 11:03:07 +0200284 * / / \
Michal Vaskoc193ce92020-03-06 11:04:48 +0100285 * 3 5 6
Radek Krejcie7b95092019-05-15 11:03:07 +0200286 * </pre>
287 *
Radek Krejci0935f412019-08-20 16:15:18 +0200288 * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While
Michal Vasko56daf732020-08-10 10:57:18 +0200289 * START can be any of the lyd_node* types, ELEM variable must be a pointer to
290 * the generic struct lyd_node.
Radek Krejcie7b95092019-05-15 11:03:07 +0200291 *
Michal Vasko56daf732020-08-10 10:57:18 +0200292 * To skip a particular subtree, instead of the continue statement, set LYD_TREE_DFS_continue
293 * variable to non-zero value.
Radek Krejcie7b95092019-05-15 11:03:07 +0200294 *
295 * Use with opening curly bracket '{' after the macro.
296 *
297 * @param START Pointer to the starting element processed first.
Radek Krejcie7b95092019-05-15 11:03:07 +0200298 * @param ELEM Iterator intended for use in the block.
299 */
Michal Vasko56daf732020-08-10 10:57:18 +0200300#define LYD_TREE_DFS_BEGIN(START, ELEM) \
Radek Krejci857189e2020-09-01 13:26:36 +0200301 { ly_bool LYD_TREE_DFS_continue = 0; struct lyd_node *LYD_TREE_DFS_next; \
Michal Vasko56daf732020-08-10 10:57:18 +0200302 for ((ELEM) = (LYD_TREE_DFS_next) = (struct lyd_node *)(START); \
Radek Krejcie7b95092019-05-15 11:03:07 +0200303 (ELEM); \
Michal Vasko56daf732020-08-10 10:57:18 +0200304 (ELEM) = (LYD_TREE_DFS_next), LYD_TREE_DFS_continue = 0)
Radek Krejcie7b95092019-05-15 11:03:07 +0200305
306/**
307 * @brief Macro to iterate via all elements in a tree. This is the closing part
308 * to the #LYD_TREE_DFS_BEGIN - they always have to be used together.
309 *
310 * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While
Michal Vasko56daf732020-08-10 10:57:18 +0200311 * START can be any of the lyd_node* types, ELEM variable must be a pointer
312 * to the generic struct lyd_node.
Radek Krejcie7b95092019-05-15 11:03:07 +0200313 *
314 * Use with closing curly bracket '}' after the macro.
315 *
316 * @param START Pointer to the starting element processed first.
Radek Krejcie7b95092019-05-15 11:03:07 +0200317 * @param ELEM Iterator intended for use in the block.
318 */
319
Michal Vasko56daf732020-08-10 10:57:18 +0200320#define LYD_TREE_DFS_END(START, ELEM) \
Radek Krejcie7b95092019-05-15 11:03:07 +0200321 /* select element for the next run - children first */ \
Michal Vasko56daf732020-08-10 10:57:18 +0200322 if (LYD_TREE_DFS_continue) { \
323 (LYD_TREE_DFS_next) = NULL; \
324 } else { \
Radek Krejcia1c1e542020-09-29 16:06:52 +0200325 (LYD_TREE_DFS_next) = lyd_child(ELEM); \
Michal Vasko56daf732020-08-10 10:57:18 +0200326 }\
327 if (!(LYD_TREE_DFS_next)) { \
Radek Krejcie7b95092019-05-15 11:03:07 +0200328 /* no children */ \
329 if ((ELEM) == (struct lyd_node*)(START)) { \
330 /* we are done, (START) has no children */ \
331 break; \
332 } \
333 /* try siblings */ \
Michal Vasko56daf732020-08-10 10:57:18 +0200334 (LYD_TREE_DFS_next) = (ELEM)->next; \
Radek Krejcie7b95092019-05-15 11:03:07 +0200335 } \
Michal Vasko56daf732020-08-10 10:57:18 +0200336 while (!(LYD_TREE_DFS_next)) { \
Radek Krejcie7b95092019-05-15 11:03:07 +0200337 /* parent is already processed, go to its sibling */ \
338 (ELEM) = (struct lyd_node*)(ELEM)->parent; \
339 /* no siblings, go back through parents */ \
340 if ((ELEM)->parent == (START)->parent) { \
341 /* we are done, no next element to process */ \
342 break; \
343 } \
Michal Vasko56daf732020-08-10 10:57:18 +0200344 (LYD_TREE_DFS_next) = (ELEM)->next; \
345 } } \
Radek Krejcie7b95092019-05-15 11:03:07 +0200346
Michal Vasko64246d82020-08-19 12:35:00 +0200347/* *INDENT-ON* */
348
Radek Krejcie7b95092019-05-15 11:03:07 +0200349/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200350 * @brief Macro to get context from a data tree node.
351 */
Michal Vaskob7be7a82020-08-20 09:09:04 +0200352#define LYD_CTX(node) ((node)->schema ? (node)->schema->module->ctx : ((struct lyd_node_opaq *)(node))->ctx)
Michal Vasko03ff5a72019-09-11 13:49:33 +0200353
354/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200355 * @brief Data input/output formats supported by libyang [parser](@ref howtoDataParsers) and
356 * [printer](@ref howtoDataPrinters) functions.
Radek Krejcie7b95092019-05-15 11:03:07 +0200357 */
358typedef enum {
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200359 LYD_UNKNOWN = 0, /**< unknown data format, invalid value */
360 LYD_XML, /**< XML instance data format */
361 LYD_JSON, /**< JSON instance data format */
Michal Vasko69730152020-10-09 16:30:07 +0200362 LYD_LYB /**< LYB instance data format */
Radek Krejcie7b95092019-05-15 11:03:07 +0200363} LYD_FORMAT;
364
365/**
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200366 * @brief All kinds of supported prefix mappings to modules.
367 */
368typedef enum {
369 LY_PREF_SCHEMA, /**< value prefixes map to YANG import prefixes */
Michal Vaskoc9795582020-10-08 16:22:17 +0200370 LY_PREF_SCHEMA_RESOLVED, /**< value prefixes map to module structures directly */
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200371 LY_PREF_XML, /**< value prefixes map to XML namespace prefixes */
Michal Vasko69730152020-10-09 16:30:07 +0200372 LY_PREF_JSON /**< value prefixes map to module names */
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200373} LY_PREFIX_FORMAT;
374
375/**
Radek Krejci59583bb2019-09-11 12:57:55 +0200376 * @brief List of possible value types stored in ::lyd_node_any.
Radek Krejcie7b95092019-05-15 11:03:07 +0200377 */
378typedef enum {
Radek Krejci8678fa42020-08-18 16:07:28 +0200379 LYD_ANYDATA_DATATREE, /**< Value is a pointer to ::lyd_node structure (first sibling). When provided as input parameter, the pointer
Radek Krejciee4cab22019-07-17 17:07:47 +0200380 is directly connected into the anydata node without duplication, caller is supposed to not manipulate
Radek Krejci8678fa42020-08-18 16:07:28 +0200381 with the data after a successful call (including calling ::lyd_free_all() on the provided data) */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200382 LYD_ANYDATA_STRING, /**< Value is a generic string without any knowledge about its format (e.g. anyxml value in JSON encoded
Radek Krejciee4cab22019-07-17 17:07:47 +0200383 as string). XML sensitive characters (such as & or \>) are automatically escaped when the anydata
384 is printed in XML format. */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200385 LYD_ANYDATA_XML, /**< Value is a string containing the serialized XML data. */
386 LYD_ANYDATA_JSON, /**< Value is a string containing the data modeled by YANG and encoded as I-JSON. */
Michal Vasko69730152020-10-09 16:30:07 +0200387 LYD_ANYDATA_LYB /**< Value is a memory chunk with the serialized data tree in LYB format. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200388} LYD_ANYDATA_VALUETYPE;
389
390/** @} */
391
392/**
393 * @brief YANG data representation
394 */
395struct lyd_value {
Michal Vaskoba99a3e2020-08-18 15:50:05 +0200396 const char *canonical; /**< Canonical string representation of the value in the dictionary. It is never
397 NULL and in case of no canonical value, its JSON representation is used instead. */
Radek Krejci8678fa42020-08-18 16:07:28 +0200398
Radek Krejcie7b95092019-05-15 11:03:07 +0200399 union {
Radek Krejcie7b95092019-05-15 11:03:07 +0200400 int8_t boolean; /**< 0 as false, 1 as true */
401 int64_t dec64; /**< decimal64: value = dec64 / 10^fraction-digits */
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200402 int8_t int8; /**< 8-bit signed integer */
403 int16_t int16; /**< 16-bit signed integer */
404 int32_t int32; /**< 32-bit signed integer */
405 int64_t int64; /**< 64-bit signed integer */
406 uint8_t uint8; /**< 8-bit unsigned integer */
Michal Vasko7c8439f2020-08-05 13:25:19 +0200407 uint16_t uint16; /**< 16-bit unsigned integer */
408 uint32_t uint32; /**< 32-bit unsigned integer */
409 uint64_t uint64; /**< 64-bit unsigned integer */
Radek Krejcie7b95092019-05-15 11:03:07 +0200410 struct lysc_type_bitenum_item *enum_item; /**< pointer to the definition of the enumeration value */
Radek Krejci849a62a2019-05-22 15:29:05 +0200411 struct lysc_type_bitenum_item **bits_items; /**< list of set pointers to the specification of the set bits ([sized array](@ref sizedarrays)) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200412 struct lysc_ident *ident; /**< pointer to the schema definition of the identityref value */
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200413 struct ly_path *target; /**< Instance-identifier target path. */
414 struct lyd_value_subvalue *subvalue; /** Union value with some metadata. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200415 void *ptr; /**< generic data type structure used to store the data */
Radek Krejci8678fa42020-08-18 16:07:28 +0200416 }; /**< The union is just a list of shorthands to possible values stored by a type's plugin. libyang itself uses the ::lyd_value.realtype
417 plugin's callbacks to work with the data.*/
Radek Krejci084289f2019-07-09 17:35:30 +0200418
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200419 const struct lysc_type *realtype; /**< pointer to the real type of the data stored in the value structure. This type can differ from the type
Radek Krejci8678fa42020-08-18 16:07:28 +0200420 in the schema node of the data node since the type's store plugin can use other types/plugins for
421 storing data. Speaking about built-in types, this is the case of leafref which stores data as its
422 target type. In contrast, union type also uses its subtype's callbacks, but inside an internal data
423 stored in subvalue member of ::lyd_value structure, so here is the pointer to the union type.
424 In general, this type is used to get free callback for this lyd_value structure, so it must reflect
425 the type used to store data directly in the same lyd_value instance. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200426};
427
428/**
Michal Vaskoba99a3e2020-08-18 15:50:05 +0200429 * @brief Macro for getting the string canonical value from a term node.
430 *
431 * @param[in] node Term node with the value.
432 * @return Canonical value.
433 */
Michal Vaskob7be7a82020-08-20 09:09:04 +0200434#define LYD_CANON_VALUE(node) ((struct lyd_node_term *)(node))->value.canonical
Michal Vaskoba99a3e2020-08-18 15:50:05 +0200435
436/**
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200437 * @brief Special lyd_value structure for union.
438 *
439 * Represents data with multiple types (union). Original value is stored in the main lyd_value:canonical_cache while
Radek Krejci8678fa42020-08-18 16:07:28 +0200440 * the ::lyd_value_subvalue.value contains representation according to one of the union's types.
441 * The ::lyd_value_subvalue.prefix_data provides (possible) mappings from prefixes in the original value to YANG modules.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200442 * These prefixes are necessary to parse original value to the union's subtypes.
443 */
444struct lyd_value_subvalue {
445 struct lyd_value value; /**< representation of the value according to the selected union's subtype
Radek Krejci8678fa42020-08-18 16:07:28 +0200446 (stored as ::lyd_value.realtype here, in subvalue structure */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200447 const char *original; /**< Original value in the dictionary. */
448 LY_PREFIX_FORMAT format; /**< Prefix format of the value. However, this information is also used to decide
449 whether a value is valid for the specific format or not on later validations
450 (instance-identifier in XML looks different than in JSON). */
Radek Krejci8678fa42020-08-18 16:07:28 +0200451 void *prefix_data; /**< Format-specific data for prefix resolution (see ::ly_type_store_resolve_prefix()) */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200452 uint32_t hints; /**< [Value hints](@ref lydvalhints) from the parser */
453 const struct lysc_node *ctx_node; /**< Context schema node. */
454};
455
456/**
Michal Vasko9f96a052020-03-10 09:41:45 +0100457 * @brief Metadata structure.
Radek Krejcie7b95092019-05-15 11:03:07 +0200458 *
Michal Vasko9f96a052020-03-10 09:41:45 +0100459 * The structure provides information about metadata of a data element. Such attributes must map to
Radek Krejcie7b95092019-05-15 11:03:07 +0200460 * annotations as specified in RFC 7952. The only exception is the filter type (in NETCONF get operations)
461 * and edit-config's operation attributes. In XML, they are represented as standard XML attributes. In JSON,
462 * they are represented as JSON elements starting with the '@' character (for more information, see the
463 * YANG metadata RFC.
464 *
465 */
Michal Vasko9f96a052020-03-10 09:41:45 +0100466struct lyd_meta {
467 struct lyd_node *parent; /**< data node where the metadata is placed */
468 struct lyd_meta *next; /**< pointer to the next metadata of the same element */
469 struct lysc_ext_instance *annotation; /**< pointer to the annotation's definition */
470 const char *name; /**< metadata name */
471 struct lyd_value value; /**< metadata value representation */
Radek Krejcie7b95092019-05-15 11:03:07 +0200472};
473
Michal Vasko52927e22020-03-16 17:26:14 +0100474/**
475 * @brief Generic prefix and namespace mapping, meaning depends on the format.
Radek Krejci1798aae2020-07-14 13:26:06 +0200476 *
477 * 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
Radek Krejci8678fa42020-08-18 16:07:28 +0200478 * ::ly_ctx_get_module_implemented_ns() or ::ly_ctx_get_module_implemented(). While the module reference is always present,
Michal Vaskoad92b672020-11-12 13:11:31 +0100479 * the prefix member can be omitted in case it is not present in the source data as a reference to the default module/namespace.
Michal Vasko52927e22020-03-16 17:26:14 +0100480 */
Michal Vaskoad92b672020-11-12 13:11:31 +0100481struct ly_opaq_name {
482 const char *name; /**< node name, without prefix if any was defined */
483 const char *prefix; /**< identifier used in the qualified name as the prefix, can be NULL */
Radek Krejci1798aae2020-07-14 13:26:06 +0200484 union {
Michal Vaskoad92b672020-11-12 13:11:31 +0100485 const char *module_ns; /**< format ::LY_PREF_XML - XML namespace of the node element */
486 const char *module_name; /**< format ::LY_PREF_JSON - (inherited) name of the module of the element */
Radek Krejci1798aae2020-07-14 13:26:06 +0200487 };
Michal Vasko52927e22020-03-16 17:26:14 +0100488};
489
490/**
491 * @brief Generic attribute structure.
492 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200493struct lyd_attr {
Michal Vasko52927e22020-03-16 17:26:14 +0100494 struct lyd_node_opaq *parent; /**< data node where the attribute is placed */
Michal Vasko6b5cb2a2020-11-11 19:11:21 +0100495 struct lyd_attr *next; /**< pointer to the next attribute */
Michal Vaskoad92b672020-11-12 13:11:31 +0100496 struct ly_opaq_name name; /**< attribute name with module information */
Michal Vasko501af032020-11-11 20:27:44 +0100497 const char *value; /**< attribute value */
498 LY_PREFIX_FORMAT format; /**< format of the attribute and any prefixes, ::LY_PREF_XML or ::LY_PREF_JSON */
499 void *val_prefix_data; /**< format-specific prefix data (see ::ly_resolve_prefix()) */
500 uint32_t hints; /**< additional information about from the data source, see the [hints list](@ref lydhints) */
Michal Vasko52927e22020-03-16 17:26:14 +0100501
502};
Radek Krejcie7b95092019-05-15 11:03:07 +0200503
Michal Vasko1bf09392020-03-27 12:38:10 +0100504#define LYD_NODE_INNER (LYS_CONTAINER|LYS_LIST|LYS_RPC|LYS_ACTION|LYS_NOTIF) /**< Schema nodetype mask for lyd_node_inner */
Radek Krejcie7b95092019-05-15 11:03:07 +0200505#define LYD_NODE_TERM (LYS_LEAF|LYS_LEAFLIST) /**< Schema nodetype mask for lyd_node_term */
506#define LYD_NODE_ANY (LYS_ANYDATA) /**< Schema nodetype mask for lyd_node_any */
507
508/**
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200509 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200510 * @defgroup dnodeflags Data node flags
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200511 * @{
512 *
513 * Various flags of data nodes.
514 *
515 * 1 - container 5 - anydata/anyxml
516 * 2 - list 6 - rpc/action
517 * 3 - leaf 7 - notification
518 * 4 - leaflist
519 *
520 * bit name 1 2 3 4 5 6 7
521 * ---------------------+-+-+-+-+-+-+-+
522 * 1 LYD_DEFAULT |x| |x|x| | | |
523 * +-+-+-+-+-+-+-+
Michal Vasko5c4e5892019-11-14 12:31:38 +0100524 * 2 LYD_WHEN_TRUE |x|x|x|x|x| | |
Michal Vasko9b368d32020-02-14 13:53:31 +0100525 * +-+-+-+-+-+-+-+
526 * 3 LYD_NEW |x|x|x|x|x|x|x|
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200527 * ---------------------+-+-+-+-+-+-+-+
528 *
529 */
530
Michal Vasko5c4e5892019-11-14 12:31:38 +0100531#define LYD_DEFAULT 0x01 /**< default (implicit) node */
532#define LYD_WHEN_TRUE 0x02 /**< all when conditions of this node were evaluated to true */
Michal Vasko9b368d32020-02-14 13:53:31 +0100533#define LYD_NEW 0x04 /**< node was created after the last validation, is needed for the next validation */
Michal Vasko52927e22020-03-16 17:26:14 +0100534
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200535/** @} */
536
537/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200538 * @brief Generic structure for a data node.
539 */
540struct lyd_node {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200541 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
542 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
543 used to get know that nodes are not equal, it cannot be used to decide that the
544 nodes are equal due to possible collisions. */
545 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Michal Vaskoecd62de2019-11-13 12:35:11 +0100546 const struct lysc_node *schema; /**< pointer to the schema definition of this node, note that the target can be not just
Radek Krejci8678fa42020-08-18 16:07:28 +0200547 ::lysc_node but ::lysc_action or ::lysc_notif as well */
Radek Krejcie7b95092019-05-15 11:03:07 +0200548 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
549 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
550 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
551 never NULL. If there is no sibling node, pointer points to the node
552 itself. In case of the first node, this pointer points to the last
553 node in the list. */
Michal Vasko9f96a052020-03-10 09:41:45 +0100554 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200555
556#ifdef LY_ENABLED_LYD_PRIV
557 void *priv; /**< private user data, not used by libyang */
558#endif
559};
560
561/**
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200562 * @brief Data node structure for the inner data tree nodes - containers, lists, RPCs, actions and Notifications.
Radek Krejcie7b95092019-05-15 11:03:07 +0200563 */
564struct lyd_node_inner {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200565 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
566 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
567 used to get know that nodes are not equal, it cannot be used to decide that the
568 nodes are equal due to possible collisions. */
569 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200570 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
571 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
572 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
573 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
574 never NULL. If there is no sibling node, pointer points to the node
575 itself. In case of the first node, this pointer points to the last
576 node in the list. */
Michal Vasko9f96a052020-03-10 09:41:45 +0100577 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200578
579#ifdef LY_ENABLED_LYD_PRIV
580 void *priv; /**< private user data, not used by libyang */
581#endif
582
583 struct lyd_node *child; /**< pointer to the first child node. */
584 struct hash_table *children_ht; /**< hash table with all the direct children (except keys for a list, lists without keys) */
Radek Krejci8678fa42020-08-18 16:07:28 +0200585#define LYD_HT_MIN_ITEMS 4 /**< minimal number of children to create ::lyd_node_inner.children_ht hash table. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200586};
587
588/**
Michal Vaskof03ed032020-03-04 13:31:44 +0100589 * @brief Data node structure for the terminal data tree nodes - leaves and leaf-lists.
Radek Krejcie7b95092019-05-15 11:03:07 +0200590 */
591struct lyd_node_term {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200592 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
593 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
594 used to get know that nodes are not equal, it cannot be used to decide that the
595 nodes are equal due to possible collisions. */
596 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200597 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
598 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
599 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
600 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
601 never NULL. If there is no sibling node, pointer points to the node
602 itself. In case of the first node, this pointer points to the last
603 node in the list. */
Michal Vasko9f96a052020-03-10 09:41:45 +0100604 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200605
606#ifdef LY_ENABLED_LYD_PRIV
607 void *priv; /**< private user data, not used by libyang */
608#endif
609
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200610 struct lyd_value value; /**< node's value representation */
Radek Krejcie7b95092019-05-15 11:03:07 +0200611};
612
613/**
614 * @brief Data node structure for the anydata data tree nodes - anydatas and anyxmls.
615 */
616struct lyd_node_any {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200617 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
618 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
619 used to get know that nodes are not equal, it cannot be used to decide that the
620 nodes are equal due to possible collisions. */
621 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200622 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
623 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
624 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
625 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
626 never NULL. If there is no sibling node, pointer points to the node
627 itself. In case of the first node, this pointer points to the last
628 node in the list. */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200629 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200630
631#ifdef LY_ENABLED_LYD_PRIV
632 void *priv; /**< private user data, not used by libyang */
633#endif
634
Michal Vasko00cbf532020-06-15 13:58:47 +0200635 union lyd_any_value {
Radek Krejciee4cab22019-07-17 17:07:47 +0200636 struct lyd_node *tree; /**< data tree */
637 const char *str; /**< Generic string data */
638 const char *xml; /**< Serialized XML data */
639 const char *json; /**< I-JSON encoded string */
640 char *mem; /**< LYD_ANYDATA_LYB memory chunk */
641 } value; /**< pointer to the stored value representation of the anydata/anyxml node */
Radek Krejci8678fa42020-08-18 16:07:28 +0200642 LYD_ANYDATA_VALUETYPE value_type;/**< type of the data stored as ::lyd_node_any.value */
Radek Krejcie7b95092019-05-15 11:03:07 +0200643};
644
645/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200646 * @ingroup datatree
647 * @defgroup lydvalhints Value format hints.
Radek Krejci1798aae2020-07-14 13:26:06 +0200648 * @{
Radek Krejci8678fa42020-08-18 16:07:28 +0200649 *
650 * Hints for the type of the data value.
651 *
652 * Any information about value types encoded in the format is hinted by these values.
Radek Krejci1798aae2020-07-14 13:26:06 +0200653 */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200654#define LYD_VALHINT_STRING 0x0001 /**< value is allowed to be a string */
655#define LYD_VALHINT_DECNUM 0x0002 /**< value is allowed to be a decimal number */
656#define LYD_VALHINT_OCTNUM 0x0004 /**< value is allowed to be an octal number */
657#define LYD_VALHINT_HEXNUM 0x0008 /**< value is allowed to be a hexadecimal number */
658#define LYD_VALHINT_NUM64 0x0010 /**< value is allowed to be an int64 or uint64 */
659#define LYD_VALHINT_BOOLEAN 0x0020 /**< value is allowed to be a boolean */
660#define LYD_VALHINT_EMPTY 0x0040 /**< value is allowed to be empty */
661/**
662 * @} lydvalhints
663 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200664
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200665/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200666 * @ingroup datatree
667 * @defgroup lydnodehints Node type format hints
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200668 * @{
Radek Krejci8678fa42020-08-18 16:07:28 +0200669 *
670 * Hints for the type of the data node.
671 *
672 * Any information about node types encoded in the format is hinted by these values.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200673 */
674#define LYD_NODEHINT_LIST 0x0080 /**< node is allowed to be a list instance */
675#define LYD_NODEHINT_LEAFLIST 0x0100 /**< node is allowed to be a leaf-list instance */
676#define LYD_NODEHINT_ENVELOPE 0x8000 /**< only found in opaque node hints; node is a special protocol-dependent
677 RPC/Action/Notification envelope */
678/**
679 * @} lydnodehints
680 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200681
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200682/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200683 * @ingroup datatree
684 * @defgroup lydhints Value and node type format hints
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200685 * @{
Radek Krejci8678fa42020-08-18 16:07:28 +0200686 *
687 * Hints for the types of data node and its value.
688 *
689 * Any information about value and node types encoded in the format is hinted by these values.
690 * It combines [value hints](@ref lydvalhints) and [node hints](@ref lydnodehints).
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200691 */
692#define LYD_HINT_DATA 0x01F3 /**< special node/value hint to be used for generic data node/value (for cases when
693 there is no encoding or it does not provide any additional information about
694 a node/value type); do not combine with specific [value hints](@ref lydvalhints)
695 or [node hints](@ref lydnodehints). */
696#define LYD_HINT_SCHEMA 0x01FF /**< special node/value hint to be used for generic schema node/value(for cases when
697 there is no encoding or it does not provide any additional information about
698 a node/value type); do not combine with specific [value hints](@ref lydvalhints)
699 or [node hints](@ref lydnodehints). */
700/**
701 * @} lydhints
702 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200703
704/**
Michal Vasko52927e22020-03-16 17:26:14 +0100705 * @brief Data node structure for unparsed (opaque) nodes.
706 */
707struct lyd_node_opaq {
708 uint32_t hash; /**< always 0 */
709 uint32_t flags; /**< always 0 */
710 const struct lysc_node *schema; /**< always NULL */
711 struct lyd_node *parent; /**< pointer to the parent node (NULL in case of root node) */
712 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
713 struct lyd_node *prev; /**< pointer to the previous sibling node (last sibling if there is none) */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200714 struct lyd_attr *attr; /**< pointer to the list of generic attributes of this node */
Michal Vasko52927e22020-03-16 17:26:14 +0100715
716#ifdef LY_ENABLED_LYD_PRIV
717 void *priv; /**< private user data, not used by libyang */
718#endif
719
Michal Vasko501af032020-11-11 20:27:44 +0100720 struct lyd_node *child; /**< pointer to the child node (compatible with ::lyd_node_inner) */
721
Michal Vaskoad92b672020-11-12 13:11:31 +0100722 struct ly_opaq_name name; /**< node name with module information */
Michal Vasko52927e22020-03-16 17:26:14 +0100723 const char *value; /**< original value */
Michal Vasko501af032020-11-11 20:27:44 +0100724 LY_PREFIX_FORMAT format; /**< format of the node and any prefixes, ::LY_PREF_XML or ::LY_PREF_JSON */
725 void *val_prefix_data; /**< format-specific prefix data (see ::ly_resolve_prefix()) */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200726 uint32_t hints; /**< additional information about from the data source, see the [hints list](@ref lydhints) */
Michal Vasko501af032020-11-11 20:27:44 +0100727
Michal Vasko52927e22020-03-16 17:26:14 +0100728 const struct ly_ctx *ctx; /**< libyang context */
729};
730
731/**
Radek Krejcia1c1e542020-09-29 16:06:52 +0200732 * @brief Get the generic parent pointer of a data node.
733 *
734 * @param[in] node Node whose parent pointer to get.
735 * @return Pointer to the parent node of the @p node.
736 * @return NULL in case of the top-level node or if the @p node is NULL itself.
Michal Vasko5bfd4be2020-06-23 13:26:19 +0200737 */
Radek Krejcia1c1e542020-09-29 16:06:52 +0200738struct lyd_node *lyd_parent(const struct lyd_node *node);
Michal Vasko5bfd4be2020-06-23 13:26:19 +0200739
740/**
Radek Krejcia1c1e542020-09-29 16:06:52 +0200741 * @brief Get the child pointer of a generic data node.
Radek Krejcie7b95092019-05-15 11:03:07 +0200742 *
Radek Krejcia1c1e542020-09-29 16:06:52 +0200743 * Decides the node's type and in case it has a children list, returns it. Supports even the opaq nodes (::lyd_node_opaq).
744 *
745 * If you need to skip key children, use ::lyd_child_no_keys().
746 *
747 * @param[in] node Node to use.
748 * @return Pointer to the first child node (if any) of the @p node.
Radek Krejcie7b95092019-05-15 11:03:07 +0200749 */
Radek Krejcia1c1e542020-09-29 16:06:52 +0200750struct lyd_node *lyd_child(const struct lyd_node *node);
751
752/**
753 * @brief Get the child pointer of a generic data node but skip its keys in case it is ::LYS_LIST.
754 *
755 * Decides the node's type and in case it has a children list, returns it. Supports even the opaq nodes (::lyd_node_opaq).
756 *
757 * If you need to take key children into account, use ::lyd_child().
758 *
759 * @param[in] node Node to use.
760 * @return Pointer to the first child node (if any) of the @p node.
761 */
762struct lyd_node *lyd_child_no_keys(const struct lyd_node *node);
Radek Krejcie7b95092019-05-15 11:03:07 +0200763
764/**
Michal Vaskoc193ce92020-03-06 11:04:48 +0100765 * @brief Get the owner module of the data node. It is the module of the top-level schema node. Generally,
766 * in case of augments it is the target module, recursively, otherwise it is the module where the data node is defined.
767 *
Michal Vaskofcdf3012020-11-23 16:57:03 +0100768 * Also works for opaque nodes, if it is possible to resolve the module.
769 *
Michal Vaskoc193ce92020-03-06 11:04:48 +0100770 * @param[in] node Data node to examine.
771 * @return Module owner of the node.
772 */
773const struct lys_module *lyd_owner_module(const struct lyd_node *node);
774
775/**
Radek Krejci19611252020-10-04 13:54:53 +0200776 * @brief Check whether a node value equals to its default one.
777 *
778 * @param[in] node Term node to test.
779 * @return false (no, it is not a default node) or true (yes, it is default)
780 */
781ly_bool lyd_is_default(const struct lyd_node *node);
782
783/**
Radek Krejcica989142020-11-05 11:32:22 +0100784 * @brief Learn the relative position of a list or leaf-list instance within other instances of the same schema node.
785 *
786 * @param[in] instance List or leaf-list instance to get the position of.
787 * return 0 on error.
788 * return Positive integer of the @p instance position.
789 */
790uint32_t lyd_list_pos(const struct lyd_node *instance);
791
792/**
Radek Krejci4233f9b2020-11-05 12:38:35 +0100793 * @brief Get the first sibling of the given node.
794 *
795 * @param[in] node Node which first sibling is going to be the result.
796 * @return The first sibling of the given node or the node itself if it is the first child of the parent.
797 */
Michal Vasko6ae16d62020-11-06 17:23:23 +0100798struct lyd_node *lyd_first_sibling(const struct lyd_node *node);
Radek Krejci4233f9b2020-11-05 12:38:35 +0100799
800/**
Michal Vasko60ea6352020-06-29 13:39:39 +0200801 * @brief Learn the length of LYB data.
802 *
803 * @param[in] data LYB data to examine.
804 * @return Length of the LYB data chunk,
805 * @return -1 on error.
806 */
807int lyd_lyb_data_length(const char *data);
808
809/**
Michal Vaskoc0004272020-08-06 08:32:34 +0200810 * @brief Copy anydata value from one node to another. Target value is freed first.
811 *
812 * @param[in,out] trg Target node.
813 * @param[in] value Source value, may be NULL when the target value is only freed.
814 * @param[in] value_type Source value type.
815 * @return LY_ERR value.
816 */
817LY_ERR lyd_any_copy_value(struct lyd_node *trg, const union lyd_any_value *value, LYD_ANYDATA_VALUETYPE value_type);
818
819/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200820 * @brief Create a new inner node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +0100821 *
822 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vaskof03ed032020-03-04 13:31:44 +0100823 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +0100824 * @param[in] name Schema node name of the new data node. The node can be #LYS_CONTAINER, #LYS_NOTIF, #LYS_RPC, or #LYS_ACTION.
Radek Krejci41ac9942020-11-02 14:47:56 +0100825 * @param[in] output Flag in case the @p parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are
826 * taken into consideration. Otherwise, the output's data node is going to be created.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200827 * @param[out] node Optional created node.
828 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +0100829 */
Radek Krejci41ac9942020-11-02 14:47:56 +0100830LY_ERR lyd_new_inner(struct lyd_node *parent, const struct lys_module *module, const char *name, ly_bool output, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +0100831
832/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200833 * @brief Create a new list node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +0100834 *
835 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vaskof03ed032020-03-04 13:31:44 +0100836 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +0100837 * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
Radek Krejci41ac9942020-11-02 14:47:56 +0100838 * @param[in] output Flag in case the @p parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are
839 * taken into consideration. Otherwise, the output's data node is going to be created.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200840 * @param[out] node Optional created node.
Michal Vasko013a8182020-03-03 10:46:53 +0100841 * @param[in] ... Ordered key values of the new list instance, all must be set. In case of an instance-identifier
Michal Vasko004d3152020-06-11 19:59:22 +0200842 * or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for
843 * key-less lists.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200844 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +0100845 */
Radek Krejci41ac9942020-11-02 14:47:56 +0100846LY_ERR lyd_new_list(struct lyd_node *parent, const struct lys_module *module, const char *name, ly_bool output, struct lyd_node **node, ...);
Michal Vasko013a8182020-03-03 10:46:53 +0100847
848/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200849 * @brief Create a new list node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +0100850 *
851 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vaskof03ed032020-03-04 13:31:44 +0100852 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +0100853 * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
854 * @param[in] keys All key values predicate in the form of "[key1='val1'][key2='val2']...", they do not have to be ordered.
855 * In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes).
Michal Vasko004d3152020-06-11 19:59:22 +0200856 * Use NULL or string of length 0 in case of key-less list.
Radek Krejci41ac9942020-11-02 14:47:56 +0100857 * @param[in] output Flag in case the @p parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are
858 * taken into consideration. Otherwise, the output's data node is going to be created.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200859 * @param[out] node Optional created node.
860 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +0100861 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200862LY_ERR lyd_new_list2(struct lyd_node *parent, const struct lys_module *module, const char *name, const char *keys,
Radek Krejci41ac9942020-11-02 14:47:56 +0100863 ly_bool output, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +0100864
865/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200866 * @brief Create a new term node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +0100867 *
868 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vaskof03ed032020-03-04 13:31:44 +0100869 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +0100870 * @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
871 * @param[in] val_str String form of the value of the node being created. In case of an instance-identifier or identityref
872 * value, the JSON format is expected (module names instead of prefixes).
Radek Krejci41ac9942020-11-02 14:47:56 +0100873 * @param[in] output Flag in case the @p parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are
874 * taken into consideration. Otherwise, the output's data node is going to be created.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200875 * @param[out] node Optional created node.
876 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +0100877 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200878LY_ERR lyd_new_term(struct lyd_node *parent, const struct lys_module *module, const char *name, const char *val_str,
Radek Krejci41ac9942020-11-02 14:47:56 +0100879 ly_bool output, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +0100880
881/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200882 * @brief Create a new any node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +0100883 *
884 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vaskof03ed032020-03-04 13:31:44 +0100885 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +0100886 * @param[in] name Schema node name of the new data node. The node can be #LYS_ANYDATA or #LYS_ANYXML.
887 * @param[in] value Value to be directly assigned to the node. Expected type is determined by @p value_type.
888 * @param[in] value_type Type of the provided value in @p value.
Radek Krejci41ac9942020-11-02 14:47:56 +0100889 * @param[in] output Flag in case the @p parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are
890 * taken into consideration. Otherwise, the output's data node is going to be created.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200891 * @param[out] node Optional created node.
892 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +0100893 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200894LY_ERR lyd_new_any(struct lyd_node *parent, const struct lys_module *module, const char *name, const void *value,
Radek Krejci41ac9942020-11-02 14:47:56 +0100895 LYD_ANYDATA_VALUETYPE value_type, ly_bool output, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +0100896
897/**
Michal Vasko871a0252020-11-11 18:35:24 +0100898 * @brief Create new metadata.
Michal Vaskod86997b2020-05-26 15:19:54 +0200899 *
Michal Vasko871a0252020-11-11 18:35:24 +0100900 * @param[in] ctx libyang context,
901 * @param[in] parent Optional parent node for the metadata being created. Must be set if @p meta is NULL.
Michal Vasko00cbf532020-06-15 13:58:47 +0200902 * @param[in] module Module of the metadata being created. If NULL, @p name must include module name as the prefix.
Michal Vaskod86997b2020-05-26 15:19:54 +0200903 * @param[in] name Annotation name of the new metadata. It can include the annotation module as the prefix.
904 * If the prefix is specified it is always used but if not specified, @p module must be set.
Michal Vasko00cbf532020-06-15 13:58:47 +0200905 * @param[in] val_str String form of the value of the metadata. In case of an instance-identifier or identityref
Michal Vaskod86997b2020-05-26 15:19:54 +0200906 * value, the JSON format is expected (module names instead of prefixes).
Michal Vasko871a0252020-11-11 18:35:24 +0100907 * @param[in] clear_dflt Whether to clear the default flag starting from @p parent, recursively all NP containers.
908 * @param[out] meta Optional created metadata. Must be set if @p parent is NULL.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200909 * @return LY_ERR value.
Michal Vaskod86997b2020-05-26 15:19:54 +0200910 */
Michal Vasko871a0252020-11-11 18:35:24 +0100911LY_ERR lyd_new_meta(const struct ly_ctx *ctx, struct lyd_node *parent, const struct lys_module *module, const char *name,
912 const char *val_str, ly_bool clear_dflt, struct lyd_meta **meta);
Michal Vaskod86997b2020-05-26 15:19:54 +0200913
914/**
Michal Vaskoba696702020-11-11 19:12:45 +0100915 * @brief Create new metadata from an opaque node attribute if possible.
916 *
917 * @param[in] ctx libyang context.
918 * @param[in] parent Optional parent node for the metadata being created. Must be set if @p meta is NULL.
919 * @param[in] clear_dflt Whether to clear the default flag starting from @p parent, recursively all NP containers.
920 * @param[in] attr Opaque node attribute to parse into metadata.
921 * @param[out] meta Optional created metadata. Must be set if @p parent is NULL.
922 * @return LY_SUCCESS on success.
923 * @return LY_ENOT if the attribute could not be parsed into any metadata.
924 * @return LY_ERR on error.
925 */
926LY_ERR lyd_new_meta2(const struct ly_ctx *ctx, struct lyd_node *parent, ly_bool clear_dflt, const struct lyd_attr *attr,
927 struct lyd_meta **meta);
928
929/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200930 * @brief Create a new opaque node in the data tree.
931 *
932 * @param[in] parent Parent node for the node beaing created. NULL in case of creating a top level element.
933 * @param[in] ctx libyang context. If NULL, @p parent context will be used.
934 * @param[in] name Node name.
935 * @param[in] value Node value, may be NULL.
936 * @param[in] module_name Node module name.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200937 * @param[out] node Optional created node.
938 * @return LY_ERR value.
Michal Vasko00cbf532020-06-15 13:58:47 +0200939 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200940LY_ERR lyd_new_opaq(struct lyd_node *parent, const struct ly_ctx *ctx, const char *name, const char *value,
Radek Krejci0f969882020-08-21 16:56:47 +0200941 const char *module_name, struct lyd_node **node);
Michal Vasko00cbf532020-06-15 13:58:47 +0200942
943/**
944 * @brief Create new attribute for an opaque data node.
945 *
946 * @param[in] parent Parent opaque node for the attribute being created.
Radek Krejci8678fa42020-08-18 16:07:28 +0200947 * @param[in] module_name Name of the module of the attribute being created. There may be none.
Michal Vasko00cbf532020-06-15 13:58:47 +0200948 * @param[in] name Attribute name. It can include the module name as the prefix.
949 * @param[in] val_str String value of the attribute. Is stored directly.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200950 * @param[out] attr Optional created attribute.
951 * @return LY_ERR value.
Michal Vasko00cbf532020-06-15 13:58:47 +0200952 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200953LY_ERR lyd_new_attr(struct lyd_node *parent, const char *module_name, const char *name, const char *val_str,
Radek Krejci0f969882020-08-21 16:56:47 +0200954 struct lyd_attr **attr);
Michal Vasko00cbf532020-06-15 13:58:47 +0200955
956/**
Michal Vasko00cbf532020-06-15 13:58:47 +0200957 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200958 * @defgroup pathoptions Data path creation options
Michal Vasko00cbf532020-06-15 13:58:47 +0200959 *
960 * Various options to change lyd_new_path*() behavior.
961 *
962 * Default behavior:
963 * - if the target node already exists (and is not default), an error is returned.
964 * - the whole path to the target node is created (with any missing parents) if necessary.
965 * - RPC output schema children are completely ignored in all modules. Input is searched and nodes created normally.
966 * @{
967 */
968
Radek Krejci092e33c2020-10-12 15:33:10 +0200969#define LYD_NEW_PATH_UPDATE 0x01 /**< If the target node exists, is a leaf, and it is updated with a new value or its
970 default flag is changed, it is returned. If the target node exists and is not
971 a leaf or generally no change occurs in the @p parent tree, NULL is returned and
972 no error set. */
973#define LYD_NEW_PATH_OUTPUT 0x02 /**< Changes the behavior to ignoring RPC/action input schema nodes and using only
974 output ones. */
975#define LYD_NEW_PATH_OPAQ 0x04 /**< Enables the creation of opaque nodes with some specific rules. If the __last node__
976 in the path is not uniquely defined ((leaf-)list without a predicate) or has an
977 invalid value (leaf/leaf-list), it is created as opaque. */
Michal Vasko00cbf532020-06-15 13:58:47 +0200978
979/** @} pathoptions */
980
981/**
982 * @brief Create a new node in the data tree based on a path. Cannot be used for anyxml/anydata nodes,
983 * for those use ::lyd_new_path_any.
984 *
985 * If @p path points to a list key and the list instance does not exist, the key value from the predicate is used
986 * and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path
987 * and @p value is set, the predicate is preferred.
988 *
Michal Vasko104fe962020-11-06 17:23:44 +0100989 * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
990 * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
991 * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
Michal Vasko00cbf532020-06-15 13:58:47 +0200992 * @param[in] ctx libyang context, must be set if @p parent is NULL.
Michal Vasko104fe962020-11-06 17:23:44 +0100993 * @param[in] path [Path](@ref howtoXPath) to create.
Michal Vasko00cbf532020-06-15 13:58:47 +0200994 * @param[in] value Value of the new leaf/leaf-list. For other node types, it is ignored.
995 * @param[in] options Bitmask of options, see @ref pathoptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200996 * @param[out] node Optional first created node.
997 * @return LY_ERR value.
Michal Vasko00cbf532020-06-15 13:58:47 +0200998 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200999LY_ERR lyd_new_path(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const char *value,
Radek Krejci1deb5be2020-08-26 16:43:36 +02001000 uint32_t options, struct lyd_node **node);
Michal Vasko00cbf532020-06-15 13:58:47 +02001001
1002/**
1003 * @brief Create a new node in the data tree based on a path. All node types can be created.
1004 *
1005 * If @p path points to a list key and the list instance does not exist, the key value from the predicate is used
1006 * and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path
1007 * and @p value is set, the predicate is preferred.
1008 *
Michal Vasko104fe962020-11-06 17:23:44 +01001009 * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
1010 * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
1011 * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
Michal Vasko00cbf532020-06-15 13:58:47 +02001012 * @param[in] ctx libyang context, must be set if @p parent is NULL.
Michal Vasko104fe962020-11-06 17:23:44 +01001013 * @param[in] path [Path](@ref howtoXPath) to create.
Michal Vasko00cbf532020-06-15 13:58:47 +02001014 * @param[in] value Value of the new leaf/leaf-list/anyxml/anydata. For other node types, it is ignored.
1015 * @param[in] value_type Anyxml/anydata node @p value type.
1016 * @param[in] options Bitmask of options, see @ref pathoptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001017 * @param[out] node Optional first created node.
1018 * @return LY_ERR value.
Michal Vasko00cbf532020-06-15 13:58:47 +02001019 */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001020LY_ERR lyd_new_path_any(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const void *value,
Radek Krejci1deb5be2020-08-26 16:43:36 +02001021 LYD_ANYDATA_VALUETYPE value_type, uint32_t options, struct lyd_node **node);
Michal Vasko00cbf532020-06-15 13:58:47 +02001022
1023/**
1024 * @brief Create a new node in the data tree based on a path. All node types can be created.
1025 *
1026 * If @p path points to a list key and the list instance does not exist, the key value from the predicate is used
1027 * and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path
1028 * and @p value is set, the predicate is preferred.
1029 *
Michal Vasko104fe962020-11-06 17:23:44 +01001030 * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
1031 * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
1032 * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
Michal Vasko00cbf532020-06-15 13:58:47 +02001033 * @param[in] ctx libyang context, must be set if @p parent is NULL.
Michal Vasko104fe962020-11-06 17:23:44 +01001034 * @param[in] path [Path](@ref howtoXPath) to create.
Michal Vasko00cbf532020-06-15 13:58:47 +02001035 * @param[in] value Value of the new leaf/leaf-list/anyxml/anydata. For other node types, it is ignored.
1036 * @param[in] value_type Anyxml/anydata node @p value type.
1037 * @param[in] options Bitmask of options, see @ref pathoptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001038 * @param[out] new_parent Optional first parent node created. If only one node was created, equals to @p new_node.
1039 * @param[out] new_node Optional last node created.
Michal Vasko00cbf532020-06-15 13:58:47 +02001040 * @return LY_ERR value.
1041 */
1042LY_ERR lyd_new_path2(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const void *value,
Radek Krejci1deb5be2020-08-26 16:43:36 +02001043 LYD_ANYDATA_VALUETYPE value_type, uint32_t options, struct lyd_node **new_parent, struct lyd_node **new_node);
Michal Vasko00cbf532020-06-15 13:58:47 +02001044
1045/**
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001046 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001047 * @defgroup implicitoptions Implicit node creation options
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001048 *
1049 * Various options to change lyd_new_implicit*() behavior.
1050 *
1051 * Default behavior:
1052 * - both configuration and state missing implicit nodes are added.
1053 * - all implicit node types are added (non-presence containers, default leaves, and default leaf-lists).
1054 * @{
1055 */
1056
Michal Vasko44b19a12020-08-07 09:21:30 +02001057#define LYD_IMPLICIT_NO_STATE 0x01 /**< Do not add any implicit state nodes. */
1058#define LYD_IMPLICIT_NO_CONFIG 0x02 /**< Do not add any implicit config nodes. */
1059#define LYD_IMPLICIT_NO_DEFAULTS 0x04 /**< Do not add any default nodes (leaves/leaf-lists), only non-presence
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001060 containers. */
1061
1062/** @} implicitoptions */
1063
1064/**
1065 * @brief Add any missing implicit nodes into a data subtree.
1066 *
1067 * @param[in] tree Tree to add implicit nodes into.
1068 * @param[in] implicit_options Options for implicit node creation, see @ref implicitoptions.
1069 * @param[out] diff Optional diff with any created nodes.
1070 * @return LY_ERR value.
1071 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001072LY_ERR lyd_new_implicit_tree(struct lyd_node *tree, uint32_t implicit_options, struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001073
1074/**
1075 * @brief Add any missing implicit nodes.
1076 *
1077 * @param[in,out] tree Tree to add implicit nodes into.
1078 * @param[in] ctx libyang context, must be set only if @p tree is an empty tree.
1079 * @param[in] implicit_options Options for implicit node creation, see @ref implicitoptions.
1080 * @param[out] diff Optional diff with any created nodes.
1081 * @return LY_ERR value.
1082 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001083LY_ERR lyd_new_implicit_all(struct lyd_node **tree, const struct ly_ctx *ctx, uint32_t implicit_options, struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001084
1085/**
1086 * @brief Add any missing implicit nodes of one module.
1087 *
1088 * @param[in,out] tree Tree to add implicit nodes into.
1089 * @param[in] module Module whose implicit nodes to create.
1090 * @param[in] implicit_options Options for implicit node creation, see @ref implicitoptions.
1091 * @param[out] diff Optional diff with any created nodes.
1092 * @return LY_ERR value.
1093 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001094LY_ERR lyd_new_implicit_module(struct lyd_node **tree, const struct lys_module *module, uint32_t implicit_options,
Radek Krejci0f969882020-08-21 16:56:47 +02001095 struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001096
1097/**
Michal Vasko00cbf532020-06-15 13:58:47 +02001098 * @brief Change the value of a term (leaf or leaf-list) node.
1099 *
1100 * Node changed this way is always considered explicitly set, meaning its default flag
1101 * is always cleared.
1102 *
1103 * @param[in] term Term node to change.
1104 * @param[in] val_str New value to set, any prefixes are expected in JSON format.
1105 * @return LY_SUCCESS if value was changed,
1106 * @return LY_EEXIST if value was the same and only the default flag was cleared,
1107 * @return LY_ENOT if the values were equal and no change occured,
1108 * @return LY_ERR value on other errors.
1109 */
1110LY_ERR lyd_change_term(struct lyd_node *term, const char *val_str);
1111
1112/**
Michal Vasko41586352020-07-13 13:54:25 +02001113 * @brief Change the value of a metadata instance.
1114 *
Michal Vasko41586352020-07-13 13:54:25 +02001115 * @param[in] meta Metadata to change.
1116 * @param[in] val_str New value to set, any prefixes are expected in JSON format.
1117 * @return LY_SUCCESS if value was changed,
1118 * @return LY_ENOT if the values were equal and no change occured,
1119 * @return LY_ERR value on other errors.
1120 */
1121LY_ERR lyd_change_meta(struct lyd_meta *meta, const char *val_str);
1122
1123/**
Michal Vaskob104f112020-07-17 09:54:54 +02001124 * @brief Insert a child into a parent.
Michal Vaskof03ed032020-03-04 13:31:44 +01001125 *
1126 * - if the node is part of some other tree, it is automatically unlinked.
1127 * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
1128 *
1129 * @param[in] parent Parent node to insert into.
1130 * @param[in] node Node to insert.
1131 * @return LY_SUCCESS on success.
1132 * @return LY_ERR error on error.
1133 */
Michal Vaskob104f112020-07-17 09:54:54 +02001134LY_ERR lyd_insert_child(struct lyd_node *parent, struct lyd_node *node);
Michal Vaskof03ed032020-03-04 13:31:44 +01001135
1136/**
Michal Vaskob104f112020-07-17 09:54:54 +02001137 * @brief Insert a node into siblings.
Michal Vaskob1b5c262020-03-05 14:29:47 +01001138 *
1139 * - if the node is part of some other tree, it is automatically unlinked.
1140 * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
1141 *
Michal Vaskob104f112020-07-17 09:54:54 +02001142 * @param[in] sibling Siblings to insert into, can even be NULL.
Michal Vaskob1b5c262020-03-05 14:29:47 +01001143 * @param[in] node Node to insert.
Michal Vaskob104f112020-07-17 09:54:54 +02001144 * @param[out] first Optionally return the first sibling after insertion. Can be the address of @p sibling.
Michal Vaskob1b5c262020-03-05 14:29:47 +01001145 * @return LY_SUCCESS on success.
1146 * @return LY_ERR error on error.
1147 */
Michal Vaskob104f112020-07-17 09:54:54 +02001148LY_ERR lyd_insert_sibling(struct lyd_node *sibling, struct lyd_node *node, struct lyd_node **first);
Michal Vaskob1b5c262020-03-05 14:29:47 +01001149
1150/**
Michal Vaskob104f112020-07-17 09:54:54 +02001151 * @brief Insert a node before another node, can be used only for user-ordered nodes.
Michal Vaskof03ed032020-03-04 13:31:44 +01001152 *
1153 * - if the node is part of some other tree, it is automatically unlinked.
1154 * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
1155 *
1156 * @param[in] sibling Sibling node to insert before.
1157 * @param[in] node Node to insert.
1158 * @return LY_SUCCESS on success.
1159 * @return LY_ERR error on error.
1160 */
1161LY_ERR lyd_insert_before(struct lyd_node *sibling, struct lyd_node *node);
1162
1163/**
Michal Vaskob104f112020-07-17 09:54:54 +02001164 * @brief Insert a node after another node, can be used only for user-ordered nodes.
Michal Vaskof03ed032020-03-04 13:31:44 +01001165 *
1166 * - if the node is part of some other tree, it is automatically unlinked.
1167 * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
1168 *
1169 * @param[in] sibling Sibling node to insert after.
1170 * @param[in] node Node to insert.
1171 * @return LY_SUCCESS on success.
1172 * @return LY_ERR error on error.
1173 */
1174LY_ERR lyd_insert_after(struct lyd_node *sibling, struct lyd_node *node);
1175
1176/**
1177 * @brief Unlink the specified data subtree.
1178 *
1179 * @param[in] node Data tree node to be unlinked (together with all the children).
1180 */
1181void lyd_unlink_tree(struct lyd_node *node);
1182
1183/**
Radek Krejcib0849a22019-07-25 12:31:04 +02001184 * @brief Free all the nodes (even parents of the node) in the data tree.
Radek Krejcie7b95092019-05-15 11:03:07 +02001185 *
1186 * @param[in] node Any of the nodes inside the tree.
1187 */
1188void lyd_free_all(struct lyd_node *node);
1189
1190/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001191 * @brief Free all the sibling nodes (preceding as well as succeeding).
Radek Krejcib0849a22019-07-25 12:31:04 +02001192 *
1193 * @param[in] node Any of the sibling nodes to free.
1194 */
Michal Vaskof03ed032020-03-04 13:31:44 +01001195void lyd_free_siblings(struct lyd_node *node);
Radek Krejcib0849a22019-07-25 12:31:04 +02001196
1197/**
Radek Krejcie7b95092019-05-15 11:03:07 +02001198 * @brief Free (and unlink) the specified data (sub)tree.
1199 *
Radek Krejcie7b95092019-05-15 11:03:07 +02001200 * @param[in] node Root of the (sub)tree to be freed.
1201 */
1202void lyd_free_tree(struct lyd_node *node);
1203
1204/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001205 * @brief Free a single metadata instance.
Radek Krejcie7b95092019-05-15 11:03:07 +02001206 *
Michal Vasko3a41dff2020-07-15 14:30:28 +02001207 * @param[in] meta Metadata to free.
Radek Krejcie7b95092019-05-15 11:03:07 +02001208 */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001209void lyd_free_meta_single(struct lyd_meta *meta);
Michal Vasko52927e22020-03-16 17:26:14 +01001210
1211/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001212 * @brief Free the metadata instance with any following instances.
1213 *
1214 * @param[in] meta Metadata to free.
1215 */
1216void lyd_free_meta_siblings(struct lyd_meta *meta);
1217
1218/**
1219 * @brief Free a single attribute.
Michal Vasko52927e22020-03-16 17:26:14 +01001220 *
1221 * @param[in] ctx Context where the attributes were created.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001222 * @param[in] attr Attribute to free.
Michal Vasko52927e22020-03-16 17:26:14 +01001223 */
Radek Krejci011e4aa2020-09-04 15:22:31 +02001224void lyd_free_attr_single(const struct ly_ctx *ctx, struct lyd_attr *attr);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001225
1226/**
1227 * @brief Free the attribute with any following attributes.
1228 *
1229 * @param[in] ctx Context where the attributes were created.
1230 * @param[in] attr First attribute to free.
1231 */
Radek Krejci011e4aa2020-09-04 15:22:31 +02001232void lyd_free_attr_siblings(const struct ly_ctx *ctx, struct lyd_attr *attr);
Radek Krejcie7b95092019-05-15 11:03:07 +02001233
Radek Krejci084289f2019-07-09 17:35:30 +02001234/**
1235 * @brief Check type restrictions applicable to the particular leaf/leaf-list with the given string @p value.
1236 *
1237 * The given node is not modified in any way - it is just checked if the @p value can be set to the node.
1238 *
1239 * If there is no data node instance and you are fine with checking just the type's restrictions without the
Radek Krejci8678fa42020-08-18 16:07:28 +02001240 * data tree context (e.g. for the case of require-instance restriction), use ::lys_value_validate().
Radek Krejci084289f2019-07-09 17:35:30 +02001241 *
1242 * @param[in] ctx libyang context for logging (function does not log errors when @p ctx is NULL)
1243 * @param[in] node Data node for the @p value.
Michal Vaskof937cfe2020-08-03 16:07:12 +02001244 * @param[in] value String value to be checked, it is expected to be in JSON format.
Radek Krejci084289f2019-07-09 17:35:30 +02001245 * @param[in] value_len Length of the given @p value (mandatory).
Michal Vaskof03ed032020-03-04 13:31:44 +01001246 * @param[in] tree Data tree (e.g. when validating RPC/Notification) where the required data instance (leafref target,
1247 * instance-identifier) can be placed. NULL in case the data tree is not yet complete,
1248 * then LY_EINCOMPLETE can be returned.
Michal Vasko3701af52020-08-03 14:29:38 +02001249 * @param[out] realtype Optional real type of the value.
Radek Krejci084289f2019-07-09 17:35:30 +02001250 * @return LY_SUCCESS on success
1251 * @return LY_EINCOMPLETE in case the @p trees is not provided and it was needed to finish the validation (e.g. due to require-instance).
1252 * @return LY_ERR value if an error occurred.
1253 */
Michal Vasko44685da2020-03-17 15:38:06 +01001254LY_ERR lyd_value_validate(const struct ly_ctx *ctx, const struct lyd_node_term *node, const char *value, size_t value_len,
Michal Vaskofeca4fb2020-10-05 08:58:40 +02001255 const struct lyd_node *tree, const struct lysc_type **realtype);
Radek Krejci084289f2019-07-09 17:35:30 +02001256
1257/**
Michal Vaskofeca4fb2020-10-05 08:58:40 +02001258 * @brief Compare the node's value with the given string value. The string value is first validated according to
1259 * the (current) node's type.
Radek Krejci084289f2019-07-09 17:35:30 +02001260 *
1261 * @param[in] node Data node to compare.
1262 * @param[in] value String value to be compared. It does not need to be in a canonical form - as part of the process,
Michal Vaskof937cfe2020-08-03 16:07:12 +02001263 * it is validated and canonized if possible. But it is expected to be in JSON format.
Radek Krejci084289f2019-07-09 17:35:30 +02001264 * @param[in] value_len Length of the given @p value (mandatory).
Michal Vaskofeca4fb2020-10-05 08:58:40 +02001265 * @return LY_SUCCESS on success,
1266 * @return LY_ENOT if the values do not match,
Radek Krejci084289f2019-07-09 17:35:30 +02001267 * @return LY_ERR value if an error occurred.
1268 */
Michal Vaskofeca4fb2020-10-05 08:58:40 +02001269LY_ERR lyd_value_compare(const struct lyd_node_term *node, const char *value, size_t value_len);
Radek Krejci084289f2019-07-09 17:35:30 +02001270
Radek Krejci576b23f2019-07-12 14:06:32 +02001271/**
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001272 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001273 * @defgroup datacompareoptions Data compare options
1274 * @{
1275 * Various options to change the ::lyd_compare_single() and ::lyd_compare_siblings() behavior.
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001276 */
1277#define LYD_COMPARE_FULL_RECURSION 0x01 /* lists and containers are the same only in case all they children
1278 (subtree, so direct as well as indirect children) are the same. By default,
1279 containers are the same in case of the same schema node and lists are the same
1280 in case of equal keys (keyless lists do the full recursion comparison all the time). */
1281#define LYD_COMPARE_DEFAULTS 0x02 /* By default, implicit and explicit default nodes are considered to be equal. This flag
1282 changes this behavior and implicit (automatically created default node) and explicit
1283 (explicitly created node with the default value) default nodes are considered different. */
Michal Vasko60ea6352020-06-29 13:39:39 +02001284/** @} datacompareoptions */
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001285
1286/**
1287 * @brief Compare 2 data nodes if they are equivalent.
1288 *
1289 * @param[in] node1 The first node to compare.
1290 * @param[in] node2 The second node to compare.
Radek Krejcic5ad9652019-09-11 11:31:51 +02001291 * @param[in] options Various @ref datacompareoptions.
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001292 * @return LY_SUCCESS if the nodes are equivalent.
1293 * @return LY_ENOT if the nodes are not equivalent.
1294 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001295LY_ERR lyd_compare_single(const struct lyd_node *node1, const struct lyd_node *node2, uint32_t options);
Michal Vasko8f359bf2020-07-28 10:41:15 +02001296
1297/**
1298 * @brief Compare 2 lists of siblings if they are equivalent.
1299 *
1300 * @param[in] node1 The first sibling list to compare.
1301 * @param[in] node2 The second sibling list to compare.
1302 * @param[in] options Various @ref datacompareoptions.
1303 * @return LY_SUCCESS if all the siblings are equivalent.
1304 * @return LY_ENOT if the siblings are not equivalent.
1305 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001306LY_ERR lyd_compare_siblings(const struct lyd_node *node1, const struct lyd_node *node2, uint32_t options);
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001307
1308/**
Michal Vasko21725742020-06-29 11:49:25 +02001309 * @brief Compare 2 metadata.
1310 *
1311 * @param[in] meta1 First metadata.
1312 * @param[in] meta2 Second metadata.
1313 * @return LY_SUCCESS if the metadata are equivalent.
1314 * @return LY_ENOT if not.
1315 */
1316LY_ERR lyd_compare_meta(const struct lyd_meta *meta1, const struct lyd_meta *meta2);
1317
1318/**
Radek Krejci22ebdba2019-07-25 13:59:43 +02001319 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001320 * @defgroup dupoptions Data duplication options
Radek Krejci22ebdba2019-07-25 13:59:43 +02001321 *
Radek Krejci8678fa42020-08-18 16:07:28 +02001322 * Various options to change ::lyd_dup_single(), ::lyd_dup_siblings() and ::lyd_dup_meta_single() behavior.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001323 *
1324 * Default behavior:
1325 * - only the specified node is duplicated without siblings, parents, or children.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001326 * - all the metadata of the duplicated nodes are also duplicated.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001327 * @{
1328 */
1329
1330#define LYD_DUP_RECURSIVE 0x01 /**< Duplicate not just the node but also all the children. Note that
1331 list's keys are always duplicated. */
Michal Vaskoa29a5762020-06-23 13:28:49 +02001332#define LYD_DUP_NO_META 0x02 /**< Do not duplicate metadata of any node. */
Radek Krejci22ebdba2019-07-25 13:59:43 +02001333#define LYD_DUP_WITH_PARENTS 0x04 /**< If a nested node is being duplicated, duplicate also all the parents.
1334 Keys are also duplicated for lists. Return value does not change! */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001335#define LYD_DUP_WITH_FLAGS 0x08 /**< Also copy any data node flags. That will cause the duplicated data to preserve
Michal Vaskof6df0a02020-06-16 13:08:34 +02001336 its validation/default node state. */
Radek Krejci22ebdba2019-07-25 13:59:43 +02001337
1338/** @} dupoptions */
1339
1340/**
1341 * @brief Create a copy of the specified data tree \p node. Schema references are kept the same.
1342 *
Radek Krejci22ebdba2019-07-25 13:59:43 +02001343 * @param[in] node Data tree node to be duplicated.
1344 * @param[in] parent Optional parent node where to connect the duplicated node(s).
Michal Vasko3a41dff2020-07-15 14:30:28 +02001345 * If set in combination with LYD_DUP_WITH_PARENTS, the parents chain is duplicated until it comes to and connects with
1346 * the @p parent.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001347 * @param[in] options Bitmask of options flags, see @ref dupoptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001348 * @param[out] dup Optional created copy of the node. Note that in case the parents chain is duplicated for the duplicated
1349 * node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
1350 * @return LY_ERR value.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001351 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001352LY_ERR lyd_dup_single(const struct lyd_node *node, struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001353
1354/**
1355 * @brief Create a copy of the specified data tree \p node with any following siblings. Schema references are kept the same.
1356 *
1357 * @param[in] node Data tree node to be duplicated.
1358 * @param[in] parent Optional parent node where to connect the duplicated node(s).
1359 * If set in combination with LYD_DUP_WITH_PARENTS, the parents chain is duplicated until it comes to and connects with
1360 * the @p parent.
1361 * @param[in] options Bitmask of options flags, see @ref dupoptions.
1362 * @param[out] dup Optional created copy of the node. Note that in case the parents chain is duplicated for the duplicated
1363 * node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
1364 * @return LY_ERR value.
1365 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001366LY_ERR lyd_dup_siblings(const struct lyd_node *node, struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup);
Radek Krejci22ebdba2019-07-25 13:59:43 +02001367
1368/**
Michal Vasko25a32822020-07-09 15:48:22 +02001369 * @brief Create a copy of the metadata.
1370 *
1371 * @param[in] meta Metadata to copy.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001372 * @param[in] parent Node where to append the new metadata.
1373 * @param[out] dup Optional created metadata copy.
1374 * @return LY_ERR value.
Michal Vasko25a32822020-07-09 15:48:22 +02001375 */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001376LY_ERR lyd_dup_meta_single(const struct lyd_meta *meta, struct lyd_node *parent, struct lyd_meta **dup);
Michal Vasko25a32822020-07-09 15:48:22 +02001377
1378/**
Michal Vasko4490d312020-06-16 13:08:55 +02001379 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001380 * @defgroup mergeoptions Data merge options.
Radek Krejci576b23f2019-07-12 14:06:32 +02001381 *
Radek Krejci8678fa42020-08-18 16:07:28 +02001382 * Various options to change ::lyd_merge_tree() and ::lyd_merge_siblings() behavior.
Michal Vasko4490d312020-06-16 13:08:55 +02001383 *
1384 * Default behavior:
1385 * - source data tree is not modified in any way,
Michal Vasko3a41dff2020-07-15 14:30:28 +02001386 * - any default nodes in the source are ignored if there are explicit nodes in the target.
Michal Vasko4490d312020-06-16 13:08:55 +02001387 * @{
1388 */
1389
1390#define LYD_MERGE_DESTRUCT 0x01 /**< Spend source data tree in the function, it cannot be used afterwards! */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001391#define LYD_MERGE_DEFAULTS 0x02 /**< Default nodes in the source tree replace even explicit nodes in the target. */
Michal Vasko4490d312020-06-16 13:08:55 +02001392
1393/** @} mergeoptions */
1394
1395/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001396 * @brief Merge the source data subtree into the target data tree. Merge may not be complete until validation
Michal Vasko4490d312020-06-16 13:08:55 +02001397 * is called on the resulting data tree (data from more cases may be present, default and non-default values).
1398 *
Michal Vasko2f510942020-11-13 10:26:25 +01001399 * Example input:
1400 *
1401 * source (A1) - A2 - A3 target (B1) - B2 - B3
1402 * /\ /\ /\ /\ /\ /\
1403 * .... .... .... .... .... ....
1404 *
1405 * result target (A1) - B1 - B2 - B3
1406 * /\ /\ /\ /\
1407 * .... .... .... ....
1408 *
Michal Vasko4490d312020-06-16 13:08:55 +02001409 * @param[in,out] target Target data tree to merge into, must be a top-level tree.
1410 * @param[in] source Source data tree to merge, must be a top-level tree.
1411 * @param[in] options Bitmask of option flags, see @ref mergeoptions.
1412 * @return LY_SUCCESS on success,
1413 * @return LY_ERR value on error.
1414 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001415LY_ERR lyd_merge_tree(struct lyd_node **target, const struct lyd_node *source, uint16_t options);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001416
1417/**
1418 * @brief Merge the source data tree with any following siblings into the target data tree. Merge may not be
1419 * complete until validation called on the resulting data tree (data from more cases may be present, default
1420 * and non-default values).
1421 *
Michal Vasko2f510942020-11-13 10:26:25 +01001422 * Example input:
1423 *
1424 * source (A1) - A2 - A3 target (B1) - B2 - B3
1425 * /\ /\ /\ /\ /\ /\
1426 * .... .... .... .... .... ....
1427 *
1428 * result target (A1) - A2 - A3 - B1 - B2 - B3
1429 * /\ /\ /\ /\ /\ /\
1430 * .... .... .... .... .... ....
1431 *
Michal Vasko3a41dff2020-07-15 14:30:28 +02001432 * @param[in,out] target Target data tree to merge into, must be a top-level tree.
1433 * @param[in] source Source data tree to merge, must be a top-level tree.
1434 * @param[in] options Bitmask of option flags, see @ref mergeoptions.
1435 * @return LY_SUCCESS on success,
1436 * @return LY_ERR value on error.
1437 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001438LY_ERR lyd_merge_siblings(struct lyd_node **target, const struct lyd_node *source, uint16_t options);
Michal Vasko4490d312020-06-16 13:08:55 +02001439
1440/**
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001441 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001442 * @defgroup diffoptions Data diff options.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001443 *
Radek Krejci8678fa42020-08-18 16:07:28 +02001444 * Various options to change ::lyd_diff_tree() and ::lyd_diff_siblings() behavior.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001445 *
1446 * Default behavior:
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001447 * - any default nodes are treated as non-existent and ignored.
1448 * @{
1449 */
1450
Michal Vasko3a41dff2020-07-15 14:30:28 +02001451#define LYD_DIFF_DEFAULTS 0x01 /**< Default nodes in the trees are not ignored but treated similarly to explicit
1452 nodes. Also, leaves and leaf-lists are added into diff even in case only their
1453 default flag (state) was changed. */
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001454
1455/** @} diffoptions */
1456
1457/**
1458 * @brief Learn the differences between 2 data trees.
1459 *
1460 * The resulting diff is represented as a data tree with specific metadata from the internal 'yang'
1461 * module. Most importantly, every node has an effective 'operation' metadata. If there is none
1462 * defined on the node, it inherits the operation from the nearest parent. Top-level nodes must
1463 * always have the 'operation' metadata defined. Additional metadata ('orig-default', 'value',
1464 * 'orig-value', 'key', 'orig-key') are used for storing more information about the value in the first
1465 * or the second tree.
1466 *
1467 * The diff tree is completely independent on the @p first and @p second trees, meaning all
1468 * the information about the change is stored in the diff and the trees are not needed.
1469 *
1470 * !! Caution !!
1471 * The diff tree should never be validated because it may easily not be valid! For example,
1472 * when data from one case branch are deleted and data from another branch created - data from both
1473 * branches are then stored in the diff tree simultaneously.
1474 *
1475 * @param[in] first First data tree.
1476 * @param[in] second Second data tree.
1477 * @param[in] options Bitmask of options flags, see @ref diffoptions.
1478 * @param[out] diff Generated diff.
1479 * @return LY_SUCCESS on success,
1480 * @return LY_ERR on error.
1481 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001482LY_ERR lyd_diff_tree(const struct lyd_node *first, const struct lyd_node *second, uint16_t options, struct lyd_node **diff);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001483
1484/**
1485 * @brief Learn the differences between 2 data trees including all the following siblings.
1486 *
1487 * @param[in] first First data tree.
1488 * @param[in] second Second data tree.
1489 * @param[in] options Bitmask of options flags, see @ref diffoptions.
1490 * @param[out] diff Generated diff.
1491 * @return LY_SUCCESS on success,
1492 * @return LY_ERR on error.
1493 */
Radek Krejci1deb5be2020-08-26 16:43:36 +02001494LY_ERR lyd_diff_siblings(const struct lyd_node *first, const struct lyd_node *second, uint16_t options, struct lyd_node **diff);
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001495
1496/**
1497 * @brief Callback for diff nodes.
1498 *
1499 * @param[in] diff_node Diff node.
1500 * @param[in] data_node Matching node in data.
1501 * @param[in] cb_data Arbitrary callback data.
1502 * @return LY_ERR value.
1503 */
1504typedef LY_ERR (*lyd_diff_cb)(const struct lyd_node *diff_node, struct lyd_node *data_node, void *cb_data);
1505
1506/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001507 * @brief Apply the whole diff on a data tree but restrict the operation to one module.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001508 *
1509 * @param[in,out] data Data to apply the diff on.
1510 * @param[in] diff Diff to apply.
1511 * @param[in] mod Module, whose diff/data only to consider, NULL for all modules.
1512 * @param[in] diff_cb Optional diff callback that will be called for every changed node.
1513 * @param[in] cb_data Arbitrary callback data.
1514 * @return LY_SUCCESS on success,
1515 * @return LY_ERR on error.
1516 */
1517LY_ERR lyd_diff_apply_module(struct lyd_node **data, const struct lyd_node *diff, const struct lys_module *mod,
Radek Krejci0f969882020-08-21 16:56:47 +02001518 lyd_diff_cb diff_cb, void *cb_data);
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001519
1520/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001521 * @brief Apply the whole diff tree on a data tree.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001522 *
1523 * @param[in,out] data Data to apply the diff on.
1524 * @param[in] diff Diff to apply.
1525 * @return LY_SUCCESS on success,
1526 * @return LY_ERR on error.
1527 */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001528LY_ERR lyd_diff_apply_all(struct lyd_node **data, const struct lyd_node *diff);
Michal Vaskoe893ddd2020-06-23 13:35:20 +02001529
1530/**
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001531 * @ingroup datatree
1532 * @defgroup diffmergeoptions Data diff merge options.
1533 *
1534 * Various options to change ::lyd_diff_merge_module(), ::lyd_diff_merge_tree(), and ::lyd_diff_merge_all() behavior.
1535 *
1536 * Default behavior:
1537 * - any default nodes are expected to be a result of validation corrections and not explicitly modified.
1538 * @{
1539 */
1540
1541#define LYD_DIFF_MERGE_DEFAULTS 0x01 /**< Default nodes in the diffs are treated as possibly explicitly modified. */
1542
1543/** @} diffoptions */
1544
1545/**
Michal Vaskoe6323f62020-07-09 15:49:02 +02001546 * @brief Merge 2 diffs into each other but restrict the operation to one module.
1547 *
1548 * The diffs must be possible to be merged, which is guaranteed only if the source diff was
1549 * created on data that had the target diff applied on them. In other words, this sequence is legal
1550 *
Michal Vasko04f85912020-08-07 12:14:58 +02001551 * 1) diff1 from data1 and data2 -> data11 from apply diff1 on data1 -> diff2 from data11 and data3 ->
1552 * -> data 33 from apply diff2 on data1
Michal Vaskoe6323f62020-07-09 15:49:02 +02001553 *
1554 * and reusing these diffs
1555 *
Michal Vasko04f85912020-08-07 12:14:58 +02001556 * 2) diff11 from merge diff1 and diff2 -> data33 from apply diff11 on data1
Michal Vaskoe6323f62020-07-09 15:49:02 +02001557 *
Michal Vaskofb737aa2020-08-06 13:53:53 +02001558 * @param[in,out] diff Target diff to merge into.
Michal Vaskoe6323f62020-07-09 15:49:02 +02001559 * @param[in] src_diff Source diff.
1560 * @param[in] mod Module, whose diff only to consider, NULL for all modules.
1561 * @param[in] diff_cb Optional diff callback that will be called for every changed node.
1562 * @param[in] cb_data Arbitrary callback data.
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001563 * @param[in] options Bitmask of options flags, see @ref diffmergeoptions.
Michal Vaskoe6323f62020-07-09 15:49:02 +02001564 * @return LY_SUCCESS on success,
1565 * @return LY_ERR on error.
1566 */
Michal Vaskofb737aa2020-08-06 13:53:53 +02001567LY_ERR lyd_diff_merge_module(struct lyd_node **diff, const struct lyd_node *src_diff, const struct lys_module *mod,
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001568 lyd_diff_cb diff_cb, void *cb_data, uint16_t options);
Michal Vaskoe6323f62020-07-09 15:49:02 +02001569
1570/**
Michal Vasko04f85912020-08-07 12:14:58 +02001571 * @brief Merge 2 diff trees into each other.
1572 *
1573 * @param[in,out] diff_first Target diff first sibling to merge into.
1574 * @param[in] diff_parent Target diff parent to merge into.
1575 * @param[in] src_sibling Source diff sibling to merge.
1576 * @param[in] diff_cb Optional diff callback that will be called for every changed node.
1577 * @param[in] cb_data Arbitrary callback data.
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001578 * @param[in] options Bitmask of options flags, see @ref diffmergeoptions.
Michal Vasko04f85912020-08-07 12:14:58 +02001579 * @return LY_SUCCESS on success,
1580 * @return LY_ERR on error.
1581 */
1582LY_ERR lyd_diff_merge_tree(struct lyd_node **diff_first, struct lyd_node *diff_parent, const struct lyd_node *src_sibling,
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001583 lyd_diff_cb diff_cb, void *cb_data, uint16_t options);
Michal Vasko04f85912020-08-07 12:14:58 +02001584
1585/**
Michal Vaskoe6323f62020-07-09 15:49:02 +02001586 * @brief Merge 2 diffs into each other.
1587 *
Michal Vaskoe6323f62020-07-09 15:49:02 +02001588 * @param[in,out] diff Target diff to merge into.
Michal Vaskofb737aa2020-08-06 13:53:53 +02001589 * @param[in] src_diff Source diff.
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001590 * @param[in] options Bitmask of options flags, see @ref diffmergeoptions.
Michal Vaskoe6323f62020-07-09 15:49:02 +02001591 * @return LY_SUCCESS on success,
1592 * @return LY_ERR on error.
1593 */
Michal Vaskoc0e58e82020-11-11 19:04:33 +01001594LY_ERR lyd_diff_merge_all(struct lyd_node **diff, const struct lyd_node *src_diff, uint16_t options);
Michal Vaskoe6323f62020-07-09 15:49:02 +02001595
1596/**
Michal Vasko4231fb62020-07-13 13:54:47 +02001597 * @brief Reverse a diff and make the opposite changes. Meaning change create to delete, delete to create,
1598 * or move from place A to B to move from B to A and so on.
1599 *
1600 * @param[in] src_diff Diff to reverse.
1601 * @param[out] diff Reversed diff.
1602 * @return LY_SUCCESS on success.
1603 * @return LY_ERR on error.
1604 */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001605LY_ERR lyd_diff_reverse_all(const struct lyd_node *src_diff, struct lyd_node **diff);
Michal Vasko4231fb62020-07-13 13:54:47 +02001606
1607/**
Radek Krejcifba9c622020-10-30 08:28:54 +01001608 * @brief Find the target in data of a compiled instance-identifier path (the target member in ::lyd_value).
Michal Vasko4490d312020-06-16 13:08:55 +02001609 *
1610 * @param[in] path Compiled path structure.
Michal Vaskof03ed032020-03-04 13:31:44 +01001611 * @param[in] tree Data tree to be searched.
Michal Vasko4490d312020-06-16 13:08:55 +02001612 * @return Found target node,
1613 * @return NULL if not found.
Radek Krejci576b23f2019-07-12 14:06:32 +02001614 */
Michal Vasko004d3152020-06-11 19:59:22 +02001615const struct lyd_node_term *lyd_target(const struct ly_path *path, const struct lyd_node *tree);
Radek Krejci084289f2019-07-09 17:35:30 +02001616
Michal Vasko5ec7cda2019-09-11 13:43:08 +02001617/**
Michal Vasko5ec7cda2019-09-11 13:43:08 +02001618 * @brief Types of the different data paths.
1619 */
1620typedef enum {
Michal Vasko14654712020-02-06 08:35:21 +01001621 LYD_PATH_LOG, /**< Descriptive path format used in log messages */
Michal Vasko69730152020-10-09 16:30:07 +02001622 LYD_PATH_LOG_NO_LAST_PRED /**< Similar to ::LYD_PATH_LOG except there is never a predicate on the last node */
Michal Vasko5ec7cda2019-09-11 13:43:08 +02001623} LYD_PATH_TYPE;
1624
1625/**
1626 * @brief Generate path of the given node in the requested format.
1627 *
1628 * @param[in] node Schema path of this node will be generated.
1629 * @param[in] pathtype Format of the path to generate.
1630 * @param[in,out] buffer Prepared buffer of the @p buflen length to store the generated path.
1631 * If NULL, memory for the complete path is allocated.
1632 * @param[in] buflen Size of the provided @p buffer.
1633 * @return NULL in case of memory allocation error, path of the node otherwise.
1634 * In case the @p buffer is NULL, the returned string is dynamically allocated and caller is responsible to free it.
1635 */
1636char *lyd_path(const struct lyd_node *node, LYD_PATH_TYPE pathtype, char *buffer, size_t buflen);
1637
Michal Vaskoe444f752020-02-10 12:20:06 +01001638/**
Michal Vasko25a32822020-07-09 15:48:22 +02001639 * @brief Find a specific metadata.
1640 *
1641 * @param[in] first First metadata to consider.
1642 * @param[in] module Module of the metadata definition, may be NULL if @p name includes a prefix.
1643 * @param[in] name Name of the metadata to find, may not include a prefix (module name) if @p module is set.
1644 * @return Found metadata,
1645 * @return NULL if not found.
1646 */
1647struct lyd_meta *lyd_find_meta(const struct lyd_meta *first, const struct lys_module *module, const char *name);
1648
1649/**
Michal Vaskoda859032020-07-14 12:20:14 +02001650 * @brief Search in the given siblings (NOT recursively) for the first target instance with the same value.
Michal Vaskoe444f752020-02-10 12:20:06 +01001651 * Uses hashes - should be used whenever possible for best performance.
1652 *
1653 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
1654 * @param[in] target Target node to find.
Michal Vasko9b368d32020-02-14 13:53:31 +01001655 * @param[out] match Can be NULL, otherwise the found data node.
Michal Vaskoe444f752020-02-10 12:20:06 +01001656 * @return LY_SUCCESS on success, @p match set.
1657 * @return LY_ENOTFOUND if not found, @p match set to NULL.
1658 * @return LY_ERR value if another error occurred.
1659 */
1660LY_ERR lyd_find_sibling_first(const struct lyd_node *siblings, const struct lyd_node *target, struct lyd_node **match);
1661
1662/**
Michal Vaskoe444f752020-02-10 12:20:06 +01001663 * @brief Search in the given siblings for the first schema instance.
1664 * Uses hashes - should be used whenever possible for best performance.
1665 *
1666 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
1667 * @param[in] schema Schema node of the data node to find.
Michal Vaskob104f112020-07-17 09:54:54 +02001668 * @param[in] key_or_value If it is NULL, the first schema node data instance is found. For nodes with many
1669 * instances, it can be set based on the type of @p schema:
Michal Vaskoe444f752020-02-10 12:20:06 +01001670 * LYS_LEAFLIST:
1671 * Searched instance value.
1672 * LYS_LIST:
Michal Vasko90932a92020-02-12 14:33:03 +01001673 * Searched instance key values in the form of "[key1='val1'][key2='val2']...".
1674 * The keys do not have to be ordered but all of them must be set.
1675 *
1676 * Note that any explicit values (leaf-list or list key values) will be canonized first
1677 * before comparison. But values that do not have a canonical value are expected to be in the
1678 * JSON format!
Michal Vaskof03ed032020-03-04 13:31:44 +01001679 * @param[in] val_len Optional length of @p key_or_value in case it is not 0-terminated.
Michal Vasko9b368d32020-02-14 13:53:31 +01001680 * @param[out] match Can be NULL, otherwise the found data node.
Michal Vaskoe444f752020-02-10 12:20:06 +01001681 * @return LY_SUCCESS on success, @p match set.
1682 * @return LY_ENOTFOUND if not found, @p match set to NULL.
1683 * @return LY_EINVAL if @p schema is a key-less list.
1684 * @return LY_ERR value if another error occurred.
1685 */
1686LY_ERR lyd_find_sibling_val(const struct lyd_node *siblings, const struct lysc_node *schema, const char *key_or_value,
Radek Krejci0f969882020-08-21 16:56:47 +02001687 size_t val_len, struct lyd_node **match);
Michal Vaskoe444f752020-02-10 12:20:06 +01001688
Michal Vaskoccc02342020-05-21 10:09:21 +02001689/**
1690 * @brief Search in the given data for instances of nodes matching the provided XPath.
1691 *
Michal Vaskob104f112020-07-17 09:54:54 +02001692 * The expected format of the expression is ::LYD_JSON, meaning the first node in every path
Michal Vasko61ac2f62020-05-25 12:39:51 +02001693 * must have its module name as prefix or be the special `*` value for all the nodes.
1694 *
Michal Vasko19a30602020-05-25 10:40:19 +02001695 * If a list instance is being selected with all its key values specified (but not necessarily ordered)
1696 * in the form `list[key1='val1'][key2='val2'][key3='val3']` or a leaf-list instance in the form
1697 * `leaf-list[.='val']`, these instances are found using hashes with constant (*O(1)*) complexity
1698 * (unless they are defined in top-level). Other predicates can still follow the aforementioned ones.
1699 *
Michal Vaskoccc02342020-05-21 10:09:21 +02001700 * @param[in] ctx_node XPath context node.
1701 * @param[in] xpath Data XPath expression filtering the matching nodes. ::LYD_JSON format is expected.
1702 * @param[out] set Set of found data nodes. In case the result is a number, a string, or a boolean,
1703 * the returned set is empty.
1704 * @return LY_SUCCESS on success, @p set is returned.
1705 * @return LY_ERR value if an error occurred.
1706 */
1707LY_ERR lyd_find_xpath(const struct lyd_node *ctx_node, const char *xpath, struct ly_set **set);
1708
Radek Krejcie7b95092019-05-15 11:03:07 +02001709#ifdef __cplusplus
1710}
1711#endif
1712
1713#endif /* LY_TREE_DATA_H_ */