blob: 9f918af223e23d7eda877e8cdb339469ee37ae5c [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
2 * @file tree_data.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vasko2b421d92021-05-18 16:33:36 +02004 * @author Michal Vasko <mvasko@cesnet.cz>
Radek Krejcie7b95092019-05-15 11:03:07 +02005 * @brief libyang representation of YANG data trees.
6 *
Michal Vasko4e947032024-01-22 12:17:51 +01007 * Copyright (c) 2015 - 2024 CESNET, z.s.p.o.
Radek Krejcie7b95092019-05-15 11:03:07 +02008 *
9 * This source code is licensed under BSD 3-Clause License (the "License").
10 * You may not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * https://opensource.org/licenses/BSD-3-Clause
14 */
15
16#ifndef LY_TREE_DATA_H_
17#define LY_TREE_DATA_H_
18
Jan Kundráta3d248e2021-12-14 18:05:26 +010019#ifdef _WIN32
20# include <winsock2.h>
21# include <ws2tcpip.h>
22#else
23# include <arpa/inet.h>
24# if defined (__FreeBSD__) || defined (__NetBSD__) || defined (__OpenBSD__)
25# include <netinet/in.h>
26# include <sys/socket.h>
27# endif
Michal Vasko2b421d92021-05-18 16:33:36 +020028#endif
Radek Krejcie7b95092019-05-15 11:03:07 +020029#include <stddef.h>
30#include <stdint.h>
Michal Vasko2b421d92021-05-18 16:33:36 +020031#include <time.h>
Radek Krejcie7b95092019-05-15 11:03:07 +020032
33#include "log.h"
Michal Vasko8f702ee2024-02-20 15:44:24 +010034#include "ly_config.h"
Christian Hopps59618972021-02-01 05:01:35 -050035#include "tree.h"
36#include "tree_schema.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020037
Radek Krejcica376bd2020-06-11 16:04:06 +020038#ifdef __cplusplus
39extern "C" {
40#endif
41
Radek Krejcie7b95092019-05-15 11:03:07 +020042struct ly_ctx;
Michal Vasko004d3152020-06-11 19:59:22 +020043struct ly_path;
Radek Krejci535ea9f2020-05-29 16:01:05 +020044struct ly_set;
45struct lyd_node;
46struct lyd_node_opaq;
Radek Krejci47fab892020-11-05 17:02:41 +010047struct lyd_node_term;
Michal Vasko43297a02021-05-19 11:12:37 +020048struct timespec;
aPiecekdf23eee2021-10-07 12:21:50 +020049struct lyxp_var;
aPiecek6cf1d162023-11-08 16:07:00 +010050struct rb_node;
Radek Krejcie7b95092019-05-15 11:03:07 +020051
Radek Krejcie7b95092019-05-15 11:03:07 +020052/**
Radek Krejci8678fa42020-08-18 16:07:28 +020053 * @page howtoData Data Instances
54 *
55 * All the nodes in data tree comes are based on ::lyd_node structure. According to the content of the ::lyd_node.schema
56 * it can be cast to several other structures.
57 *
58 * In case the ::lyd_node.schema pointer is NULL, the node is actually __opaq__ and can be safely cast to ::lyd_node_opaq.
59 * The opaq node represent an unknown node which wasn't mapped to any [(compiled) schema](@ref howtoSchema) node in the
60 * context. Such a node can appear in several places in the data tree.
61 * - As a part of the tree structure, but only in the case the ::LYD_PARSE_OPAQ option was used when input data were
62 * [parsed](@ref howtoDataParsers), because unknown data instances are ignored by default. The same way, the opaq nodes can
63 * appear as a node's attributes.
64 * - As a representation of YANG anydata/anyxml content.
65 * - As envelopes of standard data tree instances (RPCs, actions or Notifications).
66 *
67 * In case the data node has its definition in a [compiled schema tree](@ref howtoSchema), the structure of the data node is
68 * actually one of the followings according to the schema node's nodetype (::lysc_node.nodetype).
69 * - ::lyd_node_inner - represents data nodes corresponding to schema nodes matching ::LYD_NODE_INNER nodetypes. They provide
70 * structure of the tree by having children nodes.
71 * - ::lyd_node_term - represents data nodes corresponding to schema nodes matching ::LYD_NODE_TERM nodetypes. The terminal
72 * nodes provide values of the particular configuration/status information. The values are represented as ::lyd_value
Radek Krejci6d5ba0c2021-04-26 07:49:59 +020073 * structure with string representation of the value (retrieved by ::lyd_get_value() and ::lyd_get_meta_value()) and
74 * the type specific data stored in the structure's union according to the real type of the value (::lyd_value.realtype).
75 * The string representation provides canonical representation of the value in case the type has the canonical
76 * representation specified. Otherwise, it is the original value or, in case the value can contain prefixes, the JSON
77 * format is used to make the value unambiguous.
Radek Krejci8678fa42020-08-18 16:07:28 +020078 * - ::lyd_node_any - represents data nodes corresponding to schema nodes matching ::LYD_NODE_ANY nodetypes.
79 *
80 * Despite all the aforementioned structures and their members are available as part of the libyang API and callers can use
81 * it to navigate through the data tree structure or to obtain various information, we recommend to use the following macros
82 * and functions.
83 * - ::lyd_child() (or ::lyd_child_no_keys()) and ::lyd_parent() to get the node's child/parent node.
84 * - ::LYD_CTX to get libyang context from a data node.
Radek Krejci6d5ba0c2021-04-26 07:49:59 +020085 * - ::lyd_get_value()/::lyd_get_meta_value() to get canonical string value from a terminal node/metadata instance.
Radek Krejci8678fa42020-08-18 16:07:28 +020086 * - ::LYD_TREE_DFS_BEGIN and ::LYD_TREE_DFS_END to traverse the data tree (depth-first).
87 * - ::LY_LIST_FOR and ::LY_ARRAY_FOR as described on @ref howtoStructures page.
88 *
89 * Instead of going through the data tree on your own, a specific data node can be also located using a wide set of
90 * \b lyd_find_*() functions.
91 *
92 * More information about specific operations with data instances can be found on the following pages:
93 * - @subpage howtoDataParsers
94 * - @subpage howtoDataValidation
95 * - @subpage howtoDataWD
96 * - @subpage howtoDataManipulation
97 * - @subpage howtoDataPrinters
Radek Krejcif9943642021-04-26 10:18:21 +020098 * - @subpage howtoDataLYB
Radek Krejci8678fa42020-08-18 16:07:28 +020099 *
100 * \note API for this group of functions is described in the [Data Instances module](@ref datatree).
101 *
102 * Functions List (not assigned to above subsections)
103 * --------------------------------------------------
104 * - ::lyd_child()
105 * - ::lyd_child_no_keys()
106 * - ::lyd_parent()
107 * - ::lyd_owner_module()
Radek Krejci6d5ba0c2021-04-26 07:49:59 +0200108 * - ::lyd_get_value()
109 * - ::lyd_get_meta_value()
Radek Krejci8678fa42020-08-18 16:07:28 +0200110 * - ::lyd_find_xpath()
Michal Vasko3e1f6552021-01-14 09:27:55 +0100111 * - ::lyd_find_path()
Michal Vaskobb22b182021-06-14 08:14:21 +0200112 * - ::lyd_find_target()
Radek Krejci8678fa42020-08-18 16:07:28 +0200113 * - ::lyd_find_sibling_val()
114 * - ::lyd_find_sibling_first()
Michal Vasko1d4af6c2021-02-22 13:31:26 +0100115 * - ::lyd_find_sibling_opaq_next()
Radek Krejci8678fa42020-08-18 16:07:28 +0200116 * - ::lyd_find_meta()
117 *
118 * - ::lyd_path()
Michal Vasko2c1f66d2024-01-22 14:36:13 +0100119 * - ::lyd_find_target()
Radek Krejci8678fa42020-08-18 16:07:28 +0200120 *
121 * - ::lyd_lyb_data_length()
Radek Krejci75104122021-04-01 15:37:45 +0200122 *
123 *
124 * @section howtoDataMetadata Metadata Support
125 *
126 * YANG Metadata annotations are defined in [RFC 7952](https://tools.ietf.org/html/rfc7952) as YANG extension (and libyang
127 * [implements them as internal extension plugin](@ref howtoPluginsExtensions)). In practice, it allows to have XML
128 * attributes (there is also a special encoding for JSON) in YANG modeled data. libyang does not allow to have any XML
129 * attribute without the appropriate annotation definition describing the data as it is done e.g. for leafs. When an
130 * attribute without a matching annotation definition is found in the input data, it is:
131 * - silently dropped (with warning) or
132 * - an error is reported in case the ::LYD_PARSE_STRICT parser option is provided to the
133 * [parser function](@ref howtoDataParsers) or
134 * - stored into a generic ::lyd_attr structure without a connection with any YANG module in case the ::LYD_PARSE_OPAQ
135 * parser options is provided to the [parser function](@ref howtoDataParsers).
136 *
137 * There are some XML attributes, described by [YANG](https://tools.ietf.org/html/rfc7950) and
138 * [NETCONF](https://tools.ietf.org/html/rfc6241) specifications, which are not defined as annotations, but libyang
139 * implements them this way. In case of attributes in the YANG namespace (`insert`, `value` and `key` attributes
140 * for the NETCONF edit-config operation), they are defined in special libyang's internal module `yang`, which is
141 * available in each context and the content of this schema can be printed via
142 * [schema printers](@ref howtoSchemaPrinters).
143 *
144 * In case of the attributes described in [NETCONF specification](https://tools.ietf.org/html/rfc6241), the libyang's
145 * annotations structures are hidden and cannot be printed despite, internally, they are part of the `ietf-netconf`'s
146 * schema structure. Therefore, these attributes are available only when the `ietf-netconf` schema is loaded in the
147 * context. The definitions of these annotations are as follows:
148 *
149 * md:annotation operation {
150 * type enumeration {
151 * enum merge;
152 * enum replace;
153 * enum create;
154 * enum delete;
155 * enum remove;
156 * }
157 * }
158 *
159 * md:annotation type {
160 * type enumeration {
161 * enum subtree;
162 * enum xpath {
163 * if-feature "nc:xpath";
164 * }
165 * }
166 * }
167 *
168 * md:annotation select {
169 * type string;
170 * }
171 *
172 * Note, that, following the specification,
173 * - the `type` and `select` XML attributes are supposed to be unqualified (without namespace) and that
174 * - the `select`'s content is XPath and it is internally transformed by libyang into the format where the
175 * XML namespace prefixes are replaced by the YANG module names.
176 *
177 *
178 * @section howtoDataYangdata yang-data Support
179 *
180 * [RFC 8040](https://tools.ietf.org/html/rfc8040) defines ietf-restconf module, which includes yang-data extension. Despite
181 * the definition in the RESTCONF YANG module, the yang-data concept is quite generic and used even in modules without a
182 * connection to RESTCONF protocol. The extension allows to define a separated YANG trees usable separately from any
183 * datastore.
184 *
185 * libyang implements support for yang-data internally as an [extension plugin](@ref howtoPluginsExtensions). To ease the
186 * use of yang-data with libyang, there are several generic functions, which are usable for yang-data:
187 *
188 * - ::lyd_parse_ext_data()
189 * - ::lyd_parse_ext_op()
190 *
191 * - ::lys_getnext_ext()
192 *
193 * - ::lyd_new_ext_inner()
194 * - ::lyd_new_ext_list()
195 * - ::lyd_new_ext_term()
196 * - ::lyd_new_ext_any()
197 * - ::lyd_new_ext_path()
Michal Vasko1fd27412022-02-11 10:04:50 +0100198 *
199 * @section howtoDataMountpoint mount-point Support
200 *
201 * [RFC 8528](https://tools.ietf.org/html/rfc8528) defines mount-point extension in ietf-yang-schema-mount YANG module.
202 * This extension is supported out-of-the-box but to be able to parse data in a mount point, additional run-time data
203 * need to be provided by a callback:
204 *
205 * - ::ly_ctx_set_ext_data_clb()
Michal Vasko1c47f5f2022-03-29 11:38:40 +0200206 *
Michal Vaskob09f3ec2022-04-05 12:26:24 +0200207 * The mounted data can be parsed directly from data files or created manually using the standard functions. However,
208 * note that the mounted data use **their own context** created as needed. For *inline* data this means that any new
209 * request for a mount-point schema node results in a new context creation because it is impossible to determine
210 * whether any existing context can be used. Also, all these contexts created for the mounted data are **never**
211 * freed automatically except when the parent context is being freed. So, to avoid redundant context creation, it is
212 * always advised to use *shared-schema* for mount-points.
213 *
214 * In case it is not possible and *inline* mount point must be defined, it is still possible to avoid creating
215 * additional contexts. When the top-level node right under a schema node with a mount-point is created, always use
216 * this node for creation of any descendants. So, when using ::lyd_new_path(), use the node as `parent` and specify
217 * relative `path`.
Radek Krejci8678fa42020-08-18 16:07:28 +0200218 */
219
220/**
221 * @page howtoDataManipulation Manipulating Data
222 *
223 * There are many functions to create or modify an existing data tree. You can add new nodes, reconnect nodes from
224 * one tree to another (or e.g. from one list instance to another) or remove nodes. The functions doesn't allow you
225 * to put a node to a wrong place (by checking the YANG module structure), but not all validation checks can be made directly
226 * (or you have to make a valid change by multiple tree modifications) when the tree is being changed. Therefore,
227 * the [validation process](@ref howtoDataValidation) is expected to be invoked after changing the data tree to make sure
228 * that the changed data tree is valid.
229 *
230 * When inserting a node into data tree (no matter if the node already exists, via ::lyd_insert_child() and
231 * ::lyd_insert_sibling(), or a new node is being created), the node is automatically inserted to the place respecting the
aPiecek6cf1d162023-11-08 16:07:00 +0100232 * nodes order from the YANG schema. A leaf-list instances are sorted based on the value and the ::lyplg_type_sort_clb
233 * function defined in the given datatype. A list instances are ordered similarly based on keys. In case the node is opaq
234 * (it is not connected with any schema node), it is placed to the end of the sibling node in the order they are inserted in.
235 * The only situation when it is possible to influence the order of the nodes is the order of user-ordered list/leaf-list
236 * instances. In such a case the ::lyd_insert_after(), ::lyd_insert_before() can be used and ::lyd_insert_child(),
237 * ::lyd_insert_sibling() adds the node after the existing instance of the closest preceding sibling node from the schema.
Radek Krejci8678fa42020-08-18 16:07:28 +0200238 *
239 * Creating data is generally possible in two ways, they can be combined. You can add nodes one-by-one based on
240 * the node name and/or its parent (::lyd_new_inner(), ::lyd_new_term(), ::lyd_new_any(), ::lyd_new_list(), ::lyd_new_list2()
Michal Vasko493900b2020-12-08 10:23:41 +0100241 * and ::lyd_new_opaq()) or address the nodes using a [simple XPath addressing](@ref howtoXPath) (::lyd_new_path() and
242 * ::lyd_new_path2()). The latter enables to create a whole path of nodes, requires less information
Radek Krejci8678fa42020-08-18 16:07:28 +0200243 * about the modified data, and is generally simpler to use. Actually the third way is duplicating the existing data using
244 * ::lyd_dup_single(), ::lyd_dup_siblings() and ::lyd_dup_meta_single().
245 *
Radek Krejci8a5afc22021-03-12 11:10:47 +0100246 * Note, that in case the node is defined in an extension instance, the functions mentioned above do not work until you
247 * provide parent where the new node is supposed to be inserted. The reason is that all the functions searches for the
248 * top-level nodes directly inside modules. To create a top-level node defined in an extension instance, use
Radek Krejci95ccd1b2021-03-12 14:57:22 +0100249 * ::lyd_new_ext_inner(), ::lyd_new_ext_term(), ::lyd_new_ext_any(), ::lyd_new_ext_list() and ::lyd_new_ext_path()
250 * functions.
Radek Krejci8a5afc22021-03-12 11:10:47 +0100251 *
Radek Krejci75104122021-04-01 15:37:45 +0200252 * The [metadata](@ref howtoDataMetadata) (and attributes in opaq nodes) can be created with ::lyd_new_meta()
Radek Krejci8678fa42020-08-18 16:07:28 +0200253 * and ::lyd_new_attr().
254 *
255 * Changing value of a terminal node (leaf, leaf-list) is possible with ::lyd_change_term(). Similarly, the metadata value
256 * can be changed with ::lyd_change_meta(). Before changing the value, it might be useful to compare the node's value
257 * with a string value (::lyd_value_compare()) or verify that the new string value is correct for the specific data node
258 * (::lyd_value_validate()).
259 *
260 * Working with two existing subtrees can also be performed two ways. Usually, you would use lyd_insert*() functions.
261 * They are generally meant for simple inserts of a node into a data tree. For more complicated inserts and when
262 * merging 2 trees use ::lyd_merge_tree() or ::lyd_merge_siblings(). It offers additional options and is basically a more
263 * powerful insert.
264 *
265 * Besides merging, libyang is also capable to provide information about differences between two data trees. For this purpose,
266 * ::lyd_diff_tree() and ::lyd_diff_siblings() generates annotated data trees which can be, in addition, used to change one
267 * data tree to another one using ::lyd_diff_apply_all(), ::lyd_diff_apply_module() and ::lyd_diff_reverse_all(). Multiple
268 * diff data trees can be also put together for further work using ::lyd_diff_merge_all(), ::lyd_diff_merge_module() and
269 * ::lyd_diff_merge_tree() functions. To just check equivalence of the data nodes, ::lyd_compare_single(),
270 * ::lyd_compare_siblings() and ::lyd_compare_meta() can be used.
271 *
272 * To remove a node or subtree from a data tree, use ::lyd_unlink_tree() and then free the unwanted data using
273 * ::lyd_free_all() (or other \b lyd_free_*() functions).
274 *
275 * Also remember, that when you are creating/inserting a node, all the objects in that operation must belong to the
276 * same context.
277 *
278 * Modifying the single data tree in multiple threads is not safe.
279 *
280 * Functions List
281 * --------------
282 * - ::lyd_new_inner()
283 * - ::lyd_new_term()
Radek Krejci09c77442021-04-26 11:10:34 +0200284 * - ::lyd_new_term_bin()
Radek Krejci8678fa42020-08-18 16:07:28 +0200285 * - ::lyd_new_list()
286 * - ::lyd_new_list2()
stewegd4cde642024-02-21 08:34:16 +0100287 * - ::lyd_new_list3()
Radek Krejci8678fa42020-08-18 16:07:28 +0200288 * - ::lyd_new_any()
289 * - ::lyd_new_opaq()
Michal Vasko8d65f852021-02-17 11:28:13 +0100290 * - ::lyd_new_opaq2()
Radek Krejci8678fa42020-08-18 16:07:28 +0200291 * - ::lyd_new_attr()
Michal Vasko8d65f852021-02-17 11:28:13 +0100292 * - ::lyd_new_attr2()
Radek Krejci8678fa42020-08-18 16:07:28 +0200293 * - ::lyd_new_meta()
294 * - ::lyd_new_path()
295 * - ::lyd_new_path2()
Radek Krejci8678fa42020-08-18 16:07:28 +0200296 *
Radek Krejcidd2a7662021-03-12 11:26:34 +0100297 * - ::lyd_new_ext_inner()
Radek Krejci8a5afc22021-03-12 11:10:47 +0100298 * - ::lyd_new_ext_term()
Radek Krejci8247bae2021-03-12 11:47:02 +0100299 * - ::lyd_new_ext_list()
Radek Krejci0b963da2021-03-12 13:23:44 +0100300 * - ::lyd_new_ext_any()
Radek Krejci95ccd1b2021-03-12 14:57:22 +0100301 * - ::lyd_new_ext_path()
Radek Krejci8a5afc22021-03-12 11:10:47 +0100302 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200303 * - ::lyd_dup_single()
304 * - ::lyd_dup_siblings()
305 * - ::lyd_dup_meta_single()
306 *
307 * - ::lyd_insert_child()
308 * - ::lyd_insert_sibling()
309 * - ::lyd_insert_after()
310 * - ::lyd_insert_before()
311 *
312 * - ::lyd_value_compare()
313 * - ::lyd_value_validate()
314 *
315 * - ::lyd_change_term()
Radek Krejci09c77442021-04-26 11:10:34 +0200316 * - ::lyd_change_term_bin()
317 * - ::lyd_change_term_canon()
Radek Krejci8678fa42020-08-18 16:07:28 +0200318 * - ::lyd_change_meta()
319 *
320 * - ::lyd_compare_single()
321 * - ::lyd_compare_siblings()
322 * - ::lyd_compare_meta()
323 * - ::lyd_diff_tree()
324 * - ::lyd_diff_siblings()
325 * - ::lyd_diff_apply_all()
326 * - ::lyd_diff_apply_module()
327 * - ::lyd_diff_reverse_all()
328 * - ::lyd_diff_merge_all()
329 * - ::lyd_diff_merge_module()
330 * - ::lyd_diff_merge_tree()
331 *
332 * - ::lyd_merge_tree()
333 * - ::lyd_merge_siblings()
Michal Vaskocd3f6172021-05-18 16:14:50 +0200334 * - ::lyd_merge_module()
Radek Krejci8678fa42020-08-18 16:07:28 +0200335 *
336 * - ::lyd_unlink_tree()
337 *
338 * - ::lyd_free_all()
339 * - ::lyd_free_siblings()
340 * - ::lyd_free_tree()
341 * - ::lyd_free_meta_single()
342 * - ::lyd_free_meta_siblings()
343 * - ::lyd_free_attr_single()
344 * - ::lyd_free_attr_siblings()
345 *
Michal Vaskoa820c312021-02-05 16:33:00 +0100346 * - ::lyd_any_value_str()
Radek Krejci8678fa42020-08-18 16:07:28 +0200347 * - ::lyd_any_copy_value()
348 */
349
350/**
351 * @page howtoDataWD Default Values
352 *
353 * libyang provides support for work with default values as defined in [RFC 6243](https://tools.ietf.org/html/rfc6243).
354 * However, libyang context do not contains the *ietf-netconf-with-defaults* module on its own and caller is supposed to
355 * add this YANG module to enable full support of the *with-defaults* features described below. Without presence of the
356 * mentioned module in the context, the default nodes are still present and handled in the data trees, but the metadata
357 * providing the information about the default values cannot be used. It means that when parsing data, the default nodes
358 * marked with the metadata as implicit default nodes are handled as explicit data and when printing data tree, the expected
359 * nodes are printed without the ietf-netconf-with-defaults metadata.
360 *
361 * The RFC document defines 4 modes for handling default nodes in a data tree, libyang adds the fifth mode and use them
362 * via @ref dataprinterflags when printing data trees.
363 * - \b explicit - Only the explicitly set configuration data. But in the case of status data, missing default
364 * data are added into the tree. In libyang, this mode is represented by ::LYD_PRINT_WD_EXPLICIT option.
365 * This is the default with-defaults mode of the printer. The data nodes do not contain any additional
366 * metadata information.
367 * - \b trim - Data nodes containing the default value are removed. This mode is applied with ::LYD_PRINT_WD_TRIM option.
368 * - \b report-all - This mode provides all the default data nodes despite they were explicitly present in source data or
369 * they were added by libyang's [validation process](@ref howtoDataValidation). This mode is activated by
370 * ::LYD_PRINT_WD_ALL option.
371 * - \b report-all-tagged - In this case, all the data nodes (implicit as well the explicit) containing the default value
372 * are printed and tagged (see the note below). Printers accept ::LYD_PRINT_WD_ALL_TAG option for this mode.
373 * - \b report-implicit-tagged - The last mode is similar to the previous one, except only the implicitly added nodes
374 * are tagged. This is the libyang's extension and it is activated by ::LYD_PRINT_WD_IMPL_TAG option.
375 *
376 * Internally, libyang adds the default nodes into the data tree as part of the [validation process](@ref howtoDataValidation).
377 * When [parsing data](@ref howtoDataParsers) from an input source, adding default nodes can be avoided only by avoiding
378 * the whole [validation process](@ref howtoDataValidation). In case the ietf-netconf-with-defaults module is present in the
379 * context, the [parser process](@ref howtoDataParsers) also supports to recognize the implicit default nodes marked with the
380 * appropriate metadata.
381 *
382 * Note, that in a modified data tree (via e.g. \b lyd_insert_*() or \b lyd_free_*() functions), some of the default nodes
383 * can be missing or they can be present by mistake. Such a data tree is again corrected during the next run of the
384 * [validation process](@ref howtoDataValidation) or manualy using \b lyd_new_implicit_*() functions.
385 *
386 * The implicit (default) nodes, created by libyang, are marked with the ::LYD_DEFAULT flag in ::lyd_node.flags member
387 * Note, that besides leafs and leaf-lists, the flag can appear also in containers, where it means that the container
388 * 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
389 * the accessible data tree). When printing data trees, the presence of empty containers (despite they were added
390 * explicitly or implicitly as part of accessible data tree) depends on ::LYD_PRINT_KEEPEMPTYCONT option.
391 *
392 * To get know if the particular leaf or leaf-list node contains default value (despite implicit or explicit), you can
393 * use ::lyd_is_default() function.
394 *
395 * Functions List
396 * --------------
397 * - ::lyd_is_default()
398 * - ::lyd_new_implicit_all()
399 * - ::lyd_new_implicit_module()
400 * - ::lyd_new_implicit_tree()
401 */
402
403/**
Radek Krejcif9943642021-04-26 10:18:21 +0200404 * @page howtoDataLYB LYB Binary Format
405 *
406 * LYB (LibYang Binary) is a proprietary libyang binary data and file format. Its primary purpose is efficient
407 * serialization (printing) and deserialization (parsing). With this goal in mind, every term node value is stored
408 * in its new binary format specification according to its type. Following is the format for all types with explicit
409 * support out-of-the-box (meaning that have a special type plugin). Any derived types inherit the format of its
410 * closest type with explicit support (up to a built-in type).
Radek Krejci09c77442021-04-26 11:10:34 +0200411 *
Michal Vaskof1bcb5c2021-04-30 09:21:25 +0200412 * @section howtoDataLYBTypes Format of specific data type values
Radek Krejcif9943642021-04-26 10:18:21 +0200413 */
414
415/**
Radek Krejci2ff0d572020-05-21 15:27:28 +0200416 * @ingroup trees
Radek Krejci8678fa42020-08-18 16:07:28 +0200417 * @defgroup datatree Data Tree
Radek Krejcie7b95092019-05-15 11:03:07 +0200418 * @{
419 *
420 * Data structures and functions to manipulate and access instance data tree.
421 */
422
Michal Vasko64246d82020-08-19 12:35:00 +0200423/* *INDENT-OFF* */
424
Michal Vaskoa276cd92020-08-10 15:10:08 +0200425/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200426 * @brief Macro to iterate via all elements in a data tree. This is the opening part
427 * to the #LYD_TREE_DFS_END - they always have to be used together.
428 *
429 * The function follows deep-first search algorithm:
430 * <pre>
431 * 1
432 * / \
Michal Vaskoc193ce92020-03-06 11:04:48 +0100433 * 2 4
Radek Krejcie7b95092019-05-15 11:03:07 +0200434 * / / \
Michal Vaskoc193ce92020-03-06 11:04:48 +0100435 * 3 5 6
Radek Krejcie7b95092019-05-15 11:03:07 +0200436 * </pre>
437 *
Radek Krejci0935f412019-08-20 16:15:18 +0200438 * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While
Michal Vasko56daf732020-08-10 10:57:18 +0200439 * START can be any of the lyd_node* types, ELEM variable must be a pointer to
440 * the generic struct lyd_node.
Radek Krejcie7b95092019-05-15 11:03:07 +0200441 *
Michal Vasko56daf732020-08-10 10:57:18 +0200442 * To skip a particular subtree, instead of the continue statement, set LYD_TREE_DFS_continue
443 * variable to non-zero value.
Radek Krejcie7b95092019-05-15 11:03:07 +0200444 *
445 * Use with opening curly bracket '{' after the macro.
446 *
447 * @param START Pointer to the starting element processed first.
Radek Krejcie7b95092019-05-15 11:03:07 +0200448 * @param ELEM Iterator intended for use in the block.
449 */
Michal Vasko56daf732020-08-10 10:57:18 +0200450#define LYD_TREE_DFS_BEGIN(START, ELEM) \
Radek Krejci857189e2020-09-01 13:26:36 +0200451 { ly_bool LYD_TREE_DFS_continue = 0; struct lyd_node *LYD_TREE_DFS_next; \
Michal Vasko56daf732020-08-10 10:57:18 +0200452 for ((ELEM) = (LYD_TREE_DFS_next) = (struct lyd_node *)(START); \
Radek Krejcie7b95092019-05-15 11:03:07 +0200453 (ELEM); \
Michal Vasko56daf732020-08-10 10:57:18 +0200454 (ELEM) = (LYD_TREE_DFS_next), LYD_TREE_DFS_continue = 0)
Radek Krejcie7b95092019-05-15 11:03:07 +0200455
456/**
457 * @brief Macro to iterate via all elements in a tree. This is the closing part
458 * to the #LYD_TREE_DFS_BEGIN - they always have to be used together.
459 *
460 * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While
Michal Vasko56daf732020-08-10 10:57:18 +0200461 * START can be any of the lyd_node* types, ELEM variable must be a pointer
462 * to the generic struct lyd_node.
Radek Krejcie7b95092019-05-15 11:03:07 +0200463 *
464 * Use with closing curly bracket '}' after the macro.
465 *
466 * @param START Pointer to the starting element processed first.
Radek Krejcie7b95092019-05-15 11:03:07 +0200467 * @param ELEM Iterator intended for use in the block.
468 */
469
Michal Vasko56daf732020-08-10 10:57:18 +0200470#define LYD_TREE_DFS_END(START, ELEM) \
Radek Krejcie7b95092019-05-15 11:03:07 +0200471 /* select element for the next run - children first */ \
Michal Vasko56daf732020-08-10 10:57:18 +0200472 if (LYD_TREE_DFS_continue) { \
473 (LYD_TREE_DFS_next) = NULL; \
474 } else { \
Radek Krejcia1c1e542020-09-29 16:06:52 +0200475 (LYD_TREE_DFS_next) = lyd_child(ELEM); \
Michal Vasko56daf732020-08-10 10:57:18 +0200476 }\
477 if (!(LYD_TREE_DFS_next)) { \
Radek Krejcie7b95092019-05-15 11:03:07 +0200478 /* no children */ \
Michal Vasko9e685082021-01-29 14:49:09 +0100479 if ((ELEM) == (struct lyd_node *)(START)) { \
Radek Krejcie7b95092019-05-15 11:03:07 +0200480 /* we are done, (START) has no children */ \
481 break; \
482 } \
483 /* try siblings */ \
Michal Vasko56daf732020-08-10 10:57:18 +0200484 (LYD_TREE_DFS_next) = (ELEM)->next; \
Radek Krejcie7b95092019-05-15 11:03:07 +0200485 } \
Michal Vasko56daf732020-08-10 10:57:18 +0200486 while (!(LYD_TREE_DFS_next)) { \
Radek Krejcie7b95092019-05-15 11:03:07 +0200487 /* parent is already processed, go to its sibling */ \
Michal Vasko9e685082021-01-29 14:49:09 +0100488 (ELEM) = (struct lyd_node *)(ELEM)->parent; \
Radek Krejcie7b95092019-05-15 11:03:07 +0200489 /* no siblings, go back through parents */ \
490 if ((ELEM)->parent == (START)->parent) { \
491 /* we are done, no next element to process */ \
492 break; \
493 } \
Michal Vasko56daf732020-08-10 10:57:18 +0200494 (LYD_TREE_DFS_next) = (ELEM)->next; \
Christian Hopps59618972021-02-01 05:01:35 -0500495 } }
496
497/**
498 * @brief Macro to iterate via all schema node data instances in data siblings.
499 *
500 * @param START Pointer to the starting sibling. Even if it is not first, all the siblings are searched.
501 * @param SCHEMA Schema node of the searched instances.
502 * @param ELEM Iterator.
503 */
504#define LYD_LIST_FOR_INST(START, SCHEMA, ELEM) \
505 for (lyd_find_sibling_val(START, SCHEMA, NULL, 0, &(ELEM)); \
506 (ELEM) && ((ELEM)->schema == (SCHEMA)); \
507 (ELEM) = (ELEM)->next)
508
509/**
510 * @brief Macro to iterate via all schema node data instances in data siblings allowing to modify the list itself.
511 *
512 * @param START Pointer to the starting sibling. Even if it is not first, all the siblings are searched.
513 * @param SCHEMA Schema node of the searched instances.
514 * @param NEXT Temporary storage to allow removing of the current iterator content.
515 * @param ELEM Iterator.
516 */
517#define LYD_LIST_FOR_INST_SAFE(START, SCHEMA, NEXT, ELEM) \
Michal Vasko61ad1ff2022-02-10 15:48:39 +0100518 for ((NEXT) = (ELEM) = NULL, lyd_find_sibling_val(START, SCHEMA, NULL, 0, &(ELEM)); \
Christian Hopps59618972021-02-01 05:01:35 -0500519 (ELEM) && ((ELEM)->schema == (SCHEMA)) ? ((NEXT) = (ELEM)->next, 1) : 0; \
520 (ELEM) = (NEXT))
Radek Krejcie7b95092019-05-15 11:03:07 +0200521
Michal Vasko64246d82020-08-19 12:35:00 +0200522/* *INDENT-ON* */
523
Radek Krejcie7b95092019-05-15 11:03:07 +0200524/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200525 * @brief Macro to get context from a data tree node.
526 */
Michal Vasko5c7a8322021-06-25 09:12:05 +0200527#define LYD_CTX(node) ((node)->schema ? (node)->schema->module->ctx : ((const struct lyd_node_opaq *)(node))->ctx)
Michal Vasko03ff5a72019-09-11 13:49:33 +0200528
529/**
aPiecek6cf1d162023-11-08 16:07:00 +0100530 * @brief Find out if the node is the only instance, i.e. it has no siblings with the same schema.
531 *
532 * @param[in] NODE Pointer to the struct lyd_node.
533 * @return 1 @p NODE is a single instance (is alone).
534 * @return 0 @p NODE is not alone.
535 */
536#define LYD_NODE_IS_ALONE(NODE) \
537 (((NODE)->prev == NODE) || \
538 (((NODE)->prev->schema != (NODE)->schema) && (!(NODE)->next || ((NODE)->schema != (NODE)->next->schema))))
539
540/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200541 * @brief Data input/output formats supported by libyang [parser](@ref howtoDataParsers) and
542 * [printer](@ref howtoDataPrinters) functions.
Radek Krejcie7b95092019-05-15 11:03:07 +0200543 */
544typedef enum {
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200545 LYD_UNKNOWN = 0, /**< unknown data format, invalid value */
546 LYD_XML, /**< XML instance data format */
547 LYD_JSON, /**< JSON instance data format */
Michal Vasko69730152020-10-09 16:30:07 +0200548 LYD_LYB /**< LYB instance data format */
Radek Krejcie7b95092019-05-15 11:03:07 +0200549} LYD_FORMAT;
550
551/**
Radek Krejci59583bb2019-09-11 12:57:55 +0200552 * @brief List of possible value types stored in ::lyd_node_any.
Radek Krejcie7b95092019-05-15 11:03:07 +0200553 */
554typedef enum {
Radek Krejci8678fa42020-08-18 16:07:28 +0200555 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 +0200556 is directly connected into the anydata node without duplication, caller is supposed to not manipulate
Radek Krejci8678fa42020-08-18 16:07:28 +0200557 with the data after a successful call (including calling ::lyd_free_all() on the provided data) */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200558 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 +0200559 as string). XML sensitive characters (such as & or \>) are automatically escaped when the anydata
560 is printed in XML format. */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200561 LYD_ANYDATA_XML, /**< Value is a string containing the serialized XML data. */
562 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 +0200563 LYD_ANYDATA_LYB /**< Value is a memory chunk with the serialized data tree in LYB format. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200564} LYD_ANYDATA_VALUETYPE;
565
566/** @} */
567
568/**
569 * @brief YANG data representation
570 */
571struct lyd_value {
Radek Krejci995784f2021-04-26 08:02:13 +0200572 const char *_canonical; /**< Should never be accessed directly, instead ::lyd_get_value() and ::lyd_get_meta_value()
Radek Krejci6d5ba0c2021-04-26 07:49:59 +0200573 should be used. Serves as a cache for the canonical value or the JSON
574 representation if no canonical value is defined. */
Michal Vaskoaa0ee622021-05-11 09:29:25 +0200575 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
576 in the schema node of the data node since the type's store plugin can use other types/plugins for
577 storing data. Speaking about built-in types, this is the case of leafref which stores data as its
578 target type. In contrast, union type also uses its subtype's callbacks, but inside an internal data
579 stored in subvalue member of ::lyd_value structure, so here is the pointer to the union type.
580 In general, this type is used to get free callback for this lyd_value structure, so it must reflect
581 the type used to store data directly in the same lyd_value instance. */
Radek Krejci8678fa42020-08-18 16:07:28 +0200582
Radek Krejcie7b95092019-05-15 11:03:07 +0200583 union {
Radek Krejcie7b95092019-05-15 11:03:07 +0200584 int8_t boolean; /**< 0 as false, 1 as true */
585 int64_t dec64; /**< decimal64: value = dec64 / 10^fraction-digits */
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200586 int8_t int8; /**< 8-bit signed integer */
587 int16_t int16; /**< 16-bit signed integer */
588 int32_t int32; /**< 32-bit signed integer */
589 int64_t int64; /**< 64-bit signed integer */
590 uint8_t uint8; /**< 8-bit unsigned integer */
Michal Vasko7c8439f2020-08-05 13:25:19 +0200591 uint16_t uint16; /**< 16-bit unsigned integer */
592 uint32_t uint32; /**< 32-bit unsigned integer */
593 uint64_t uint64; /**< 64-bit unsigned integer */
Radek Krejcie7b95092019-05-15 11:03:07 +0200594 struct lysc_type_bitenum_item *enum_item; /**< pointer to the definition of the enumeration value */
595 struct lysc_ident *ident; /**< pointer to the schema definition of the identityref value */
Michal Vaskobb22b182021-06-14 08:14:21 +0200596 struct ly_path *target; /**< Instance-identifier target path, use ::lyd_find_target() to evaluate
597 it on data. */
Michal Vasko3ce79712021-05-04 11:44:20 +0200598 struct lyd_value_union *subvalue; /** Union value with some metadata. */
Michal Vaskoaa0ee622021-05-11 09:29:25 +0200599
600 void *dyn_mem; /**< pointer to generic data type value stored in dynamic memory */
601 uint8_t fixed_mem[LYD_VALUE_FIXED_MEM_SIZE]; /**< fixed-size buffer for a generic data type value */
Radek Krejci8678fa42020-08-18 16:07:28 +0200602 }; /**< The union is just a list of shorthands to possible values stored by a type's plugin. libyang itself uses the ::lyd_value.realtype
603 plugin's callbacks to work with the data.*/
Radek Krejcie7b95092019-05-15 11:03:07 +0200604};
605
606/**
Michal Vaskoaa0ee622021-05-11 09:29:25 +0200607 * @brief Get the value in format specific to the type.
608 *
609 * Should be used for any types that do not have their specific representation in the ::lyd_value union.
610 *
611 * @param[in] value Pointer to the value structure to read from (struct ::lyd_value *).
612 * @param[out] type_val Pointer to the type-specific value structure.
613 */
614#define LYD_VALUE_GET(value, type_val) \
615 ((sizeof *(type_val) > LYD_VALUE_FIXED_MEM_SIZE) \
616 ? ((type_val) = (((value)->dyn_mem))) \
617 : ((type_val) = ((void *)((value)->fixed_mem))))
618
619/**
Michal Vasko2b421d92021-05-18 16:33:36 +0200620 * @brief Special lyd_value structure for built-in union values.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200621 *
Michal Vasko3ce79712021-05-04 11:44:20 +0200622 * Represents data with multiple types (union). The ::lyd_value_union.value contains representation according to
623 * one of the union's types. The ::lyd_value_union.prefix_data provides (possible) mappings from prefixes in
Michal Vasko495f4502021-04-27 14:48:05 +0200624 * the original value to YANG modules. These prefixes are necessary to parse original value to the union's subtypes.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200625 */
Michal Vasko3ce79712021-05-04 11:44:20 +0200626struct lyd_value_union {
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200627 struct lyd_value value; /**< representation of the value according to the selected union's subtype
Michal Vasko3ce79712021-05-04 11:44:20 +0200628 (stored as ::lyd_value.realtype here) */
629 void *original; /**< Original value. */
630 size_t orig_len; /**< Original value length. */
Michal Vaskod0c3bac2021-05-11 09:44:43 +0200631 uint32_t hints; /**< [Value hints](@ref lydvalhints) from the parser */
Radek Krejci8df109d2021-04-23 12:19:08 +0200632 LY_VALUE_FORMAT format; /**< Prefix format of the value. However, this information is also used to decide
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200633 whether a value is valid for the specific format or not on later validations
634 (instance-identifier in XML looks different than in JSON). */
Radek Krejci0b013302021-03-29 15:22:32 +0200635 void *prefix_data; /**< Format-specific data for prefix resolution (see ly_resolve_prefix()) */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200636 const struct lysc_node *ctx_node; /**< Context schema node. */
637};
638
639/**
Michal Vasko2b421d92021-05-18 16:33:36 +0200640 * @brief Special lyd_value structure for built-in bits values.
Michal Vasko2724b922021-04-28 13:46:31 +0200641 */
642struct lyd_value_bits {
643 char *bitmap; /**< bitmap of size ::lyplg_type_bits_bitmap_size(), if its value is
644 cast to an integer type of the corresponding size, can be used
645 directly as a bitmap */
646 struct lysc_type_bitenum_item **items; /**< list of set pointers to the specification of the set
647 bits ([sized array](@ref sizedarrays)) */
648};
649
650/**
Michal Vasko2b421d92021-05-18 16:33:36 +0200651 * @brief Special lyd_value structure for built-in binary values.
Michal Vasko495f4502021-04-27 14:48:05 +0200652 */
653struct lyd_value_binary {
Michal Vasko74515d02021-06-11 11:13:11 +0200654 void *data; /**< pointer to the binary value */
655 size_t size; /**< size of @p data value in bytes */
Michal Vasko495f4502021-04-27 14:48:05 +0200656};
657
658/**
Michal Vasko2b421d92021-05-18 16:33:36 +0200659 * @brief Special lyd_value structure for ietf-inet-types ipv4-address-no-zone values.
660 */
661struct lyd_value_ipv4_address_no_zone {
662 struct in_addr addr; /**< IPv4 address in binary */
663};
664
665/**
666 * @brief Special lyd_value structure for ietf-inet-types ipv4-address values.
667 */
668struct lyd_value_ipv4_address {
669 struct in_addr addr; /**< IPv4 address in binary */
670 const char *zone; /**< Optional address zone */
671};
672
673/**
674 * @brief Special lyd_value structure for ietf-inet-types ipv4-prefix values.
675 */
676struct lyd_value_ipv4_prefix {
677 struct in_addr addr; /**< IPv4 host address in binary */
678 uint8_t prefix; /**< prefix length (0 - 32) */
679};
680
681/**
682 * @brief Special lyd_value structure for ietf-inet-types ipv6-address-no-zone values.
683 */
684struct lyd_value_ipv6_address_no_zone {
685 struct in6_addr addr; /**< IPv6 address in binary */
686};
687
688/**
689 * @brief Special lyd_value structure for ietf-inet-types ipv6-address values.
690 */
691struct lyd_value_ipv6_address {
692 struct in6_addr addr; /**< IPv6 address in binary */
693 const char *zone; /**< Optional address zone */
694};
695
696/**
697 * @brief Special lyd_value structure for ietf-inet-types ipv6-prefix values.
698 */
699struct lyd_value_ipv6_prefix {
700 struct in6_addr addr; /**< IPv6 host address in binary */
701 uint8_t prefix; /**< prefix length (0 - 128) */
702};
703
704/**
705 * @brief Special lyd_value structure for ietf-yang-types date-and-time values.
706 */
707struct lyd_value_date_and_time {
708 time_t time; /**< UNIX timestamp */
709 char *fractions_s; /**< Optional fractions of a second */
Michal Vaskoc2dabc32021-11-22 14:01:41 +0100710 ly_bool unknown_tz; /**< Whether the value is in the special -00:00 timezone. */
Michal Vasko2b421d92021-05-18 16:33:36 +0200711};
712
713/**
Michal Vaskoddd76592022-01-17 13:34:48 +0100714 * @brief Special lyd_value structure for ietf-yang-types xpath1.0 values.
715 */
716struct lyd_value_xpath10 {
717 struct lyxp_expr *exp;
718 const struct ly_ctx *ctx;
719 void *prefix_data;
720 LY_VALUE_FORMAT format;
721};
722
723/**
aPiecek6cf1d162023-11-08 16:07:00 +0100724 * @brief Special lyd_value structure for lyds tree value.
725 */
726struct lyd_value_lyds_tree {
727 struct rb_node *rbt; /**< Root of the Red-black tree. */
728};
729
730/**
Michal Vasko52927e22020-03-16 17:26:14 +0100731 * @brief Generic prefix and namespace mapping, meaning depends on the format.
Radek Krejci1798aae2020-07-14 13:26:06 +0200732 *
733 * 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 +0200734 * ::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 +0100735 * 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 +0100736 */
Michal Vaskoad92b672020-11-12 13:11:31 +0100737struct ly_opaq_name {
738 const char *name; /**< node name, without prefix if any was defined */
739 const char *prefix; /**< identifier used in the qualified name as the prefix, can be NULL */
Michal Vasko26bbb272022-08-02 14:54:33 +0200740
Radek Krejci1798aae2020-07-14 13:26:06 +0200741 union {
Radek Krejci8df109d2021-04-23 12:19:08 +0200742 const char *module_ns; /**< format ::LY_VALUE_XML - XML namespace of the node element */
743 const char *module_name; /**< format ::LY_VALUE_JSON - (inherited) name of the module of the element */
Radek Krejci1798aae2020-07-14 13:26:06 +0200744 };
Michal Vasko52927e22020-03-16 17:26:14 +0100745};
746
747/**
748 * @brief Generic attribute structure.
749 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200750struct lyd_attr {
Michal Vasko52927e22020-03-16 17:26:14 +0100751 struct lyd_node_opaq *parent; /**< data node where the attribute is placed */
Michal Vasko6b5cb2a2020-11-11 19:11:21 +0100752 struct lyd_attr *next; /**< pointer to the next attribute */
Michal Vaskoad92b672020-11-12 13:11:31 +0100753 struct ly_opaq_name name; /**< attribute name with module information */
Michal Vasko501af032020-11-11 20:27:44 +0100754 const char *value; /**< attribute value */
Michal Vaskod0c3bac2021-05-11 09:44:43 +0200755 uint32_t hints; /**< additional information about from the data source, see the [hints list](@ref lydhints) */
Michal Vaskoddd76592022-01-17 13:34:48 +0100756 LY_VALUE_FORMAT format; /**< format of the attribute and any prefixes, ::LY_VALUE_XML or ::LY_VALUE_JSON */
Radek Krejciec9ad602021-01-04 10:46:30 +0100757 void *val_prefix_data; /**< format-specific prefix data */
Michal Vasko52927e22020-03-16 17:26:14 +0100758};
Radek Krejcie7b95092019-05-15 11:03:07 +0200759
Michal Vasko1bf09392020-03-27 12:38:10 +0100760#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 +0200761#define LYD_NODE_TERM (LYS_LEAF|LYS_LEAFLIST) /**< Schema nodetype mask for lyd_node_term */
762#define LYD_NODE_ANY (LYS_ANYDATA) /**< Schema nodetype mask for lyd_node_any */
763
764/**
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200765 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200766 * @defgroup dnodeflags Data node flags
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200767 * @{
768 *
769 * Various flags of data nodes.
770 *
771 * 1 - container 5 - anydata/anyxml
772 * 2 - list 6 - rpc/action
773 * 3 - leaf 7 - notification
774 * 4 - leaflist
775 *
776 * bit name 1 2 3 4 5 6 7
777 * ---------------------+-+-+-+-+-+-+-+
778 * 1 LYD_DEFAULT |x| |x|x| | | |
779 * +-+-+-+-+-+-+-+
Michal Vasko5c4e5892019-11-14 12:31:38 +0100780 * 2 LYD_WHEN_TRUE |x|x|x|x|x| | |
Michal Vasko9b368d32020-02-14 13:53:31 +0100781 * +-+-+-+-+-+-+-+
782 * 3 LYD_NEW |x|x|x|x|x|x|x|
Michal Vaskoa65c72c2022-02-17 16:20:18 +0100783 * +-+-+-+-+-+-+-+
784 * 4 LYD_EXT |x|x|x|x|x|x|x|
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200785 * ---------------------+-+-+-+-+-+-+-+
786 *
787 */
788
Michal Vaskoddd76592022-01-17 13:34:48 +0100789#define LYD_DEFAULT 0x01 /**< default (implicit) node */
790#define LYD_WHEN_TRUE 0x02 /**< all when conditions of this node were evaluated to true */
791#define LYD_NEW 0x04 /**< node was created after the last validation, is needed for the next validation */
792#define LYD_EXT 0x08 /**< node is the first sibling parsed as extension instance data */
Michal Vasko52927e22020-03-16 17:26:14 +0100793
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200794/** @} */
795
796/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200797 * @brief Generic structure for a data node.
798 */
799struct lyd_node {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200800 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
801 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
802 used to get know that nodes are not equal, it cannot be used to decide that the
803 nodes are equal due to possible collisions. */
804 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejci2a9fc652021-01-22 17:44:34 +0100805 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200806 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
807 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
808 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
809 never NULL. If there is no sibling node, pointer points to the node
810 itself. In case of the first node, this pointer points to the last
811 node in the list. */
Michal Vasko9f96a052020-03-10 09:41:45 +0100812 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200813 void *priv; /**< private user data, not used by libyang */
Radek Krejcie7b95092019-05-15 11:03:07 +0200814};
815
816/**
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200817 * @brief Data node structure for the inner data tree nodes - containers, lists, RPCs, actions and Notifications.
Radek Krejcie7b95092019-05-15 11:03:07 +0200818 */
819struct lyd_node_inner {
Michal Vasko9e685082021-01-29 14:49:09 +0100820 union {
821 struct lyd_node node; /**< implicit cast for the members compatible with ::lyd_node */
Michal Vasko26bbb272022-08-02 14:54:33 +0200822
Michal Vasko9e685082021-01-29 14:49:09 +0100823 struct {
824 uint32_t hash; /**< hash of this particular node (module name + schema name + key string
825 values if list or hashes of all nodes of subtree in case of keyless
826 list). Note that while hash can be used to get know that nodes are
827 not equal, it cannot be used to decide that the nodes are equal due
828 to possible collisions. */
829 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
830 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
831 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
832 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
833 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
834 never NULL. If there is no sibling node, pointer points to the node
835 itself. In case of the first node, this pointer points to the last
836 node in the list. */
837 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
838 void *priv; /**< private user data, not used by libyang */
839 };
840 }; /**< common part corresponding to ::lyd_node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200841
842 struct lyd_node *child; /**< pointer to the first child node. */
Michal Vasko8efac242023-03-30 08:24:56 +0200843 struct ly_ht *children_ht; /**< hash table with all the direct children (except keys for a list, lists without keys) */
Michal Vasko26bbb272022-08-02 14:54:33 +0200844
Radek Krejci8678fa42020-08-18 16:07:28 +0200845#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 +0200846};
847
848/**
Michal Vaskof03ed032020-03-04 13:31:44 +0100849 * @brief Data node structure for the terminal data tree nodes - leaves and leaf-lists.
Radek Krejcie7b95092019-05-15 11:03:07 +0200850 */
851struct lyd_node_term {
Michal Vasko9e685082021-01-29 14:49:09 +0100852 union {
853 struct lyd_node node; /**< implicit cast for the members compatible with ::lyd_node */
Michal Vasko26bbb272022-08-02 14:54:33 +0200854
Michal Vasko9e685082021-01-29 14:49:09 +0100855 struct {
856 uint32_t hash; /**< hash of this particular node (module name + schema name + key string
857 values if list or hashes of all nodes of subtree in case of keyless
858 list). Note that while hash can be used to get know that nodes are
859 not equal, it cannot be used to decide that the nodes are equal due
860 to possible collisions. */
861 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
862 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
863 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
864 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
865 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
866 never NULL. If there is no sibling node, pointer points to the node
867 itself. In case of the first node, this pointer points to the last
868 node in the list. */
869 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
870 void *priv; /**< private user data, not used by libyang */
871 };
872 }; /**< common part corresponding to ::lyd_node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200873
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200874 struct lyd_value value; /**< node's value representation */
Radek Krejcie7b95092019-05-15 11:03:07 +0200875};
876
877/**
Christian Hopps61213e02021-04-12 20:41:32 -0400878 * @brief union for anydata/anyxml value representation.
879 */
880union lyd_any_value {
881 struct lyd_node *tree; /**< data tree */
882 const char *str; /**< Generic string data */
883 const char *xml; /**< Serialized XML data */
884 const char *json; /**< I-JSON encoded string */
885 char *mem; /**< LYD_ANYDATA_LYB memory chunk */
886};
887
888/**
889 * @brief Data node structure for the anydata data tree nodes - anydata or
890 * anyxml.
Radek Krejcie7b95092019-05-15 11:03:07 +0200891 */
892struct lyd_node_any {
Michal Vasko9e685082021-01-29 14:49:09 +0100893 union {
894 struct lyd_node node; /**< implicit cast for the members compatible with ::lyd_node */
Michal Vasko26bbb272022-08-02 14:54:33 +0200895
Michal Vasko9e685082021-01-29 14:49:09 +0100896 struct {
897 uint32_t hash; /**< hash of this particular node (module name + schema name + key string
898 values if list or hashes of all nodes of subtree in case of keyless
899 list). Note that while hash can be used to get know that nodes are
900 not equal, it cannot be used to decide that the nodes are equal due
901 to possible collisions. */
902 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
903 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
904 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
905 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
906 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
907 never NULL. If there is no sibling node, pointer points to the node
908 itself. In case of the first node, this pointer points to the last
909 node in the list. */
910 struct lyd_meta *meta; /**< pointer to the list of metadata of this node */
911 void *priv; /**< private user data, not used by libyang */
912 };
913 }; /**< common part corresponding to ::lyd_node */
Radek Krejcie7b95092019-05-15 11:03:07 +0200914
Christian Hopps61213e02021-04-12 20:41:32 -0400915 union lyd_any_value value; /**< pointer to the stored value representation of the anydata/anyxml node */
Michal Vasko9e685082021-01-29 14:49:09 +0100916 LYD_ANYDATA_VALUETYPE value_type; /**< type of the data stored as ::lyd_node_any.value */
Radek Krejcie7b95092019-05-15 11:03:07 +0200917};
918
919/**
Michal Vasko1d4af6c2021-02-22 13:31:26 +0100920 * @brief Get the name (associated with) of a data node. Works for opaque nodes as well.
921 *
922 * @param[in] node Node to examine.
923 * @return Data node name.
924 */
925#define LYD_NAME(node) ((node)->schema ? (node)->schema->name : ((struct lyd_node_opaq *)node)->name.name)
926
927/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200928 * @ingroup datatree
929 * @defgroup lydvalhints Value format hints.
Radek Krejci1798aae2020-07-14 13:26:06 +0200930 * @{
Radek Krejci8678fa42020-08-18 16:07:28 +0200931 *
932 * Hints for the type of the data value.
933 *
934 * Any information about value types encoded in the format is hinted by these values.
Radek Krejci1798aae2020-07-14 13:26:06 +0200935 */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200936#define LYD_VALHINT_STRING 0x0001 /**< value is allowed to be a string */
937#define LYD_VALHINT_DECNUM 0x0002 /**< value is allowed to be a decimal number */
938#define LYD_VALHINT_OCTNUM 0x0004 /**< value is allowed to be an octal number */
939#define LYD_VALHINT_HEXNUM 0x0008 /**< value is allowed to be a hexadecimal number */
940#define LYD_VALHINT_NUM64 0x0010 /**< value is allowed to be an int64 or uint64 */
941#define LYD_VALHINT_BOOLEAN 0x0020 /**< value is allowed to be a boolean */
942#define LYD_VALHINT_EMPTY 0x0040 /**< value is allowed to be empty */
943/**
944 * @} lydvalhints
945 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200946
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200947/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200948 * @ingroup datatree
949 * @defgroup lydnodehints Node type format hints
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200950 * @{
Radek Krejci8678fa42020-08-18 16:07:28 +0200951 *
952 * Hints for the type of the data node.
953 *
954 * Any information about node types encoded in the format is hinted by these values.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200955 */
956#define LYD_NODEHINT_LIST 0x0080 /**< node is allowed to be a list instance */
957#define LYD_NODEHINT_LEAFLIST 0x0100 /**< node is allowed to be a leaf-list instance */
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200958/**
959 * @} lydnodehints
960 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200961
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200962/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200963 * @ingroup datatree
964 * @defgroup lydhints Value and node type format hints
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200965 * @{
Radek Krejci8678fa42020-08-18 16:07:28 +0200966 *
967 * Hints for the types of data node and its value.
968 *
969 * Any information about value and node types encoded in the format is hinted by these values.
970 * It combines [value hints](@ref lydvalhints) and [node hints](@ref lydnodehints).
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200971 */
972#define LYD_HINT_DATA 0x01F3 /**< special node/value hint to be used for generic data node/value (for cases when
973 there is no encoding or it does not provide any additional information about
974 a node/value type); do not combine with specific [value hints](@ref lydvalhints)
975 or [node hints](@ref lydnodehints). */
976#define LYD_HINT_SCHEMA 0x01FF /**< special node/value hint to be used for generic schema node/value(for cases when
977 there is no encoding or it does not provide any additional information about
978 a node/value type); do not combine with specific [value hints](@ref lydvalhints)
979 or [node hints](@ref lydnodehints). */
980/**
981 * @} lydhints
982 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200983
984/**
Michal Vasko52927e22020-03-16 17:26:14 +0100985 * @brief Data node structure for unparsed (opaque) nodes.
986 */
987struct lyd_node_opaq {
Michal Vasko9e685082021-01-29 14:49:09 +0100988 union {
989 struct lyd_node node; /**< implicit cast for the members compatible with ::lyd_node */
Michal Vasko26bbb272022-08-02 14:54:33 +0200990
Michal Vasko9e685082021-01-29 14:49:09 +0100991 struct {
992 uint32_t hash; /**< always 0 */
993 uint32_t flags; /**< always 0 */
994 const struct lysc_node *schema; /**< always NULL */
995 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
996 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
997 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
998 never NULL. If there is no sibling node, pointer points to the node
999 itself. In case of the first node, this pointer points to the last
1000 node in the list. */
1001 struct lyd_meta *meta; /**< always NULL */
1002 void *priv; /**< private user data, not used by libyang */
1003 };
1004 }; /**< common part corresponding to ::lyd_node */
Michal Vasko52927e22020-03-16 17:26:14 +01001005
Michal Vasko501af032020-11-11 20:27:44 +01001006 struct lyd_node *child; /**< pointer to the child node (compatible with ::lyd_node_inner) */
1007
Michal Vaskoad92b672020-11-12 13:11:31 +01001008 struct ly_opaq_name name; /**< node name with module information */
Michal Vasko52927e22020-03-16 17:26:14 +01001009 const char *value; /**< original value */
Michal Vaskod0c3bac2021-05-11 09:44:43 +02001010 uint32_t hints; /**< additional information about from the data source, see the [hints list](@ref lydhints) */
Radek Krejci8df109d2021-04-23 12:19:08 +02001011 LY_VALUE_FORMAT format; /**< format of the node and any prefixes, ::LY_VALUE_XML or ::LY_VALUE_JSON */
Radek Krejciec9ad602021-01-04 10:46:30 +01001012 void *val_prefix_data; /**< format-specific prefix data */
Michal Vasko501af032020-11-11 20:27:44 +01001013
Michal Vasko9e685082021-01-29 14:49:09 +01001014 struct lyd_attr *attr; /**< pointer to the list of generic attributes of this node */
Michal Vasko52927e22020-03-16 17:26:14 +01001015 const struct ly_ctx *ctx; /**< libyang context */
1016};
1017
1018/**
stewegf9041a22024-01-18 13:29:12 +01001019 * @brief Structure of leafref links record.
1020 */
1021struct lyd_leafref_links_rec {
1022 const struct lyd_node_term *node; /** pointer to the data node itself */
1023 const struct lyd_node_term **leafref_nodes; /** list of the leafref pointing to this data node [sized array](@ref sizedarrays)),
1024 By default it is empty. It is filled automatically by validation function of
1025 leafref nodes, which are valid and are not using 'require-instance false;'.
1026 It can also be populated based on manual request using
1027 [link api](@ref lyd_leafref_link_node_tree). Freeing of the resources is
1028 automatic. */
steweg67388952024-01-25 12:14:50 +01001029 const struct lyd_node_term **target_nodes; /** list of leafref target data nodes [sized array](@ref sizedarrays)). Byt default
1030 it is empty. The logic is the same as for [leafref_nodes](@ref leafref_nodes) and
1031 is filled only for leafrefs */
stewegf9041a22024-01-18 13:29:12 +01001032};
1033
1034/**
Radek Krejcia1c1e542020-09-29 16:06:52 +02001035 * @brief Get the generic parent pointer of a data node.
1036 *
1037 * @param[in] node Node whose parent pointer to get.
1038 * @return Pointer to the parent node of the @p node.
1039 * @return NULL in case of the top-level node or if the @p node is NULL itself.
Michal Vasko5bfd4be2020-06-23 13:26:19 +02001040 */
Michal Vasko4e947032024-01-22 12:17:51 +01001041static inline struct lyd_node *
1042lyd_parent(const struct lyd_node *node)
1043{
1044 return (node && node->parent) ? &node->parent->node : NULL;
1045}
Michal Vasko5bfd4be2020-06-23 13:26:19 +02001046
1047/**
Radek Krejcia1c1e542020-09-29 16:06:52 +02001048 * @brief Get the child pointer of a generic data node.
Radek Krejcie7b95092019-05-15 11:03:07 +02001049 *
Radek Krejcia1c1e542020-09-29 16:06:52 +02001050 * Decides the node's type and in case it has a children list, returns it. Supports even the opaq nodes (::lyd_node_opaq).
1051 *
1052 * If you need to skip key children, use ::lyd_child_no_keys().
1053 *
1054 * @param[in] node Node to use.
1055 * @return Pointer to the first child node (if any) of the @p node.
Radek Krejcie7b95092019-05-15 11:03:07 +02001056 */
Michal Vasko4e947032024-01-22 12:17:51 +01001057static inline struct lyd_node *
1058lyd_child(const struct lyd_node *node)
1059{
1060 if (!node) {
1061 return NULL;
1062 }
1063
1064 if (!node->schema) {
1065 /* opaq node */
1066 return ((const struct lyd_node_opaq *)node)->child;
1067 }
1068
1069 if (node->schema->nodetype & (LYS_CONTAINER | LYS_LIST | LYS_RPC | LYS_ACTION | LYS_NOTIF)) {
1070 return ((const struct lyd_node_inner *)node)->child;
1071 }
1072
1073 return NULL;
1074}
Radek Krejcia1c1e542020-09-29 16:06:52 +02001075
1076/**
1077 * @brief Get the child pointer of a generic data node but skip its keys in case it is ::LYS_LIST.
1078 *
1079 * Decides the node's type and in case it has a children list, returns it. Supports even the opaq nodes (::lyd_node_opaq).
1080 *
1081 * If you need to take key children into account, use ::lyd_child().
1082 *
1083 * @param[in] node Node to use.
1084 * @return Pointer to the first child node (if any) of the @p node.
1085 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001086LIBYANG_API_DECL struct lyd_node *lyd_child_no_keys(const struct lyd_node *node);
Radek Krejcie7b95092019-05-15 11:03:07 +02001087
1088/**
Michal Vaskoc193ce92020-03-06 11:04:48 +01001089 * @brief Get the owner module of the data node. It is the module of the top-level schema node. Generally,
1090 * in case of augments it is the target module, recursively, otherwise it is the module where the data node is defined.
1091 *
Michal Vaskofcdf3012020-11-23 16:57:03 +01001092 * Also works for opaque nodes, if it is possible to resolve the module.
1093 *
Michal Vaskoc193ce92020-03-06 11:04:48 +01001094 * @param[in] node Data node to examine.
1095 * @return Module owner of the node.
1096 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001097LIBYANG_API_DECL const struct lys_module *lyd_owner_module(const struct lyd_node *node);
Michal Vaskoc193ce92020-03-06 11:04:48 +01001098
1099/**
Michal Vasko420cc252023-08-24 08:14:24 +02001100 * @brief Get the module of a node. Useful mainly for opaque nodes.
1101 *
1102 * @param[in] node Node to examine.
1103 * @return Module of the node.
1104 */
1105LIBYANG_API_DECL const struct lys_module *lyd_node_module(const struct lyd_node *node);
1106
1107/**
Radek Krejci19611252020-10-04 13:54:53 +02001108 * @brief Check whether a node value equals to its default one.
1109 *
1110 * @param[in] node Term node to test.
1111 * @return false (no, it is not a default node) or true (yes, it is default)
1112 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001113LIBYANG_API_DECL ly_bool lyd_is_default(const struct lyd_node *node);
Radek Krejci19611252020-10-04 13:54:53 +02001114
1115/**
Radek Krejcica989142020-11-05 11:32:22 +01001116 * @brief Learn the relative position of a list or leaf-list instance within other instances of the same schema node.
1117 *
1118 * @param[in] instance List or leaf-list instance to get the position of.
Michal Vaskoe78faec2021-04-08 17:24:43 +02001119 * @return 0 on error.
1120 * @return Positive integer of the @p instance position.
Radek Krejcica989142020-11-05 11:32:22 +01001121 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001122LIBYANG_API_DECL uint32_t lyd_list_pos(const struct lyd_node *instance);
Radek Krejcica989142020-11-05 11:32:22 +01001123
1124/**
Radek Krejci4233f9b2020-11-05 12:38:35 +01001125 * @brief Get the first sibling of the given node.
1126 *
1127 * @param[in] node Node which first sibling is going to be the result.
1128 * @return The first sibling of the given node or the node itself if it is the first child of the parent.
1129 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001130LIBYANG_API_DECL struct lyd_node *lyd_first_sibling(const struct lyd_node *node);
Radek Krejci4233f9b2020-11-05 12:38:35 +01001131
1132/**
Michal Vasko60ea6352020-06-29 13:39:39 +02001133 * @brief Learn the length of LYB data.
1134 *
1135 * @param[in] data LYB data to examine.
1136 * @return Length of the LYB data chunk,
1137 * @return -1 on error.
1138 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001139LIBYANG_API_DECL int lyd_lyb_data_length(const char *data);
Michal Vasko60ea6352020-06-29 13:39:39 +02001140
1141/**
Michal Vaskobfff6ac2022-02-23 16:22:53 +01001142 * @brief Check node parsed into an opaque node for the reason (error) why it could not be parsed as data node.
1143 *
1144 * The node is expected to be produced by a parser and must either have no parent or a data node parent (not opaque).
1145 *
1146 * @param[in] node Opaque node to check.
1147 * @return LY_EINVAL if @p node is in some way unexpected (even valid);
1148 * @return LY_ERR value of the reason.
1149 */
1150LIBYANG_API_DECL LY_ERR lyd_parse_opaq_error(const struct lyd_node *node);
1151
1152/**
Christian Hopps46bd21b2021-04-27 09:43:58 -04001153 * @brief Get the (canonical) value of a lyd_value.
1154 *
Michal Vasko33876022021-04-27 16:42:24 +02001155 * Whenever possible, ::lyd_get_value() or ::lyd_get_meta_value() should be used instead.
1156 *
Christian Hopps46bd21b2021-04-27 09:43:58 -04001157 * @param[in] ctx Context for the value
Michal Vasko33876022021-04-27 16:42:24 +02001158 * @param[in] value Value structure to use.
Christian Hopps46bd21b2021-04-27 09:43:58 -04001159 * @return Canonical value.
1160 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001161LIBYANG_API_DECL const char *lyd_value_get_canonical(const struct ly_ctx *ctx, const struct lyd_value *value);
Christian Hopps46bd21b2021-04-27 09:43:58 -04001162
1163/**
Radek Krejci6d5ba0c2021-04-26 07:49:59 +02001164 * @brief Get the (canonical) value of a data node.
1165 *
1166 * @param[in] node Data node to use.
1167 * @return Canonical value.
1168 */
Michal Vasko4e947032024-01-22 12:17:51 +01001169static inline const char *
1170lyd_get_value(const struct lyd_node *node)
1171{
1172 if (!node) {
1173 return NULL;
1174 }
1175
1176 if (!node->schema) {
1177 return ((const struct lyd_node_opaq *)node)->value;
1178 } else if (node->schema->nodetype & LYD_NODE_TERM) {
1179 const struct lyd_value *value = &((const struct lyd_node_term *)node)->value;
1180
1181 return value->_canonical ? value->_canonical : lyd_value_get_canonical(LYD_CTX(node), value);
1182 }
1183
1184 return NULL;
1185}
Radek Krejci6d5ba0c2021-04-26 07:49:59 +02001186
1187/**
Michal Vaskoa820c312021-02-05 16:33:00 +01001188 * @brief Get anydata string value.
1189 *
1190 * @param[in] any Anyxml/anydata node to read from.
1191 * @param[out] value_str String representation of the value.
1192 * @return LY_ERR value.
1193 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001194LIBYANG_API_DECL LY_ERR lyd_any_value_str(const struct lyd_node *any, char **value_str);
Michal Vaskoa820c312021-02-05 16:33:00 +01001195
1196/**
Michal Vaskoc0004272020-08-06 08:32:34 +02001197 * @brief Copy anydata value from one node to another. Target value is freed first.
1198 *
1199 * @param[in,out] trg Target node.
1200 * @param[in] value Source value, may be NULL when the target value is only freed.
1201 * @param[in] value_type Source value type.
1202 * @return LY_ERR value.
1203 */
Michal Vasko55896172022-02-17 10:47:21 +01001204LIBYANG_API_DECL LY_ERR lyd_any_copy_value(struct lyd_node *trg, const union lyd_any_value *value,
1205 LYD_ANYDATA_VALUETYPE value_type);
Michal Vaskoc0004272020-08-06 08:32:34 +02001206
1207/**
Michal Vasko21c11c22023-10-09 16:06:58 +02001208 * @brief Get schema node of a data node. Useful especially for opaque nodes.
1209 *
1210 * @param[in] node Data node to use.
1211 * @return Schema node represented by data @p node, NULL if there is none.
1212 */
Michal Vasko7e4a6c72023-10-09 16:23:40 +02001213LIBYANG_API_DECL const struct lysc_node *lyd_node_schema(const struct lyd_node *node);
Michal Vasko21c11c22023-10-09 16:06:58 +02001214
1215/**
Michal Vasko00cbf532020-06-15 13:58:47 +02001216 * @brief Create a new inner node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +01001217 *
Radek Krejcidd2a7662021-03-12 11:26:34 +01001218 * To create list, use ::lyd_new_list() or ::lyd_new_list2().
1219 *
1220 * To create a top-level inner node defined in an extension instance, use ::lyd_new_ext_inner().
1221 *
Michal Vasko013a8182020-03-03 10:46:53 +01001222 * @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 +01001223 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +01001224 * @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 +01001225 * @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
1226 * taken into consideration. Otherwise, the output's data node is going to be created.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001227 * @param[out] node Optional created node.
1228 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +01001229 */
Michal Vasko55896172022-02-17 10:47:21 +01001230LIBYANG_API_DECL LY_ERR lyd_new_inner(struct lyd_node *parent, const struct lys_module *module, const char *name,
1231 ly_bool output, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +01001232
1233/**
Radek Krejcidd2a7662021-03-12 11:26:34 +01001234 * @brief Create a new top-level inner node defined in the given extension instance.
1235 *
1236 * To create list, use ::lyd_new_list() or ::lyd_new_list2().
1237 *
1238 * To create an inner node with parent (no matter if defined inside extension instance or a standard tree) or a top-level
1239 * node of a standard module's tree, use ::lyd_new_inner().
1240 *
1241 * @param[in] ext Extension instance where the inner node being created is defined.
1242 * @param[in] name Schema node name of the new data node. The node can be #LYS_CONTAINER, #LYS_NOTIF, #LYS_RPC, or #LYS_ACTION.
1243 * @param[out] node The created node.
1244 * @return LY_ERR value.
1245 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001246LIBYANG_API_DECL LY_ERR lyd_new_ext_inner(const struct lysc_ext_instance *ext, const char *name, struct lyd_node **node);
Radek Krejcidd2a7662021-03-12 11:26:34 +01001247
1248/**
stewegd4cde642024-02-21 08:34:16 +01001249 * @ingroup datatree
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001250 * @defgroup newvaloptions New value creation options
stewegd4cde642024-02-21 08:34:16 +01001251 *
1252 * Various options to change lyd_new_*() behavior. The LYD_NEW_VAL* can be used within any API, others
1253 * are API specific
1254 *
1255 * Default behavior:
1256 * - the input data nodes or RPC/Action is taken into account
1257 * - the value is being validated with all possible validations, which doesn't require existence of any other data nodes
1258 * - the input value is expected to be in JSON format
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001259 * - RPC output schema children are completely ignored in all modules. Input is searched and nodes created normally.
1260 *
1261 * Default behavior specific for lyd_new_path*() functions:
stewegd4cde642024-02-21 08:34:16 +01001262 * - if the target node already exists (and is not default), an error is returned.
1263 * - the whole path to the target node is created (with any missing parents) if necessary.
stewegd4cde642024-02-21 08:34:16 +01001264 * - during creation of new metadata, the nodes will have default flag set
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001265 * - string value is copied and stored internally during any node creation
stewegd4cde642024-02-21 08:34:16 +01001266 * @{
1267 */
1268
1269#define LYD_NEW_VAL_OUTPUT 0x01 /**< Flag in case the @p parent is RPC/Action. If value is 0, the input's data nodes of the RPC/Action are
1270 taken into consideration. Otherwise, the output's data node is going to be created. */
1271#define LYD_NEW_VAL_STORE_ONLY 0x02 /**< Whether to perform only storing operation with no or minimum valitions */
Michal Vasko6a027db2024-02-21 09:55:34 +01001272#define LYD_NEW_VAL_BIN 0x04 /**< Interpret the provided leaf/leaf-list @p value as being in the binary
stewegd4cde642024-02-21 08:34:16 +01001273 ::LY_VALUE_LYB format, to learn what exactly is expected see @ref howtoDataLYB. */
Michal Vasko6a027db2024-02-21 09:55:34 +01001274#define LYD_NEW_VAL_CANON 0x08 /**< Interpret the provided leaf/leaf-list @p value as being in the canonical
stewegd4cde642024-02-21 08:34:16 +01001275 (or JSON if no defined) ::LY_VALUE_CANON format. If it is not, it may lead
1276 to unexpected behavior. */
1277#define LYD_NEW_META_CLEAR_DFLT 0x10 /**< Whether to clear the default flag starting from @p parent, recursively all NP containers. */
1278#define LYD_NEW_PATH_UPDATE 0x20 /**< If the target node exists, is a leaf, and it is updated with a new value or its
1279 default flag is changed, it is returned. If the target node exists and is not
1280 a leaf or generally no change occurs in the @p parent tree, NULL is returned and
1281 no error set. */
1282#define LYD_NEW_PATH_OPAQ 0x40 /**< Enables the creation of opaque nodes with some specific rules. If the __last node__
1283 in the path is not uniquely defined ((leaf-)list without a predicate) or has an
1284 invalid value (leaf/leaf-list), it is created as opaque. */
1285#define LYD_NEW_PATH_WITH_OPAQ 0x80 /**< Consider opaque nodes normally when searching for existing nodes. */
1286#define LYD_NEW_ANY_USE_VALUE 0x100 /**< Whether to use dynamic @p value or make a copy. */
1287
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001288/** @} newvaloptions */
stewegd4cde642024-02-21 08:34:16 +01001289
1290/**
Michal Vasko00cbf532020-06-15 13:58:47 +02001291 * @brief Create a new list node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +01001292 *
1293 * @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 +01001294 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +01001295 * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001296 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001297 * @param[out] node Optional created node.
Michal Vasko013a8182020-03-03 10:46:53 +01001298 * @param[in] ... Ordered key values of the new list instance, all must be set. In case of an instance-identifier
stewegd4cde642024-02-21 08:34:16 +01001299 * or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for key-less lists.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001300 * In case options include ::LYD_NEW_VAL_BIN, every key value must be followed by its length.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001301 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +01001302 */
Michal Vasko55896172022-02-17 10:47:21 +01001303LIBYANG_API_DECL LY_ERR lyd_new_list(struct lyd_node *parent, const struct lys_module *module, const char *name,
stewegd4cde642024-02-21 08:34:16 +01001304 uint32_t options, struct lyd_node **node, ...);
Michal Vasko208e6d62021-06-28 11:23:50 +02001305
1306/**
Radek Krejci8247bae2021-03-12 11:47:02 +01001307 * @brief Create a new top-level list node defined in the given extension instance.
1308 *
1309 * To create a list node with parent (no matter if defined inside extension instance or a standard tree) or a top-level
1310 * list node of a standard module's tree, use ::lyd_new_list() or ::lyd_new_list2().
1311 *
1312 * @param[in] ext Extension instance where the list node being created is defined.
1313 * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001314 * @param[in] options Bitmask of options, see @ref newvaloptions.
Radek Krejci8247bae2021-03-12 11:47:02 +01001315 * @param[out] node The created node.
1316 * @param[in] ... Ordered key values of the new list instance, all must be set. In case of an instance-identifier
stewegd4cde642024-02-21 08:34:16 +01001317 * or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for key-less lists.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001318 * In case options include ::LYD_NEW_VAL_BIN, every key value must be followed by its length.
Radek Krejci8247bae2021-03-12 11:47:02 +01001319 * @return LY_ERR value.
1320 */
stewegd4cde642024-02-21 08:34:16 +01001321LIBYANG_API_DECL LY_ERR lyd_new_ext_list(const struct lysc_ext_instance *ext, const char *name, uint32_t options,
1322 struct lyd_node **node, ...);
Radek Krejci8247bae2021-03-12 11:47:02 +01001323
1324/**
Michal Vasko00cbf532020-06-15 13:58:47 +02001325 * @brief Create a new list node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +01001326 *
1327 * @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 +01001328 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +01001329 * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
1330 * @param[in] keys All key values predicate in the form of "[key1='val1'][key2='val2']...", they do not have to be ordered.
1331 * 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 +02001332 * Use NULL or string of length 0 in case of key-less list.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001333 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001334 * @param[out] node Optional created node.
1335 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +01001336 */
Michal Vasko55896172022-02-17 10:47:21 +01001337LIBYANG_API_DECL LY_ERR lyd_new_list2(struct lyd_node *parent, const struct lys_module *module, const char *name,
stewegd4cde642024-02-21 08:34:16 +01001338 const char *keys, uint32_t options, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +01001339
1340/**
Michal Vasko2c1e3272023-10-17 14:08:35 +02001341 * @brief Create a new list node in the data tree.
1342 *
1343 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
1344 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
1345 * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
Michal Vasko2c1e3272023-10-17 14:08:35 +02001346 * @param[in] key_values Ordered key string values of the new list instance, all must be set.
1347 * @param[in] value_lengths Array of lengths of each @p key_values, may be NULL if @p key_values are 0-terminated strings.
Michal Vaskof8c0b582024-02-21 09:55:53 +01001348 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko2c1e3272023-10-17 14:08:35 +02001349 * @param[out] node Optional created node.
1350 * @return LY_ERR value.
1351 */
1352LIBYANG_API_DECL LY_ERR lyd_new_list3(struct lyd_node *parent, const struct lys_module *module, const char *name,
stewegd4cde642024-02-21 08:34:16 +01001353 const char **key_values, uint32_t *value_lengths, uint32_t options, struct lyd_node **node);
Michal Vasko2c1e3272023-10-17 14:08:35 +02001354
1355/**
Michal Vasko00cbf532020-06-15 13:58:47 +02001356 * @brief Create a new term node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +01001357 *
Radek Krejci8a5afc22021-03-12 11:10:47 +01001358 * To create a top-level term node defined in an extension instance, use ::lyd_new_ext_term().
stewegd4cde642024-02-21 08:34:16 +01001359 * To create a term node based on binary value, use ::lyd_new_term_bin().
Radek Krejci8a5afc22021-03-12 11:10:47 +01001360 *
Michal Vasko013a8182020-03-03 10:46:53 +01001361 * @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 +01001362 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +01001363 * @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001364 * @param[in] value Value of the node in JSON format unless changed by @p options.
1365 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001366 * @param[out] node Optional created node.
1367 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +01001368 */
Michal Vasko55896172022-02-17 10:47:21 +01001369LIBYANG_API_DECL LY_ERR lyd_new_term(struct lyd_node *parent, const struct lys_module *module, const char *name,
stewegd4cde642024-02-21 08:34:16 +01001370 const char *value, uint32_t options, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +01001371
1372/**
stewegd4cde642024-02-21 08:34:16 +01001373 * @brief Create a new term node in the data tree based on binary value.
Radek Krejci09c77442021-04-26 11:10:34 +02001374 *
1375 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
1376 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
1377 * @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
1378 * @param[in] value Binary value of the node. To learn what exactly is expected see @ref howtoDataLYB.
1379 * @param[in] value_len Length of @p value.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001380 * @param[in] options Bitmask of options, see @ref newvaloptions.
Radek Krejci09c77442021-04-26 11:10:34 +02001381 * @param[out] node Optional created node.
1382 * @return LY_ERR value.
1383 */
Michal Vasko55896172022-02-17 10:47:21 +01001384LIBYANG_API_DECL LY_ERR lyd_new_term_bin(struct lyd_node *parent, const struct lys_module *module, const char *name,
stewegd4cde642024-02-21 08:34:16 +01001385 const void *value, size_t value_len, uint32_t options, struct lyd_node **node);
Radek Krejci09c77442021-04-26 11:10:34 +02001386
1387/**
Radek Krejci8a5afc22021-03-12 11:10:47 +01001388 * @brief Create a new top-level term node defined in the given extension instance.
1389 *
1390 * To create a term node with parent (no matter if defined inside extension instance or a standard tree) or a top-level
1391 * node of a standard module's tree, use ::lyd_new_term().
1392 *
1393 * @param[in] ext Extension instance where the term node being created is defined.
1394 * @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001395 * @param[in] value Value of the node in JSON format unless changed by @p options.
1396 * @param[in] value_len Length of @p value.
1397 * @param[in] options Bitmask of options, see @ref newvaloptions.
Radek Krejci8a5afc22021-03-12 11:10:47 +01001398 * @param[out] node The created node.
1399 * @return LY_ERR value.
1400 */
stewegd4cde642024-02-21 08:34:16 +01001401LIBYANG_API_DECL LY_ERR lyd_new_ext_term(const struct lysc_ext_instance *ext, const char *name, const void *value,
1402 size_t value_len, uint32_t options, struct lyd_node **node);
Radek Krejci8a5afc22021-03-12 11:10:47 +01001403
1404/**
Michal Vasko00cbf532020-06-15 13:58:47 +02001405 * @brief Create a new any node in the data tree.
Michal Vasko013a8182020-03-03 10:46:53 +01001406 *
Radek Krejci0b963da2021-03-12 13:23:44 +01001407 * To create a top-level any node defined in an extension instance, use ::lyd_new_ext_any().
1408 *
Michal Vasko013a8182020-03-03 10:46:53 +01001409 * @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 +01001410 * @param[in] module Module of the node being created. If NULL, @p parent module will be used.
Michal Vasko013a8182020-03-03 10:46:53 +01001411 * @param[in] name Schema node name of the new data node. The node can be #LYS_ANYDATA or #LYS_ANYXML.
Michal Vasko2a4ab2b2021-03-04 15:52:40 +01001412 * @param[in] value Value for the node. Expected type is determined by @p value_type.
Michal Vasko013a8182020-03-03 10:46:53 +01001413 * @param[in] value_type Type of the provided value in @p value.
Michal Vasko6a027db2024-02-21 09:55:34 +01001414 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001415 * @param[out] node Optional created node.
1416 * @return LY_ERR value.
Michal Vasko013a8182020-03-03 10:46:53 +01001417 */
Michal Vasko55896172022-02-17 10:47:21 +01001418LIBYANG_API_DECL LY_ERR lyd_new_any(struct lyd_node *parent, const struct lys_module *module, const char *name,
Michal Vasko6a027db2024-02-21 09:55:34 +01001419 const void *value, LYD_ANYDATA_VALUETYPE value_type, uint32_t options, struct lyd_node **node);
Michal Vasko013a8182020-03-03 10:46:53 +01001420
1421/**
Radek Krejci0b963da2021-03-12 13:23:44 +01001422 * @brief Create a new top-level any node defined in the given extension instance.
1423 *
1424 * To create an any node with parent (no matter if defined inside extension instance or a standard tree) or a top-level
1425 * any node of a standard module's tree, use ::lyd_new_any().
1426 *
1427 * @param[in] ext Extension instance where the any node being created is defined.
1428 * @param[in] name Schema node name of the new data node. The node can be #LYS_ANYDATA or #LYS_ANYXML.
1429 * @param[in] value Value for the node. Expected type is determined by @p value_type.
Radek Krejci0b963da2021-03-12 13:23:44 +01001430 * @param[in] value_type Type of the provided value in @p value.
Michal Vasko6a027db2024-02-21 09:55:34 +01001431 * @param[in] options Bitmask of options, see @ref newvaloptions.
Radek Krejci0b963da2021-03-12 13:23:44 +01001432 * @param[out] node The created node.
1433 * @return LY_ERR value.
1434 */
Michal Vasko55896172022-02-17 10:47:21 +01001435LIBYANG_API_DECL LY_ERR lyd_new_ext_any(const struct lysc_ext_instance *ext, const char *name, const void *value,
Michal Vasko6a027db2024-02-21 09:55:34 +01001436 LYD_ANYDATA_VALUETYPE value_type, uint32_t options, struct lyd_node **node);
Radek Krejci0b963da2021-03-12 13:23:44 +01001437
1438/**
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001439 * @brief Create a new metadata.
Michal Vaskod86997b2020-05-26 15:19:54 +02001440 *
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001441 * @param[in] ctx libyang context.
Michal Vasko871a0252020-11-11 18:35:24 +01001442 * @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 +02001443 * @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 +02001444 * @param[in] name Annotation name of the new metadata. It can include the annotation module as the prefix.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001445 * 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 +02001446 * @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 +02001447 * value, the JSON format is expected (module names instead of prefixes).
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001448 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko871a0252020-11-11 18:35:24 +01001449 * @param[out] meta Optional created metadata. Must be set if @p parent is NULL.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001450 * @return LY_ERR value.
Michal Vaskod86997b2020-05-26 15:19:54 +02001451 */
Michal Vasko55896172022-02-17 10:47:21 +01001452LIBYANG_API_DECL LY_ERR lyd_new_meta(const struct ly_ctx *ctx, struct lyd_node *parent, const struct lys_module *module,
stewegd4cde642024-02-21 08:34:16 +01001453 const char *name, const char *val_str, uint32_t options, struct lyd_meta **meta);
Michal Vaskod86997b2020-05-26 15:19:54 +02001454
1455/**
Michal Vaskoba696702020-11-11 19:12:45 +01001456 * @brief Create new metadata from an opaque node attribute if possible.
1457 *
1458 * @param[in] ctx libyang context.
1459 * @param[in] parent Optional parent node for the metadata being created. Must be set if @p meta is NULL.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001460 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vaskoba696702020-11-11 19:12:45 +01001461 * @param[in] attr Opaque node attribute to parse into metadata.
1462 * @param[out] meta Optional created metadata. Must be set if @p parent is NULL.
1463 * @return LY_SUCCESS on success.
1464 * @return LY_ENOT if the attribute could not be parsed into any metadata.
1465 * @return LY_ERR on error.
1466 */
stewegd4cde642024-02-21 08:34:16 +01001467LIBYANG_API_DECL LY_ERR lyd_new_meta2(const struct ly_ctx *ctx, struct lyd_node *parent, uint32_t options,
Michal Vasko55896172022-02-17 10:47:21 +01001468 const struct lyd_attr *attr, struct lyd_meta **meta);
Michal Vaskoba696702020-11-11 19:12:45 +01001469
1470/**
Michal Vasko8d65f852021-02-17 11:28:13 +01001471 * @brief Create a new JSON opaque node in the data tree. To create an XML opaque node, use ::lyd_new_opaq2().
Michal Vasko00cbf532020-06-15 13:58:47 +02001472 *
aPiecekb0445f22021-06-24 11:34:07 +02001473 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vasko00cbf532020-06-15 13:58:47 +02001474 * @param[in] ctx libyang context. If NULL, @p parent context will be used.
1475 * @param[in] name Node name.
Michal Vasko0ab974d2021-02-24 13:18:26 +01001476 * @param[in] value Optional node value.
1477 * @param[in] prefix Optional node prefix, must be equal to @p module_name if set.
Michal Vasko00cbf532020-06-15 13:58:47 +02001478 * @param[in] module_name Node module name.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001479 * @param[out] node Optional created node.
1480 * @return LY_ERR value.
Michal Vasko00cbf532020-06-15 13:58:47 +02001481 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001482LIBYANG_API_DECL LY_ERR lyd_new_opaq(struct lyd_node *parent, const struct ly_ctx *ctx, const char *name, const char *value,
Michal Vasko0ab974d2021-02-24 13:18:26 +01001483 const char *prefix, const char *module_name, struct lyd_node **node);
Michal Vasko00cbf532020-06-15 13:58:47 +02001484
1485/**
Michal Vasko8d65f852021-02-17 11:28:13 +01001486 * @brief Create a new XML opaque node in the data tree. To create a JSON opaque node, use ::lyd_new_opaq().
1487 *
aPiecekb0445f22021-06-24 11:34:07 +02001488 * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
Michal Vasko8d65f852021-02-17 11:28:13 +01001489 * @param[in] ctx libyang context. If NULL, @p parent context will be used.
1490 * @param[in] name Node name.
Michal Vasko0ab974d2021-02-24 13:18:26 +01001491 * @param[in] value Optional node value.
1492 * @param[in] prefix Optional node prefix.
Michal Vasko8d65f852021-02-17 11:28:13 +01001493 * @param[in] module_ns Node module namespace.
1494 * @param[out] node Optional created node.
1495 * @return LY_ERR value.
1496 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001497LIBYANG_API_DECL LY_ERR lyd_new_opaq2(struct lyd_node *parent, const struct ly_ctx *ctx, const char *name, const char *value,
Michal Vasko0ab974d2021-02-24 13:18:26 +01001498 const char *prefix, const char *module_ns, struct lyd_node **node);
Michal Vasko8d65f852021-02-17 11:28:13 +01001499
1500/**
1501 * @brief Create new JSON attribute for an opaque data node. To create an XML attribute, use ::lyd_new_attr2().
Michal Vasko00cbf532020-06-15 13:58:47 +02001502 *
Michal Vasko5e60e872021-11-09 09:49:27 +01001503 * Note that for an attribute to be later resolved as YANG metadata, it needs @p module_nane and a prefix in @p name.
1504 *
1505 * @param[in] parent Parent opaque node for the attribute.
1506 * @param[in] module_name Optional name of the module of the attribute.
1507 * @param[in] name Attribute name with optional prefix, which is a module name. If the prefix is set, it is also stored
1508 * as the explicit module name if @p module_name is not set.
1509 * @param[in] value Optional attribute value.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001510 * @param[out] attr Optional created attribute.
1511 * @return LY_ERR value.
Michal Vasko00cbf532020-06-15 13:58:47 +02001512 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001513LIBYANG_API_DECL LY_ERR lyd_new_attr(struct lyd_node *parent, const char *module_name, const char *name, const char *value,
Michal Vasko8d65f852021-02-17 11:28:13 +01001514 struct lyd_attr **attr);
1515
1516/**
1517 * @brief Create new XML attribute for an opaque data node. To create a JSON attribute, use ::lyd_new_attr().
1518 *
Michal Vasko5e60e872021-11-09 09:49:27 +01001519 * Note that for an attribute to be later resolved as YANG metadata, it needs @p module_ns and a prefix in @p name.
1520 *
Michal Vasko8d65f852021-02-17 11:28:13 +01001521 * @param[in] parent Parent opaque node for the attribute being created.
Michal Vasko5e60e872021-11-09 09:49:27 +01001522 * @param[in] module_ns Optional namespace of the module of the attribute.
1523 * @param[in] name Attribute name with optional prefix, which is an XML prefix.
1524 * @param[in] value Optional attribute value.
Michal Vasko8d65f852021-02-17 11:28:13 +01001525 * @param[out] attr Optional created attribute.
1526 * @return LY_ERR value.
1527 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001528LIBYANG_API_DECL LY_ERR lyd_new_attr2(struct lyd_node *parent, const char *module_ns, const char *name, const char *value,
Radek Krejci0f969882020-08-21 16:56:47 +02001529 struct lyd_attr **attr);
Michal Vasko00cbf532020-06-15 13:58:47 +02001530
1531/**
Michal Vaskod5e67442021-03-04 15:56:31 +01001532 * @brief Create a new node in the data tree based on a path. If creating anyxml/anydata nodes, ::lyd_new_path2
1533 * should be used instead, this function expects the value as string.
Michal Vasko00cbf532020-06-15 13:58:47 +02001534 *
Radek Krejci95ccd1b2021-03-12 14:57:22 +01001535 * If creating data nodes defined inside an extension instance, use ::lyd_new_ext_path().
1536 *
Michal Vaskoa918a632021-07-02 11:53:36 +02001537 * If @p path points to a list key, the key value from the predicate is used and @p value is ignored.
1538 * Also, if a leaf-list is being created and both a predicate is defined in @p path
Michal Vasko00cbf532020-06-15 13:58:47 +02001539 * and @p value is set, the predicate is preferred.
1540 *
Michal Vasko5de21542023-03-20 10:00:05 +01001541 * For key-less lists, positional predicates must be used (indices starting from 1). For non-configuration leaf-lists
1542 * either positional predicate can be used or leaf-list predicate, when an instance is always created at the end.
Michal Vasko2261dfa2022-09-29 12:29:20 +02001543 * If no predicate is used for these nodes, they are always created.
Michal Vasko6741dc62021-02-04 09:27:45 +01001544 *
Michal Vasko104fe962020-11-06 17:23:44 +01001545 * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
1546 * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
1547 * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
Michal Vasko00cbf532020-06-15 13:58:47 +02001548 * @param[in] ctx libyang context, must be set if @p parent is NULL.
Michal Vasko104fe962020-11-06 17:23:44 +01001549 * @param[in] path [Path](@ref howtoXPath) to create.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001550 * @param[in] value String value of the new leaf/leaf-list in JSON format. For other node types it should be NULL.
stewegd4cde642024-02-21 08:34:16 +01001551 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001552 * @param[out] node Optional first created node.
Michal Vasko0a8fcc22023-03-03 09:54:32 +01001553 * @return LY_SUCCESS on success.
1554 * @return LY_EEXIST if the final node to create exists (unless ::LYD_NEW_PATH_UPDATE is used).
1555 * @return LY_EINVAL on invalid arguments including invalid @p path.
1556 * @return LY_EVALID on invalid @p value.
1557 * @return LY_ERR on other errors.
Michal Vasko00cbf532020-06-15 13:58:47 +02001558 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001559LIBYANG_API_DECL LY_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 +02001560 uint32_t options, struct lyd_node **node);
Michal Vasko00cbf532020-06-15 13:58:47 +02001561
1562/**
1563 * @brief Create a new node in the data tree based on a path. All node types can be created.
1564 *
Michal Vasko65591ab2021-04-09 14:29:34 +02001565 * Details are mentioned in ::lyd_new_path().
Michal Vasko6741dc62021-02-04 09:27:45 +01001566 *
Michal Vasko104fe962020-11-06 17:23:44 +01001567 * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
1568 * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
1569 * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
Michal Vasko00cbf532020-06-15 13:58:47 +02001570 * @param[in] ctx libyang context, must be set if @p parent is NULL.
Michal Vasko104fe962020-11-06 17:23:44 +01001571 * @param[in] path [Path](@ref howtoXPath) to create.
Radek Krejci09c77442021-04-26 11:10:34 +02001572 * @param[in] value Value of the new leaf/leaf-list (const char *) in ::LY_VALUE_JSON format. If creating an
1573 * anyxml/anydata node, the expected type depends on @p value_type. For other node types, it should be NULL.
1574 * @param[in] value_len Length of @p value in bytes. May be 0 if @p value is a zero-terminated string. Ignored when
1575 * creating anyxml/anydata nodes.
Michal Vasko00cbf532020-06-15 13:58:47 +02001576 * @param[in] value_type Anyxml/anydata node @p value type.
stewegd4cde642024-02-21 08:34:16 +01001577 * @param[in] options Bitmask of options, see @ref newvaloptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001578 * @param[out] new_parent Optional first parent node created. If only one node was created, equals to @p new_node.
1579 * @param[out] new_node Optional last node created.
Michal Vasko0a8fcc22023-03-03 09:54:32 +01001580 * @return LY_SUCCESS on success.
1581 * @return LY_EEXIST if the final node to create exists (unless ::LYD_NEW_PATH_UPDATE is used).
1582 * @return LY_EINVAL on invalid arguments including invalid @p path.
1583 * @return LY_EVALID on invalid @p value.
1584 * @return LY_ERR on other errors.
Michal Vasko00cbf532020-06-15 13:58:47 +02001585 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001586LIBYANG_API_DECL LY_ERR lyd_new_path2(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const void *value,
Radek Krejci09c77442021-04-26 11:10:34 +02001587 size_t value_len, LYD_ANYDATA_VALUETYPE value_type, uint32_t options, struct lyd_node **new_parent,
1588 struct lyd_node **new_node);
Michal Vasko00cbf532020-06-15 13:58:47 +02001589
1590/**
Radek Krejci95ccd1b2021-03-12 14:57:22 +01001591 * @brief Create a new node defined in the given extension instance. In case of anyxml/anydata nodes, this function expects
1592 * the @p value as string.
1593 *
1594 * If creating data nodes defined in a module's standard tree, use ::lyd_new_path() or ::lyd_new_path2().
1595 *
Michal Vasko65591ab2021-04-09 14:29:34 +02001596 * Details are mentioned in ::lyd_new_path().
Radek Krejci95ccd1b2021-03-12 14:57:22 +01001597 *
1598 * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
1599 * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
1600 * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
1601 * @param[in] ext Extension instance where the node being created is defined.
1602 * @param[in] path [Path](@ref howtoXPath) to create.
Radek Krejci09c77442021-04-26 11:10:34 +02001603 * @param[in] value Value of the new leaf/leaf-list. For other node types, it should be NULL.
Michal Vaskoabd34fb2024-02-21 09:53:56 +01001604 * @param[in] options Bitmask of options, see @ref newvaloptions.
Radek Krejci95ccd1b2021-03-12 14:57:22 +01001605 * @param[out] node Optional first created node.
Michal Vasko0a8fcc22023-03-03 09:54:32 +01001606 * @return LY_SUCCESS on success.
1607 * @return LY_EEXIST if the final node to create exists (unless ::LYD_NEW_PATH_UPDATE is used).
1608 * @return LY_EINVAL on invalid arguments including invalid @p path.
1609 * @return LY_EVALID on invalid @p value.
1610 * @return LY_ERR on other errors.
Radek Krejci95ccd1b2021-03-12 14:57:22 +01001611 */
Michal Vasko55896172022-02-17 10:47:21 +01001612LIBYANG_API_DECL LY_ERR lyd_new_ext_path(struct lyd_node *parent, const struct lysc_ext_instance *ext, const char *path,
1613 const void *value, uint32_t options, struct lyd_node **node);
Radek Krejci95ccd1b2021-03-12 14:57:22 +01001614
1615/**
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001616 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001617 * @defgroup implicitoptions Implicit node creation options
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001618 *
1619 * Various options to change lyd_new_implicit*() behavior.
1620 *
1621 * Default behavior:
1622 * - both configuration and state missing implicit nodes are added.
Michal Vasko630d9892020-12-08 17:11:08 +01001623 * - for existing RPC/action nodes, input implicit nodes are added.
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001624 * - all implicit node types are added (non-presence containers, default leaves, and default leaf-lists).
1625 * @{
1626 */
1627
Michal Vasko44b19a12020-08-07 09:21:30 +02001628#define LYD_IMPLICIT_NO_STATE 0x01 /**< Do not add any implicit state nodes. */
1629#define LYD_IMPLICIT_NO_CONFIG 0x02 /**< Do not add any implicit config nodes. */
Michal Vasko630d9892020-12-08 17:11:08 +01001630#define LYD_IMPLICIT_OUTPUT 0x04 /**< For RPC/action nodes, add output implicit nodes instead of input. */
1631#define LYD_IMPLICIT_NO_DEFAULTS 0x08 /**< Do not add any default nodes (leaves/leaf-lists), only non-presence
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001632 containers. */
1633
1634/** @} implicitoptions */
1635
1636/**
Michal Vasko3488ada2020-12-03 14:18:19 +01001637 * @brief Add any missing implicit nodes into a data subtree. Default nodes with a false "when" are not added.
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001638 *
1639 * @param[in] tree Tree to add implicit nodes into.
1640 * @param[in] implicit_options Options for implicit node creation, see @ref implicitoptions.
1641 * @param[out] diff Optional diff with any created nodes.
1642 * @return LY_ERR value.
1643 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001644LIBYANG_API_DECL LY_ERR lyd_new_implicit_tree(struct lyd_node *tree, uint32_t implicit_options, struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001645
1646/**
Michal Vasko3488ada2020-12-03 14:18:19 +01001647 * @brief Add any missing implicit nodes. Default nodes with a false "when" are not added.
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001648 *
Michal Vaskod3bb12f2020-12-04 14:33:09 +01001649 * @param[in,out] tree Tree to add implicit nodes into. Note that in case a first top-level sibling is used,
1650 * it may no longer be first if an implicit node was inserted before @p tree. Use ::lyd_first_sibling() to
1651 * adjust @p tree in these cases.
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001652 * @param[in] ctx libyang context, must be set only if @p tree is an empty tree.
1653 * @param[in] implicit_options Options for implicit node creation, see @ref implicitoptions.
1654 * @param[out] diff Optional diff with any created nodes.
1655 * @return LY_ERR value.
1656 */
Michal Vasko55896172022-02-17 10:47:21 +01001657LIBYANG_API_DECL LY_ERR lyd_new_implicit_all(struct lyd_node **tree, const struct ly_ctx *ctx, uint32_t implicit_options,
1658 struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001659
1660/**
Michal Vasko3488ada2020-12-03 14:18:19 +01001661 * @brief Add any missing implicit nodes of one module. Default nodes with a false "when" are not added.
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001662 *
Michal Vaskod3bb12f2020-12-04 14:33:09 +01001663 * @param[in,out] tree Tree to add implicit nodes into. Note that in case a first top-level sibling is used,
1664 * it may no longer be first if an implicit node was inserted before @p tree. Use ::lyd_first_sibling() to
1665 * adjust @p tree in these cases.
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001666 * @param[in] module Module whose implicit nodes to create.
1667 * @param[in] implicit_options Options for implicit node creation, see @ref implicitoptions.
1668 * @param[out] diff Optional diff with any created nodes.
1669 * @return LY_ERR value.
1670 */
Michal Vasko55896172022-02-17 10:47:21 +01001671LIBYANG_API_DECL LY_ERR lyd_new_implicit_module(struct lyd_node **tree, const struct lys_module *module,
1672 uint32_t implicit_options, struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +02001673
1674/**
Radek Krejci09c77442021-04-26 11:10:34 +02001675 * @brief Change the value of a term (leaf or leaf-list) node to a string value.
Michal Vasko00cbf532020-06-15 13:58:47 +02001676 *
1677 * Node changed this way is always considered explicitly set, meaning its default flag
1678 * is always cleared.
1679 *
1680 * @param[in] term Term node to change.
1681 * @param[in] val_str New value to set, any prefixes are expected in JSON format.
1682 * @return LY_SUCCESS if value was changed,
1683 * @return LY_EEXIST if value was the same and only the default flag was cleared,
aPiecekb0445f22021-06-24 11:34:07 +02001684 * @return LY_ENOT if the values were equal and no change occurred,
Michal Vasko00cbf532020-06-15 13:58:47 +02001685 * @return LY_ERR value on other errors.
1686 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001687LIBYANG_API_DECL LY_ERR lyd_change_term(struct lyd_node *term, const char *val_str);
Michal Vasko00cbf532020-06-15 13:58:47 +02001688
1689/**
Radek Krejci09c77442021-04-26 11:10:34 +02001690 * @brief Change the value of a term (leaf or leaf-list) node to a binary value.
1691 *
1692 * Node changed this way is always considered explicitly set, meaning its default flag
1693 * is always cleared.
1694 *
1695 * @param[in] term Term node to change.
Michal Vasko8193b072023-03-22 08:13:59 +01001696 * @param[in] value New value to set in binary format (usually a pointer), see @ref howtoDataLYB.
Radek Krejci09c77442021-04-26 11:10:34 +02001697 * @param[in] value_len Length of @p value.
1698 * @return LY_SUCCESS if value was changed,
1699 * @return LY_EEXIST if value was the same and only the default flag was cleared,
aPiecekb0445f22021-06-24 11:34:07 +02001700 * @return LY_ENOT if the values were equal and no change occurred,
Radek Krejci09c77442021-04-26 11:10:34 +02001701 * @return LY_ERR value on other errors.
1702 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001703LIBYANG_API_DECL LY_ERR lyd_change_term_bin(struct lyd_node *term, const void *value, size_t value_len);
Radek Krejci09c77442021-04-26 11:10:34 +02001704
1705/**
1706 * @brief Change the value of a term (leaf or leaf-list) node to a canonical string value.
1707 *
1708 * Node changed this way is always considered explicitly set, meaning its default flag
1709 * is always cleared.
1710 *
1711 * @param[in] term Term node to change.
1712 * @param[in] val_str New value to set in canonical (or JSON if no defined) format. If the value is not
1713 * canonical, it may lead to unexpected behavior.
1714 * @return LY_SUCCESS if value was changed,
1715 * @return LY_EEXIST if value was the same and only the default flag was cleared,
aPiecekb0445f22021-06-24 11:34:07 +02001716 * @return LY_ENOT if the values were equal and no change occurred,
Radek Krejci09c77442021-04-26 11:10:34 +02001717 * @return LY_ERR value on other errors.
1718 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001719LIBYANG_API_DECL LY_ERR lyd_change_term_canon(struct lyd_node *term, const char *val_str);
Radek Krejci09c77442021-04-26 11:10:34 +02001720
1721/**
Michal Vasko41586352020-07-13 13:54:25 +02001722 * @brief Change the value of a metadata instance.
1723 *
Michal Vasko41586352020-07-13 13:54:25 +02001724 * @param[in] meta Metadata to change.
1725 * @param[in] val_str New value to set, any prefixes are expected in JSON format.
1726 * @return LY_SUCCESS if value was changed,
aPiecekb0445f22021-06-24 11:34:07 +02001727 * @return LY_ENOT if the values were equal and no change occurred,
Michal Vasko41586352020-07-13 13:54:25 +02001728 * @return LY_ERR value on other errors.
1729 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001730LIBYANG_API_DECL LY_ERR lyd_change_meta(struct lyd_meta *meta, const char *val_str);
Michal Vasko41586352020-07-13 13:54:25 +02001731
1732/**
Michal Vaskob104f112020-07-17 09:54:54 +02001733 * @brief Insert a child into a parent.
Michal Vaskof03ed032020-03-04 13:31:44 +01001734 *
1735 * - if the node is part of some other tree, it is automatically unlinked.
1736 * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
1737 *
1738 * @param[in] parent Parent node to insert into.
1739 * @param[in] node Node to insert.
1740 * @return LY_SUCCESS on success.
1741 * @return LY_ERR error on error.
1742 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001743LIBYANG_API_DECL LY_ERR lyd_insert_child(struct lyd_node *parent, struct lyd_node *node);
Michal Vaskof03ed032020-03-04 13:31:44 +01001744
1745/**
Michal Vaskob104f112020-07-17 09:54:54 +02001746 * @brief Insert a node into siblings.
Michal Vaskob1b5c262020-03-05 14:29:47 +01001747 *
1748 * - if the node is part of some other tree, it is automatically unlinked.
1749 * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
1750 *
Michal Vaskob104f112020-07-17 09:54:54 +02001751 * @param[in] sibling Siblings to insert into, can even be NULL.
Michal Vaskob1b5c262020-03-05 14:29:47 +01001752 * @param[in] node Node to insert.
Michal Vaskob104f112020-07-17 09:54:54 +02001753 * @param[out] first Optionally return the first sibling after insertion. Can be the address of @p sibling.
Michal Vaskob1b5c262020-03-05 14:29:47 +01001754 * @return LY_SUCCESS on success.
1755 * @return LY_ERR error on error.
1756 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001757LIBYANG_API_DECL LY_ERR lyd_insert_sibling(struct lyd_node *sibling, struct lyd_node *node, struct lyd_node **first);
Michal Vaskob1b5c262020-03-05 14:29:47 +01001758
1759/**
Michal Vaskob104f112020-07-17 09:54:54 +02001760 * @brief Insert a node before another node, can be used only for user-ordered nodes.
Michal Vasko4bc2ce32020-12-08 10:06:16 +01001761 * If inserting several siblings, each of them must be inserted individually.
Michal Vaskof03ed032020-03-04 13:31:44 +01001762 *
1763 * - if the node is part of some other tree, it is automatically unlinked.
Michal Vaskof03ed032020-03-04 13:31:44 +01001764 *
1765 * @param[in] sibling Sibling node to insert before.
1766 * @param[in] node Node to insert.
1767 * @return LY_SUCCESS on success.
1768 * @return LY_ERR error on error.
1769 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001770LIBYANG_API_DECL LY_ERR lyd_insert_before(struct lyd_node *sibling, struct lyd_node *node);
Michal Vaskof03ed032020-03-04 13:31:44 +01001771
1772/**
Michal Vaskob104f112020-07-17 09:54:54 +02001773 * @brief Insert a node after another node, can be used only for user-ordered nodes.
Michal Vasko4bc2ce32020-12-08 10:06:16 +01001774 * If inserting several siblings, each of them must be inserted individually.
Michal Vaskof03ed032020-03-04 13:31:44 +01001775 *
1776 * - if the node is part of some other tree, it is automatically unlinked.
Michal Vaskof03ed032020-03-04 13:31:44 +01001777 *
1778 * @param[in] sibling Sibling node to insert after.
1779 * @param[in] node Node to insert.
1780 * @return LY_SUCCESS on success.
1781 * @return LY_ERR error on error.
1782 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001783LIBYANG_API_DECL LY_ERR lyd_insert_after(struct lyd_node *sibling, struct lyd_node *node);
Michal Vaskof03ed032020-03-04 13:31:44 +01001784
1785/**
Michal Vasko66d508c2021-07-21 16:07:09 +02001786 * @brief Unlink the specified node with all the following siblings.
1787 *
1788 * @param[in] node Data tree node to be unlinked (together with all the children and following siblings).
aPiecekdfde77d2024-01-15 15:16:01 +01001789 * @return LYS_SUCCESS on success.
1790 * @return LY_ERR error on error.
Michal Vasko66d508c2021-07-21 16:07:09 +02001791 */
aPiecekdfde77d2024-01-15 15:16:01 +01001792LIBYANG_API_DECL LY_ERR lyd_unlink_siblings(struct lyd_node *node);
Michal Vasko66d508c2021-07-21 16:07:09 +02001793
1794/**
Michal Vaskof03ed032020-03-04 13:31:44 +01001795 * @brief Unlink the specified data subtree.
1796 *
1797 * @param[in] node Data tree node to be unlinked (together with all the children).
aPiecekdfde77d2024-01-15 15:16:01 +01001798 * @return LYS_SUCCESS on success.
1799 * @return LY_ERR error on error.
Michal Vaskof03ed032020-03-04 13:31:44 +01001800 */
aPiecekdfde77d2024-01-15 15:16:01 +01001801LIBYANG_API_DECL LY_ERR lyd_unlink_tree(struct lyd_node *node);
Michal Vaskof03ed032020-03-04 13:31:44 +01001802
1803/**
Radek Krejcib0849a22019-07-25 12:31:04 +02001804 * @brief Free all the nodes (even parents of the node) in the data tree.
Radek Krejcie7b95092019-05-15 11:03:07 +02001805 *
1806 * @param[in] node Any of the nodes inside the tree.
1807 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001808LIBYANG_API_DECL void lyd_free_all(struct lyd_node *node);
Radek Krejcie7b95092019-05-15 11:03:07 +02001809
1810/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001811 * @brief Free all the sibling nodes (preceding as well as succeeding).
Radek Krejcib0849a22019-07-25 12:31:04 +02001812 *
1813 * @param[in] node Any of the sibling nodes to free.
1814 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001815LIBYANG_API_DECL void lyd_free_siblings(struct lyd_node *node);
Radek Krejcib0849a22019-07-25 12:31:04 +02001816
1817/**
Radek Krejcie7b95092019-05-15 11:03:07 +02001818 * @brief Free (and unlink) the specified data (sub)tree.
1819 *
Radek Krejcie7b95092019-05-15 11:03:07 +02001820 * @param[in] node Root of the (sub)tree to be freed.
1821 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001822LIBYANG_API_DECL void lyd_free_tree(struct lyd_node *node);
Radek Krejcie7b95092019-05-15 11:03:07 +02001823
1824/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001825 * @brief Free a single metadata instance.
Radek Krejcie7b95092019-05-15 11:03:07 +02001826 *
Michal Vasko3a41dff2020-07-15 14:30:28 +02001827 * @param[in] meta Metadata to free.
Radek Krejcie7b95092019-05-15 11:03:07 +02001828 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001829LIBYANG_API_DECL void lyd_free_meta_single(struct lyd_meta *meta);
Michal Vasko52927e22020-03-16 17:26:14 +01001830
1831/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02001832 * @brief Free the metadata instance with any following instances.
1833 *
1834 * @param[in] meta Metadata to free.
1835 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001836LIBYANG_API_DECL void lyd_free_meta_siblings(struct lyd_meta *meta);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001837
1838/**
1839 * @brief Free a single attribute.
Michal Vasko52927e22020-03-16 17:26:14 +01001840 *
1841 * @param[in] ctx Context where the attributes were created.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001842 * @param[in] attr Attribute to free.
Michal Vasko52927e22020-03-16 17:26:14 +01001843 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001844LIBYANG_API_DECL void lyd_free_attr_single(const struct ly_ctx *ctx, struct lyd_attr *attr);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001845
1846/**
1847 * @brief Free the attribute with any following attributes.
1848 *
1849 * @param[in] ctx Context where the attributes were created.
1850 * @param[in] attr First attribute to free.
1851 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001852LIBYANG_API_DECL void lyd_free_attr_siblings(const struct ly_ctx *ctx, struct lyd_attr *attr);
Radek Krejcie7b95092019-05-15 11:03:07 +02001853
Radek Krejci084289f2019-07-09 17:35:30 +02001854/**
1855 * @brief Check type restrictions applicable to the particular leaf/leaf-list with the given string @p value.
1856 *
1857 * The given node is not modified in any way - it is just checked if the @p value can be set to the node.
1858 *
Radek Krejci084289f2019-07-09 17:35:30 +02001859 * @param[in] ctx libyang context for logging (function does not log errors when @p ctx is NULL)
Michal Vaskoaebbce02021-04-06 09:23:37 +02001860 * @param[in] schema Schema node of the @p value.
Michal Vaskof937cfe2020-08-03 16:07:12 +02001861 * @param[in] value String value to be checked, it is expected to be in JSON format.
Radek Krejci084289f2019-07-09 17:35:30 +02001862 * @param[in] value_len Length of the given @p value (mandatory).
Michal Vaskoaebbce02021-04-06 09:23:37 +02001863 * @param[in] ctx_node Optional data tree context node for the value (leafref target, instance-identifier).
1864 * If not set and is required for the validation to complete, ::LY_EINCOMPLETE is be returned.
1865 * @param[out] realtype Optional real type of @p value.
1866 * @param[out] canonical Optional canonical value of @p value (in the dictionary).
Radek Krejci084289f2019-07-09 17:35:30 +02001867 * @return LY_SUCCESS on success
Michal Vaskoaebbce02021-04-06 09:23:37 +02001868 * @return LY_EINCOMPLETE in case the @p ctx_node is not provided and it was needed to finish the validation
1869 * (e.g. due to require-instance).
Radek Krejci084289f2019-07-09 17:35:30 +02001870 * @return LY_ERR value if an error occurred.
1871 */
Michal Vasko55896172022-02-17 10:47:21 +01001872LIBYANG_API_DECL LY_ERR lyd_value_validate(const struct ly_ctx *ctx, const struct lysc_node *schema, const char *value,
1873 size_t value_len, const struct lyd_node *ctx_node, const struct lysc_type **realtype, const char **canonical);
Radek Krejci084289f2019-07-09 17:35:30 +02001874
1875/**
Michal Vaskofeca4fb2020-10-05 08:58:40 +02001876 * @brief Compare the node's value with the given string value. The string value is first validated according to
1877 * the (current) node's type.
Radek Krejci084289f2019-07-09 17:35:30 +02001878 *
1879 * @param[in] node Data node to compare.
1880 * @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 +02001881 * it is validated and canonized if possible. But it is expected to be in JSON format.
Radek Krejci084289f2019-07-09 17:35:30 +02001882 * @param[in] value_len Length of the given @p value (mandatory).
Michal Vaskofeca4fb2020-10-05 08:58:40 +02001883 * @return LY_SUCCESS on success,
1884 * @return LY_ENOT if the values do not match,
Radek Krejci084289f2019-07-09 17:35:30 +02001885 * @return LY_ERR value if an error occurred.
1886 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001887LIBYANG_API_DECL LY_ERR lyd_value_compare(const struct lyd_node_term *node, const char *value, size_t value_len);
Radek Krejci084289f2019-07-09 17:35:30 +02001888
Radek Krejci576b23f2019-07-12 14:06:32 +02001889/**
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001890 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001891 * @defgroup datacompareoptions Data compare options
1892 * @{
1893 * Various options to change the ::lyd_compare_single() and ::lyd_compare_siblings() behavior.
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001894 */
Michal Vaskodf8ebf62022-11-10 10:33:28 +01001895#define LYD_COMPARE_FULL_RECURSION 0x01 /* Lists and containers are the same only in case all they children
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001896 (subtree, so direct as well as indirect children) are the same. By default,
1897 containers are the same in case of the same schema node and lists are the same
1898 in case of equal keys (keyless lists do the full recursion comparison all the time). */
1899#define LYD_COMPARE_DEFAULTS 0x02 /* By default, implicit and explicit default nodes are considered to be equal. This flag
1900 changes this behavior and implicit (automatically created default node) and explicit
1901 (explicitly created node with the default value) default nodes are considered different. */
Michal Vaskodf8ebf62022-11-10 10:33:28 +01001902#define LYD_COMPARE_OPAQ 0x04 /* Opaque nodes can normally be never equal to data nodes. Using this flag even
1903 opaque nodes members are compared to data node schema and value and can result
1904 in a match. */
Michal Vasko60ea6352020-06-29 13:39:39 +02001905/** @} datacompareoptions */
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001906
1907/**
1908 * @brief Compare 2 data nodes if they are equivalent.
1909 *
Michal Vasko892f5bf2021-11-24 10:41:05 +01001910 * Works correctly even if @p node1 and @p node2 have different contexts.
1911 *
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001912 * @param[in] node1 The first node to compare.
1913 * @param[in] node2 The second node to compare.
Radek Krejcic5ad9652019-09-11 11:31:51 +02001914 * @param[in] options Various @ref datacompareoptions.
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001915 * @return LY_SUCCESS if the nodes are equivalent.
1916 * @return LY_ENOT if the nodes are not equivalent.
1917 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001918LIBYANG_API_DECL LY_ERR lyd_compare_single(const struct lyd_node *node1, const struct lyd_node *node2, uint32_t options);
Michal Vasko8f359bf2020-07-28 10:41:15 +02001919
1920/**
1921 * @brief Compare 2 lists of siblings if they are equivalent.
1922 *
Michal Vasko892f5bf2021-11-24 10:41:05 +01001923 * Works correctly even if @p node1 and @p node2 have different contexts.
1924 *
Michal Vasko8f359bf2020-07-28 10:41:15 +02001925 * @param[in] node1 The first sibling list to compare.
1926 * @param[in] node2 The second sibling list to compare.
1927 * @param[in] options Various @ref datacompareoptions.
1928 * @return LY_SUCCESS if all the siblings are equivalent.
1929 * @return LY_ENOT if the siblings are not equivalent.
1930 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001931LIBYANG_API_DECL LY_ERR lyd_compare_siblings(const struct lyd_node *node1, const struct lyd_node *node2, uint32_t options);
Radek Krejci1f05b6a2019-07-18 16:15:06 +02001932
1933/**
Michal Vasko21725742020-06-29 11:49:25 +02001934 * @brief Compare 2 metadata.
1935 *
Michal Vasko892f5bf2021-11-24 10:41:05 +01001936 * If @p meta1 and @p meta2 have different contexts, they are never equivalent.
1937 *
Michal Vasko21725742020-06-29 11:49:25 +02001938 * @param[in] meta1 First metadata.
1939 * @param[in] meta2 Second metadata.
1940 * @return LY_SUCCESS if the metadata are equivalent.
1941 * @return LY_ENOT if not.
1942 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01001943LIBYANG_API_DECL LY_ERR lyd_compare_meta(const struct lyd_meta *meta1, const struct lyd_meta *meta2);
Michal Vasko21725742020-06-29 11:49:25 +02001944
1945/**
Radek Krejci22ebdba2019-07-25 13:59:43 +02001946 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02001947 * @defgroup dupoptions Data duplication options
Radek Krejci22ebdba2019-07-25 13:59:43 +02001948 *
Michal Vaskoe78faec2021-04-08 17:24:43 +02001949 * Various options to change ::lyd_dup_single() and ::lyd_dup_siblings() behavior.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001950 *
1951 * Default behavior:
1952 * - only the specified node is duplicated without siblings, parents, or children.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001953 * - all the metadata of the duplicated nodes are also duplicated.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001954 * @{
1955 */
1956
1957#define LYD_DUP_RECURSIVE 0x01 /**< Duplicate not just the node but also all the children. Note that
1958 list's keys are always duplicated. */
aPiecek6cf1d162023-11-08 16:07:00 +01001959#define LYD_DUP_NO_META 0x02 /**< Do not duplicate metadata (or attributes) of any node. Flag has no effect
1960 on 'lyds_tree' metadata. */
Radek Krejci22ebdba2019-07-25 13:59:43 +02001961#define LYD_DUP_WITH_PARENTS 0x04 /**< If a nested node is being duplicated, duplicate also all the parents.
1962 Keys are also duplicated for lists. Return value does not change! */
Michal Vasko3a41dff2020-07-15 14:30:28 +02001963#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 +02001964 its validation/default node state. */
Michal Vasko53ac4dd2022-06-07 10:56:08 +02001965#define LYD_DUP_NO_EXT 0x10 /**< Do not duplicate nodes with the ::LYD_EXT flag (nested extension instance data). */
Igor Ryzhov9e7af662023-10-31 13:27:56 +02001966#define LYD_DUP_WITH_PRIV 0x20 /**< Also copy data node private pointer. Only the pointer is copied, it still points
1967 to the same data. */
aPiecek1462ab12024-02-07 09:13:29 +01001968#define LYD_DUP_NO_LYDS 0x40 /**< The order of nodes is used the same as for copied nodes and a 'lyds_tree' is not
1969 created, so the flag is suitable for optimization. If a new node is inserted into
1970 such a (leaf-)list by default, the 'lyds_tree' will be created additionally and
1971 the sorting will work. */
Radek Krejci22ebdba2019-07-25 13:59:43 +02001972
1973/** @} dupoptions */
1974
1975/**
Michal Vaskoddd76592022-01-17 13:34:48 +01001976 * @brief Create a copy of the specified data tree @p node. Schema references are kept the same.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001977 *
Radek Krejci22ebdba2019-07-25 13:59:43 +02001978 * @param[in] node Data tree node to be duplicated.
Michal Vaskoddd76592022-01-17 13:34:48 +01001979 * @param[in] parent Optional parent node where to connect the duplicated node(s). If set in combination with
1980 * ::LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with @p parent.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001981 * @param[in] options Bitmask of options flags, see @ref dupoptions.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001982 * @param[out] dup Optional created copy of the node. Note that in case the parents chain is duplicated for the duplicated
Michal Vaskoddd76592022-01-17 13:34:48 +01001983 * node(s) (when ::LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001984 * @return LY_ERR value.
Radek Krejci22ebdba2019-07-25 13:59:43 +02001985 */
Michal Vaskoddd76592022-01-17 13:34:48 +01001986LIBYANG_API_DECL LY_ERR lyd_dup_single(const struct lyd_node *node, struct lyd_node_inner *parent, uint32_t options,
1987 struct lyd_node **dup);
Michal Vasko3a41dff2020-07-15 14:30:28 +02001988
1989/**
Michal Vaskoddd76592022-01-17 13:34:48 +01001990 * @brief Create a copy of the specified data tree @p node. Schema references are assigned from @p trg_ctx.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001991 *
1992 * @param[in] node Data tree node to be duplicated.
Michal Vaskoddd76592022-01-17 13:34:48 +01001993 * @param[in] trg_ctx Target context for duplicated nodes.
1994 * @param[in] parent Optional parent node where to connect the duplicated node(s). If set in combination with
1995 * ::LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with @p parent.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001996 * @param[in] options Bitmask of options flags, see @ref dupoptions.
1997 * @param[out] dup Optional created copy of the node. Note that in case the parents chain is duplicated for the duplicated
Michal Vaskoddd76592022-01-17 13:34:48 +01001998 * node(s) (when ::LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
Michal Vasko3a41dff2020-07-15 14:30:28 +02001999 * @return LY_ERR value.
2000 */
Michal Vaskoddd76592022-01-17 13:34:48 +01002001LIBYANG_API_DECL LY_ERR lyd_dup_single_to_ctx(const struct lyd_node *node, const struct ly_ctx *trg_ctx,
2002 struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup);
2003
2004/**
2005 * @brief Create a copy of the specified data tree @p node with any following siblings. Schema references are kept the same.
2006 *
2007 * @param[in] node Data tree node to be duplicated.
2008 * @param[in] parent Optional parent node where to connect the duplicated node(s). If set in combination with
2009 * ::LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with @p parent.
2010 * @param[in] options Bitmask of options flags, see @ref dupoptions.
2011 * @param[out] dup Optional created copy of the node. Note that in case the parents chain is duplicated for the duplicated
2012 * node(s) (when ::LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
2013 * @return LY_ERR value.
2014 */
2015LIBYANG_API_DECL LY_ERR lyd_dup_siblings(const struct lyd_node *node, struct lyd_node_inner *parent, uint32_t options,
2016 struct lyd_node **dup);
2017
2018/**
2019 * @brief Create a copy of the specified data tree @p node with any following siblings. Schema references are assigned
2020 * from @p trg_ctx.
2021 *
2022 * @param[in] node Data tree node to be duplicated.
2023 * @param[in] trg_ctx Target context for duplicated nodes.
2024 * @param[in] parent Optional parent node where to connect the duplicated node(s). If set in combination with
2025 * ::LYD_DUP_WITH_PARENTS, the missing parents' chain is duplicated and connected with @p parent.
2026 * @param[in] options Bitmask of options flags, see @ref dupoptions.
2027 * @param[out] dup Optional created copy of the node. Note that in case the parents chain is duplicated for the duplicated
2028 * node(s) (when ::LYD_DUP_WITH_PARENTS used), the first duplicated node is still returned.
2029 * @return LY_ERR value.
2030 */
2031LIBYANG_API_DECL LY_ERR lyd_dup_siblings_to_ctx(const struct lyd_node *node, const struct ly_ctx *trg_ctx,
2032 struct lyd_node_inner *parent, uint32_t options, struct lyd_node **dup);
Radek Krejci22ebdba2019-07-25 13:59:43 +02002033
2034/**
Michal Vasko25a32822020-07-09 15:48:22 +02002035 * @brief Create a copy of the metadata.
2036 *
2037 * @param[in] meta Metadata to copy.
Michal Vasko3a41dff2020-07-15 14:30:28 +02002038 * @param[in] parent Node where to append the new metadata.
2039 * @param[out] dup Optional created metadata copy.
2040 * @return LY_ERR value.
Michal Vasko25a32822020-07-09 15:48:22 +02002041 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002042LIBYANG_API_DECL LY_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 +02002043
2044/**
Michal Vasko4490d312020-06-16 13:08:55 +02002045 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02002046 * @defgroup mergeoptions Data merge options.
Radek Krejci576b23f2019-07-12 14:06:32 +02002047 *
Michal Vaskocd3f6172021-05-18 16:14:50 +02002048 * Various options to change ::lyd_merge_tree(), ::lyd_merge_siblings(), and ::lyd_merge_module() behavior.
Michal Vasko4490d312020-06-16 13:08:55 +02002049 *
2050 * Default behavior:
2051 * - source data tree is not modified in any way,
Michal Vasko745d6f62021-04-12 16:55:23 +02002052 * - any default nodes in the source are ignored if there are explicit nodes in the target,
2053 * - any metadata are ignored - those present in the target are kept, those in the source are not merged.
Michal Vasko7e8315b2021-08-03 17:01:06 +02002054 * - any merged nodes flags are set as non-validated.
Michal Vasko4490d312020-06-16 13:08:55 +02002055 * @{
2056 */
2057
2058#define LYD_MERGE_DESTRUCT 0x01 /**< Spend source data tree in the function, it cannot be used afterwards! */
Michal Vasko3a41dff2020-07-15 14:30:28 +02002059#define LYD_MERGE_DEFAULTS 0x02 /**< Default nodes in the source tree replace even explicit nodes in the target. */
Michal Vasko7e8315b2021-08-03 17:01:06 +02002060#define LYD_MERGE_WITH_FLAGS 0x04 /**< Merged nodes (those missing in the source) keep their exact flags. */
Michal Vasko4490d312020-06-16 13:08:55 +02002061
2062/** @} mergeoptions */
2063
2064/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02002065 * @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 +02002066 * is called on the resulting data tree (data from more cases may be present, default and non-default values).
2067 *
Michal Vasko2f510942020-11-13 10:26:25 +01002068 * Example input:
2069 *
2070 * source (A1) - A2 - A3 target (B1) - B2 - B3
2071 * /\ /\ /\ /\ /\ /\
2072 * .... .... .... .... .... ....
2073 *
2074 * result target (A1) - B1 - B2 - B3
2075 * /\ /\ /\ /\
2076 * .... .... .... ....
2077 *
Michal Vaskof922e8f2021-10-21 15:38:06 +02002078 * @param[in,out] target Target data tree to merge into, must be a top-level tree. Always points to the first sibling.
Michal Vasko4490d312020-06-16 13:08:55 +02002079 * @param[in] source Source data tree to merge, must be a top-level tree.
2080 * @param[in] options Bitmask of option flags, see @ref mergeoptions.
2081 * @return LY_SUCCESS on success,
2082 * @return LY_ERR value on error.
2083 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002084LIBYANG_API_DECL LY_ERR lyd_merge_tree(struct lyd_node **target, const struct lyd_node *source, uint16_t options);
Michal Vasko3a41dff2020-07-15 14:30:28 +02002085
2086/**
2087 * @brief Merge the source data tree with any following siblings into the target data tree. Merge may not be
2088 * complete until validation called on the resulting data tree (data from more cases may be present, default
2089 * and non-default values).
2090 *
Michal Vasko2f510942020-11-13 10:26:25 +01002091 * Example input:
2092 *
2093 * source (A1) - A2 - A3 target (B1) - B2 - B3
2094 * /\ /\ /\ /\ /\ /\
2095 * .... .... .... .... .... ....
2096 *
2097 * result target (A1) - A2 - A3 - B1 - B2 - B3
2098 * /\ /\ /\ /\ /\ /\
2099 * .... .... .... .... .... ....
2100 *
Michal Vaskof922e8f2021-10-21 15:38:06 +02002101 * @param[in,out] target Target data tree to merge into, must be a top-level tree. Always points to the first sibling.
Michal Vasko3a41dff2020-07-15 14:30:28 +02002102 * @param[in] source Source data tree to merge, must be a top-level tree.
2103 * @param[in] options Bitmask of option flags, see @ref mergeoptions.
2104 * @return LY_SUCCESS on success,
2105 * @return LY_ERR value on error.
2106 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002107LIBYANG_API_DECL LY_ERR lyd_merge_siblings(struct lyd_node **target, const struct lyd_node *source, uint16_t options);
Michal Vasko4490d312020-06-16 13:08:55 +02002108
2109/**
Michal Vaskocd3f6172021-05-18 16:14:50 +02002110 * @brief Callback for matching merge nodes.
2111 *
2112 * @param[in] trg_node Target data node.
2113 * @param[in] src_node Source data node, is NULL if it was actually duplicated (no target node found) and
2114 * its copy is @p trg_node.
2115 * @param[in] cb_data Arbitrary callback data.
2116 * @return LY_ERR value.
2117 */
2118typedef LY_ERR (*lyd_merge_cb)(struct lyd_node *trg_node, const struct lyd_node *src_node, void *cb_data);
2119
2120/**
2121 * @brief Merge all the nodes of a module from source data tree into the target data tree. Merge may not be
2122 * complete until validation called on the resulting data tree (data from more cases may be present, default
2123 * and non-default values).
2124 *
Michal Vaskof922e8f2021-10-21 15:38:06 +02002125 * @param[in,out] target Target data tree to merge into, must be a top-level tree. Always points to the first sibling.
Michal Vaskocd3f6172021-05-18 16:14:50 +02002126 * @param[in] source Source data tree to merge, must be a top-level tree.
2127 * @param[in] mod Module, whose source data only to consider, NULL for all modules.
Michal Vasko807557c2021-05-25 08:50:52 +02002128 * @param[in] merge_cb Optional merge callback that will be called for every merged node, before merging its descendants.
Michal Vaskocd3f6172021-05-18 16:14:50 +02002129 * If a subtree is being added into target (no matching node found), callback is called only once with the subtree root.
2130 * @param[in] cb_data Arbitrary callback data.
2131 * @param[in] options Bitmask of option flags, see @ref mergeoptions.
2132 * @return LY_SUCCESS on success,
2133 * @return LY_ERR value on error.
2134 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002135LIBYANG_API_DECL LY_ERR lyd_merge_module(struct lyd_node **target, const struct lyd_node *source, const struct lys_module *mod,
Michal Vaskocd3f6172021-05-18 16:14:50 +02002136 lyd_merge_cb merge_cb, void *cb_data, uint16_t options);
2137
2138/**
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002139 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +02002140 * @defgroup diffoptions Data diff options.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002141 *
Radek Krejci8678fa42020-08-18 16:07:28 +02002142 * Various options to change ::lyd_diff_tree() and ::lyd_diff_siblings() behavior.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002143 *
2144 * Default behavior:
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002145 * - any default nodes are treated as non-existent and ignored.
2146 * @{
2147 */
2148
Michal Vasko3a41dff2020-07-15 14:30:28 +02002149#define LYD_DIFF_DEFAULTS 0x01 /**< Default nodes in the trees are not ignored but treated similarly to explicit
2150 nodes. Also, leaves and leaf-lists are added into diff even in case only their
2151 default flag (state) was changed. */
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002152
2153/** @} diffoptions */
2154
2155/**
2156 * @brief Learn the differences between 2 data trees.
2157 *
2158 * The resulting diff is represented as a data tree with specific metadata from the internal 'yang'
2159 * module. Most importantly, every node has an effective 'operation' metadata. If there is none
2160 * defined on the node, it inherits the operation from the nearest parent. Top-level nodes must
2161 * always have the 'operation' metadata defined. Additional metadata ('orig-default', 'value',
2162 * 'orig-value', 'key', 'orig-key') are used for storing more information about the value in the first
2163 * or the second tree.
2164 *
2165 * The diff tree is completely independent on the @p first and @p second trees, meaning all
2166 * the information about the change is stored in the diff and the trees are not needed.
2167 *
Michal Vaskoff857812021-03-05 17:03:52 +01002168 * __!! Caution !!__
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002169 * The diff tree should never be validated because it may easily not be valid! For example,
2170 * when data from one case branch are deleted and data from another branch created - data from both
2171 * branches are then stored in the diff tree simultaneously.
2172 *
2173 * @param[in] first First data tree.
2174 * @param[in] second Second data tree.
2175 * @param[in] options Bitmask of options flags, see @ref diffoptions.
Michal Vaskoe2d52df2023-06-02 09:10:28 +02002176 * @param[out] diff Generated diff, NULL if there are no differences.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002177 * @return LY_SUCCESS on success,
2178 * @return LY_ERR on error.
2179 */
Michal Vasko55896172022-02-17 10:47:21 +01002180LIBYANG_API_DECL LY_ERR lyd_diff_tree(const struct lyd_node *first, const struct lyd_node *second, uint16_t options,
2181 struct lyd_node **diff);
Michal Vasko3a41dff2020-07-15 14:30:28 +02002182
2183/**
2184 * @brief Learn the differences between 2 data trees including all the following siblings.
2185 *
Michal Vaskoff857812021-03-05 17:03:52 +01002186 * Details are mentioned in ::lyd_diff_tree().
2187 *
Michal Vasko3a41dff2020-07-15 14:30:28 +02002188 * @param[in] first First data tree.
2189 * @param[in] second Second data tree.
2190 * @param[in] options Bitmask of options flags, see @ref diffoptions.
Michal Vaskoe2d52df2023-06-02 09:10:28 +02002191 * @param[out] diff Generated diff, NULL if there are no differences.
Michal Vasko3a41dff2020-07-15 14:30:28 +02002192 * @return LY_SUCCESS on success,
2193 * @return LY_ERR on error.
2194 */
Michal Vasko55896172022-02-17 10:47:21 +01002195LIBYANG_API_DECL LY_ERR lyd_diff_siblings(const struct lyd_node *first, const struct lyd_node *second, uint16_t options,
2196 struct lyd_node **diff);
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002197
2198/**
2199 * @brief Callback for diff nodes.
2200 *
2201 * @param[in] diff_node Diff node.
2202 * @param[in] data_node Matching node in data.
2203 * @param[in] cb_data Arbitrary callback data.
2204 * @return LY_ERR value.
2205 */
2206typedef LY_ERR (*lyd_diff_cb)(const struct lyd_node *diff_node, struct lyd_node *data_node, void *cb_data);
2207
2208/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02002209 * @brief Apply the whole diff on a data tree but restrict the operation to one module.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002210 *
Michal Vaskoa98dcba2021-03-05 17:04:14 +01002211 * __!! Caution !!__
2212 * If applying a diff that was created __without__ the ::LYD_DIFF_DEFAULTS flag, there may be some duplicate values
2213 * created. Unless the resulting tree is validated (and default values thus consolidated), using it further
2214 * (such as applying another diff) may cause unexpected results or errors.
2215 *
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002216 * @param[in,out] data Data to apply the diff on.
2217 * @param[in] diff Diff to apply.
2218 * @param[in] mod Module, whose diff/data only to consider, NULL for all modules.
2219 * @param[in] diff_cb Optional diff callback that will be called for every changed node.
2220 * @param[in] cb_data Arbitrary callback data.
2221 * @return LY_SUCCESS on success,
2222 * @return LY_ERR on error.
2223 */
Michal Vasko55896172022-02-17 10:47:21 +01002224LIBYANG_API_DECL LY_ERR lyd_diff_apply_module(struct lyd_node **data, const struct lyd_node *diff,
2225 const struct lys_module *mod, lyd_diff_cb diff_cb, void *cb_data);
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002226
2227/**
Michal Vasko3a41dff2020-07-15 14:30:28 +02002228 * @brief Apply the whole diff tree on a data tree.
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002229 *
Michal Vaskoff857812021-03-05 17:03:52 +01002230 * Details are mentioned in ::lyd_diff_apply_module().
2231 *
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002232 * @param[in,out] data Data to apply the diff on.
2233 * @param[in] diff Diff to apply.
2234 * @return LY_SUCCESS on success,
2235 * @return LY_ERR on error.
2236 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002237LIBYANG_API_DECL LY_ERR lyd_diff_apply_all(struct lyd_node **data, const struct lyd_node *diff);
Michal Vaskoe893ddd2020-06-23 13:35:20 +02002238
2239/**
Michal Vaskoc0e58e82020-11-11 19:04:33 +01002240 * @ingroup datatree
2241 * @defgroup diffmergeoptions Data diff merge options.
2242 *
2243 * Various options to change ::lyd_diff_merge_module(), ::lyd_diff_merge_tree(), and ::lyd_diff_merge_all() behavior.
2244 *
2245 * Default behavior:
2246 * - any default nodes are expected to be a result of validation corrections and not explicitly modified.
2247 * @{
2248 */
2249
2250#define LYD_DIFF_MERGE_DEFAULTS 0x01 /**< Default nodes in the diffs are treated as possibly explicitly modified. */
2251
Michal Vaskoff857812021-03-05 17:03:52 +01002252/** @} diffmergeoptions */
Michal Vaskoc0e58e82020-11-11 19:04:33 +01002253
2254/**
Michal Vaskoe6323f62020-07-09 15:49:02 +02002255 * @brief Merge 2 diffs into each other but restrict the operation to one module.
2256 *
2257 * The diffs must be possible to be merged, which is guaranteed only if the source diff was
2258 * created on data that had the target diff applied on them. In other words, this sequence is legal
2259 *
Michal Vaskoff857812021-03-05 17:03:52 +01002260 * 1) get diff1 from data1 and data2 -> get data11 from apply diff1 on data1 -> get diff2 from data11 and data3 ->
2261 * -> get data 33 from apply diff2 on data1
Michal Vaskoe6323f62020-07-09 15:49:02 +02002262 *
2263 * and reusing these diffs
2264 *
Michal Vaskoff857812021-03-05 17:03:52 +01002265 * 2) get diff11 from merge diff1 and diff2 -> get data33 from apply diff11 on data1
Michal Vaskoe6323f62020-07-09 15:49:02 +02002266 *
Michal Vaskofb737aa2020-08-06 13:53:53 +02002267 * @param[in,out] diff Target diff to merge into.
Michal Vaskoe6323f62020-07-09 15:49:02 +02002268 * @param[in] src_diff Source diff.
2269 * @param[in] mod Module, whose diff only to consider, NULL for all modules.
Michal Vaskoe2af8412020-12-03 14:11:38 +01002270 * @param[in] diff_cb Optional diff callback that will be called for every merged node. Param @p diff_node is the source
2271 * diff node while @p data_node is the updated target diff node. In case a whole subtree is added, the callback is
2272 * called on the root with @p diff_node being NULL.
Michal Vaskoe6323f62020-07-09 15:49:02 +02002273 * @param[in] cb_data Arbitrary callback data.
Michal Vaskoc0e58e82020-11-11 19:04:33 +01002274 * @param[in] options Bitmask of options flags, see @ref diffmergeoptions.
Michal Vaskoe6323f62020-07-09 15:49:02 +02002275 * @return LY_SUCCESS on success,
2276 * @return LY_ERR on error.
2277 */
Michal Vasko55896172022-02-17 10:47:21 +01002278LIBYANG_API_DECL LY_ERR lyd_diff_merge_module(struct lyd_node **diff, const struct lyd_node *src_diff,
2279 const struct lys_module *mod, lyd_diff_cb diff_cb, void *cb_data, uint16_t options);
Michal Vaskoe6323f62020-07-09 15:49:02 +02002280
2281/**
Michal Vasko04f85912020-08-07 12:14:58 +02002282 * @brief Merge 2 diff trees into each other.
2283 *
Michal Vaskoff857812021-03-05 17:03:52 +01002284 * Details are mentioned in ::lyd_diff_merge_module().
2285 *
Michal Vasko04f85912020-08-07 12:14:58 +02002286 * @param[in,out] diff_first Target diff first sibling to merge into.
2287 * @param[in] diff_parent Target diff parent to merge into.
2288 * @param[in] src_sibling Source diff sibling to merge.
Michal Vaskoe2af8412020-12-03 14:11:38 +01002289 * @param[in] diff_cb Optional diff callback that will be called for every merged node. Param @p diff_node is the source
2290 * diff node while @p data_node is the updated target diff node. In case a whole subtree is added, the callback is
2291 * called on the root with @p diff_node being NULL.
Michal Vasko04f85912020-08-07 12:14:58 +02002292 * @param[in] cb_data Arbitrary callback data.
Michal Vaskoc0e58e82020-11-11 19:04:33 +01002293 * @param[in] options Bitmask of options flags, see @ref diffmergeoptions.
Michal Vasko04f85912020-08-07 12:14:58 +02002294 * @return LY_SUCCESS on success,
2295 * @return LY_ERR on error.
2296 */
Michal Vasko55896172022-02-17 10:47:21 +01002297LIBYANG_API_DECL LY_ERR lyd_diff_merge_tree(struct lyd_node **diff_first, struct lyd_node *diff_parent,
2298 const struct lyd_node *src_sibling, lyd_diff_cb diff_cb, void *cb_data, uint16_t options);
Michal Vasko04f85912020-08-07 12:14:58 +02002299
2300/**
Michal Vaskoe6323f62020-07-09 15:49:02 +02002301 * @brief Merge 2 diffs into each other.
2302 *
Michal Vaskoff857812021-03-05 17:03:52 +01002303 * Details are mentioned in ::lyd_diff_merge_module().
2304 *
Michal Vaskoe6323f62020-07-09 15:49:02 +02002305 * @param[in,out] diff Target diff to merge into.
Michal Vaskofb737aa2020-08-06 13:53:53 +02002306 * @param[in] src_diff Source diff.
Michal Vaskoc0e58e82020-11-11 19:04:33 +01002307 * @param[in] options Bitmask of options flags, see @ref diffmergeoptions.
Michal Vaskoe6323f62020-07-09 15:49:02 +02002308 * @return LY_SUCCESS on success,
2309 * @return LY_ERR on error.
2310 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002311LIBYANG_API_DECL LY_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 +02002312
2313/**
Michal Vasko4231fb62020-07-13 13:54:47 +02002314 * @brief Reverse a diff and make the opposite changes. Meaning change create to delete, delete to create,
2315 * or move from place A to B to move from B to A and so on.
2316 *
2317 * @param[in] src_diff Diff to reverse.
2318 * @param[out] diff Reversed diff.
2319 * @return LY_SUCCESS on success.
2320 * @return LY_ERR on error.
2321 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002322LIBYANG_API_DECL LY_ERR lyd_diff_reverse_all(const struct lyd_node *src_diff, struct lyd_node **diff);
Michal Vasko4231fb62020-07-13 13:54:47 +02002323
2324/**
Michal Vasko5ec7cda2019-09-11 13:43:08 +02002325 * @brief Types of the different data paths.
2326 */
2327typedef enum {
Radek Krejci635d2b82021-01-04 11:26:51 +01002328 LYD_PATH_STD, /**< Generic data path used for logging, node searching (::lyd_find_xpath(), ::lys_find_path()) as well as
Radek Krejci95ccd1b2021-03-12 14:57:22 +01002329 creating new nodes (::lyd_new_path(), ::lyd_new_path2(), ::lyd_new_ext_path()). */
Radek Krejci635d2b82021-01-04 11:26:51 +01002330 LYD_PATH_STD_NO_LAST_PRED /**< Similar to ::LYD_PATH_STD except there is never a predicate on the last node. While it
2331 can be used to search for nodes, do not use it to create new data nodes (lists). */
Michal Vasko5ec7cda2019-09-11 13:43:08 +02002332} LYD_PATH_TYPE;
2333
2334/**
2335 * @brief Generate path of the given node in the requested format.
2336 *
Jan Kundrátb5a113c2023-03-01 16:30:46 +01002337 * The path is constructed based on the parent node(s) of this node. When run on a node which is disconnected
2338 * from its parent(s), this function might yield unexpected results such as `/example:b` instead of the expected
2339 * `/example:a/b`.
2340 *
Radek Krejci635d2b82021-01-04 11:26:51 +01002341 * @param[in] node Data path of this node will be generated.
Michal Vasko5ec7cda2019-09-11 13:43:08 +02002342 * @param[in] pathtype Format of the path to generate.
2343 * @param[in,out] buffer Prepared buffer of the @p buflen length to store the generated path.
2344 * If NULL, memory for the complete path is allocated.
2345 * @param[in] buflen Size of the provided @p buffer.
2346 * @return NULL in case of memory allocation error, path of the node otherwise.
2347 * In case the @p buffer is NULL, the returned string is dynamically allocated and caller is responsible to free it.
2348 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002349LIBYANG_API_DECL char *lyd_path(const struct lyd_node *node, LYD_PATH_TYPE pathtype, char *buffer, size_t buflen);
Michal Vasko5ec7cda2019-09-11 13:43:08 +02002350
Michal Vaskoe444f752020-02-10 12:20:06 +01002351/**
Michal Vasko25a32822020-07-09 15:48:22 +02002352 * @brief Find a specific metadata.
2353 *
2354 * @param[in] first First metadata to consider.
2355 * @param[in] module Module of the metadata definition, may be NULL if @p name includes a prefix.
2356 * @param[in] name Name of the metadata to find, may not include a prefix (module name) if @p module is set.
2357 * @return Found metadata,
2358 * @return NULL if not found.
2359 */
Michal Vaskoddd76592022-01-17 13:34:48 +01002360LIBYANG_API_DECL struct lyd_meta *lyd_find_meta(const struct lyd_meta *first, const struct lys_module *module,
2361 const char *name);
Michal Vasko25a32822020-07-09 15:48:22 +02002362
2363/**
Michal Vaskoda859032020-07-14 12:20:14 +02002364 * @brief Search in the given siblings (NOT recursively) for the first target instance with the same value.
Michal Vaskoe444f752020-02-10 12:20:06 +01002365 * Uses hashes - should be used whenever possible for best performance.
2366 *
2367 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
2368 * @param[in] target Target node to find.
Michal Vasko9b368d32020-02-14 13:53:31 +01002369 * @param[out] match Can be NULL, otherwise the found data node.
Michal Vaskoe444f752020-02-10 12:20:06 +01002370 * @return LY_SUCCESS on success, @p match set.
2371 * @return LY_ENOTFOUND if not found, @p match set to NULL.
2372 * @return LY_ERR value if another error occurred.
2373 */
Michal Vaskoddd76592022-01-17 13:34:48 +01002374LIBYANG_API_DECL LY_ERR lyd_find_sibling_first(const struct lyd_node *siblings, const struct lyd_node *target,
2375 struct lyd_node **match);
Michal Vaskoe444f752020-02-10 12:20:06 +01002376
2377/**
Michal Vaskoe444f752020-02-10 12:20:06 +01002378 * @brief Search in the given siblings for the first schema instance.
2379 * Uses hashes - should be used whenever possible for best performance.
2380 *
2381 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
2382 * @param[in] schema Schema node of the data node to find.
Michal Vaskob104f112020-07-17 09:54:54 +02002383 * @param[in] key_or_value If it is NULL, the first schema node data instance is found. For nodes with many
2384 * instances, it can be set based on the type of @p schema:
Michal Vaskoe444f752020-02-10 12:20:06 +01002385 * LYS_LEAFLIST:
2386 * Searched instance value.
2387 * LYS_LIST:
Michal Vasko90932a92020-02-12 14:33:03 +01002388 * Searched instance key values in the form of "[key1='val1'][key2='val2']...".
2389 * The keys do not have to be ordered but all of them must be set.
2390 *
2391 * Note that any explicit values (leaf-list or list key values) will be canonized first
2392 * before comparison. But values that do not have a canonical value are expected to be in the
2393 * JSON format!
Michal Vaskof03ed032020-03-04 13:31:44 +01002394 * @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 +01002395 * @param[out] match Can be NULL, otherwise the found data node.
Michal Vaskoe444f752020-02-10 12:20:06 +01002396 * @return LY_SUCCESS on success, @p match set.
2397 * @return LY_ENOTFOUND if not found, @p match set to NULL.
2398 * @return LY_EINVAL if @p schema is a key-less list.
2399 * @return LY_ERR value if another error occurred.
2400 */
Michal Vaskoddd76592022-01-17 13:34:48 +01002401LIBYANG_API_DECL LY_ERR lyd_find_sibling_val(const struct lyd_node *siblings, const struct lysc_node *schema,
2402 const char *key_or_value, size_t val_len, struct lyd_node **match);
Michal Vaskoe444f752020-02-10 12:20:06 +01002403
Michal Vaskoccc02342020-05-21 10:09:21 +02002404/**
Michal Vasko83ae7772022-06-08 10:01:55 +02002405 * @brief Search the given siblings for all the exact same instances of a specific node instance.
2406 * Uses hashes to whatever extent possible.
Michal Vaskoe78faec2021-04-08 17:24:43 +02002407 *
2408 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
2409 * @param[in] target Target node instance to find.
2410 * @param[out] set Set with all the found instances. The first item is always the first instance.
2411 * @return LY_SUCCESS on success, @p set returned.
2412 * @return LY_ENOTFOUND if not found, empty @p set returned.
2413 * @return LY_ERR value if another error occurred.
2414 */
Michal Vaskoddd76592022-01-17 13:34:48 +01002415LIBYANG_API_DECL LY_ERR lyd_find_sibling_dup_inst_set(const struct lyd_node *siblings, const struct lyd_node *target,
2416 struct ly_set **set);
Michal Vaskoe78faec2021-04-08 17:24:43 +02002417
2418/**
Michal Vasko1d4af6c2021-02-22 13:31:26 +01002419 * @brief Search the given siblings for an opaque node with a specific name.
2420 *
2421 * @param[in] first First sibling to consider.
2422 * @param[in] name Opaque node name to find.
2423 * @param[out] match Can be NULL, otherwise the found data node.
2424 * @return LY_SUCCESS on success, @p match set.
2425 * @return LY_ENOTFOUND if not found, @p match set to NULL.
2426 * @return LY_ERR value is an error occurred.
2427 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002428LIBYANG_API_DECL LY_ERR lyd_find_sibling_opaq_next(const struct lyd_node *first, const char *name, struct lyd_node **match);
Michal Vasko1d4af6c2021-02-22 13:31:26 +01002429
2430/**
aPiecekdf23eee2021-10-07 12:21:50 +02002431 * @brief Set a new XPath variable to @p vars.
2432 *
2433 * @param[in,out] vars Pointer to [sized array](@ref sizedarrays) of XPath variables.
2434 * To create a new array, set the @p vars target pointer to NULL.
2435 * Otherwise variable named @p name with a value @p value will be added to the @p vars
2436 * or its value will be changed if the variable is already defined.
2437 * @param[in] name Name of the added/edited variable.
2438 * @param[in] value Value of the variable.
2439 * @return LY_ERR value.
2440 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002441LIBYANG_API_DECL LY_ERR lyxp_vars_set(struct lyxp_var **vars, const char *name, const char *value);
aPiecekdf23eee2021-10-07 12:21:50 +02002442
2443/**
2444 * @brief Free the XPath variables.
2445 *
2446 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
2447 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002448LIBYANG_API_DECL void lyxp_vars_free(struct lyxp_var *vars);
aPiecekdf23eee2021-10-07 12:21:50 +02002449
2450/**
Michal Vaskoccc02342020-05-21 10:09:21 +02002451 * @brief Search in the given data for instances of nodes matching the provided XPath.
2452 *
Michal Vasko3f631cd2022-08-08 14:35:32 +02002453 * If a list instance is being selected with all its key values specified and ordered
2454 * in the form `list[key1=...][key2=...][key3=...]` or a leaf-list instance in the form
2455 * `leaf-list[.=...]`, these instances are found using hashes with constant (*O(1)*) complexity
Michal Vasko19a30602020-05-25 10:40:19 +02002456 * (unless they are defined in top-level). Other predicates can still follow the aforementioned ones.
2457 *
Michal Vaskofbd0da42023-08-17 14:57:44 +02002458 * Opaque nodes are part of the evaluation.
2459 *
Michal Vaskoccc02342020-05-21 10:09:21 +02002460 * @param[in] ctx_node XPath context node.
Michal Vaskoc0d91642022-11-03 13:56:29 +01002461 * @param[in] xpath [XPath](@ref howtoXPath) to select in JSON format. It must evaluate into a node set.
Michal Vaskoccc02342020-05-21 10:09:21 +02002462 * @param[out] set Set of found data nodes. In case the result is a number, a string, or a boolean,
2463 * the returned set is empty.
2464 * @return LY_SUCCESS on success, @p set is returned.
2465 * @return LY_ERR value if an error occurred.
2466 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002467LIBYANG_API_DECL LY_ERR lyd_find_xpath(const struct lyd_node *ctx_node, const char *xpath, struct ly_set **set);
Michal Vaskoccc02342020-05-21 10:09:21 +02002468
Michal Vasko3e1f6552021-01-14 09:27:55 +01002469/**
aPiecekfba75362021-10-07 12:39:48 +02002470 * @brief Search in the given data for instances of nodes matching the provided XPath.
2471 *
Michal Vasko10fabfc2022-08-09 08:55:43 +02002472 * It is ::lyd_find_xpath() with @p vars added.
aPiecekfba75362021-10-07 12:39:48 +02002473 *
2474 * @param[in] ctx_node XPath context node.
Michal Vaskoddd76592022-01-17 13:34:48 +01002475 * @param[in] xpath [XPath](@ref howtoXPath) to select in JSON format.
aPiecekfba75362021-10-07 12:39:48 +02002476 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
2477 * @param[out] set Set of found data nodes. In case the result is a number, a string, or a boolean,
2478 * the returned set is empty.
2479 * @return LY_SUCCESS on success, @p set is returned.
2480 * @return LY_ERR value if an error occurred.
2481 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002482LIBYANG_API_DECL LY_ERR lyd_find_xpath2(const struct lyd_node *ctx_node, const char *xpath, const struct lyxp_var *vars,
Michal Vaskoe3716b32021-12-13 16:58:25 +01002483 struct ly_set **set);
2484
2485/**
2486 * @brief Search in the given data for instances of nodes matching the provided XPath.
2487 *
Michal Vaskobe1b0cb2024-01-22 14:32:15 +01002488 * It is ::lyd_find_xpath2() with @p tree added so that @p ctx_node may be the root and
2489 * also @p format and @p prefix_data added for expressions in different formats than JSON.
Michal Vaskoe3716b32021-12-13 16:58:25 +01002490 *
2491 * @param[in] ctx_node XPath context node, NULL for the root node.
2492 * @param[in] tree Data tree to evaluate on.
Michal Vaskobe1b0cb2024-01-22 14:32:15 +01002493 * @param[in] xpath [XPath](@ref howtoXPath) to select with prefixes in @p format.
Michal Vaskoddd76592022-01-17 13:34:48 +01002494 * @param[in] format Format of any prefixes in @p xpath.
2495 * @param[in] prefix_data Format-specific prefix data.
2496 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
2497 * @param[out] set Set of found data nodes. In case the result is a number, a string, or a boolean,
2498 * the returned set is empty.
2499 * @return LY_SUCCESS on success, @p set is returned.
2500 * @return LY_ERR value if an error occurred.
2501 */
Michal Vaskobe1b0cb2024-01-22 14:32:15 +01002502LIBYANG_API_DECL LY_ERR lyd_find_xpath3(const struct lyd_node *ctx_node, const struct lyd_node *tree, const char *xpath,
Michal Vaskoddd76592022-01-17 13:34:48 +01002503 LY_VALUE_FORMAT format, void *prefix_data, const struct lyxp_var *vars, struct ly_set **set);
2504
2505/**
Michal Vaskoc9eb3ca2021-07-16 10:20:37 +02002506 * @brief Evaluate an XPath on data and return the result converted to boolean.
2507 *
2508 * Optimizations similar as in ::lyd_find_xpath().
2509 *
2510 * @param[in] ctx_node XPath context node.
Michal Vaskobe1b0cb2024-01-22 14:32:15 +01002511 * @param[in] xpath [XPath](@ref howtoXPath) to select in JSON format.
Michal Vasko080155c2021-10-14 09:22:16 +02002512 * @param[out] result Expression result converted to boolean.
Michal Vaskoc9eb3ca2021-07-16 10:20:37 +02002513 * @return LY_SUCCESS on success, @p result is returned.
2514 * @return LY_ERR value if an error occurred.
2515 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002516LIBYANG_API_DECL LY_ERR lyd_eval_xpath(const struct lyd_node *ctx_node, const char *xpath, ly_bool *result);
Michal Vaskoc9eb3ca2021-07-16 10:20:37 +02002517
2518/**
aPiecekfba75362021-10-07 12:39:48 +02002519 * @brief Evaluate an XPath on data and return the result converted to boolean.
2520 *
Michal Vasko10fabfc2022-08-09 08:55:43 +02002521 * It is ::lyd_eval_xpath() with @p vars added.
aPiecekfba75362021-10-07 12:39:48 +02002522 *
2523 * @param[in] ctx_node XPath context node.
Michal Vaskobe1b0cb2024-01-22 14:32:15 +01002524 * @param[in] xpath [XPath](@ref howtoXPath) to select in JSON format.
aPiecekfba75362021-10-07 12:39:48 +02002525 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
Michal Vasko080155c2021-10-14 09:22:16 +02002526 * @param[out] result Expression result converted to boolean.
aPiecekfba75362021-10-07 12:39:48 +02002527 * @return LY_SUCCESS on success, @p result is returned.
2528 * @return LY_ERR value if an error occurred.
2529 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002530LIBYANG_API_DECL LY_ERR lyd_eval_xpath2(const struct lyd_node *ctx_node, const char *xpath,
aPiecekfba75362021-10-07 12:39:48 +02002531 const struct lyxp_var *vars, ly_bool *result);
2532
2533/**
Michal Vasko10fabfc2022-08-09 08:55:43 +02002534 * @brief Evaluate an XPath on data and return the result converted to boolean.
2535 *
2536 * It is ::lyd_eval_xpath2() with @p format and @p prefix_data added for special use-cases.
2537 *
2538 * @param[in] ctx_node XPath context node.
2539 * @param[in] cur_mod Current module of @p xpath, needed for some kinds of @p format.
Michal Vaskobe1b0cb2024-01-22 14:32:15 +01002540 * @param[in] xpath [XPath](@ref howtoXPath) to select with prefixes in in @p format.
Michal Vasko10fabfc2022-08-09 08:55:43 +02002541 * @param[in] format Format of any prefixes in @p xpath.
2542 * @param[in] prefix_data Format-specific prefix data.
2543 * @param[in] vars [Sized array](@ref sizedarrays) of XPath variables.
2544 * @param[out] result Expression result converted to boolean.
2545 * @return LY_SUCCESS on success, @p result is returned.
2546 * @return LY_ERR value if an error occurred.
2547 */
2548LIBYANG_API_DECL LY_ERR lyd_eval_xpath3(const struct lyd_node *ctx_node, const struct lys_module *cur_mod,
2549 const char *xpath, LY_VALUE_FORMAT format, void *prefix_data, const struct lyxp_var *vars, ly_bool *result);
2550
2551/**
Michal Vaskod96e2372023-02-24 16:07:51 +01002552 * @brief XPath result type.
2553 */
2554typedef enum {
2555 LY_XPATH_NODE_SET, /**< XPath node set */
2556 LY_XPATH_STRING, /**< XPath string */
2557 LY_XPATH_NUMBER, /**< XPath number */
2558 LY_XPATH_BOOLEAN /**< XPath boolean */
2559} LY_XPATH_TYPE;
2560
2561/**
2562 * @brief Evaluate an XPath on data and return the result or convert it first to an expected result type.
2563 *
2564 * Either all return type parameters @p node_set, @p string, @p number, and @p boolean with @p ret_type
2565 * are provided or exactly one of @p node_set, @p string, @p number, and @p boolean is provided with @p ret_type
2566 * being obvious and hence optional.
2567 *
2568 * @param[in] ctx_node XPath context node, NULL for the root node.
2569 * @param[in] tree Data tree to evaluate on.
2570 * @param[in] cur_mod Current module of @p xpath, needed for some kinds of @p format.
2571 * @param[in] xpath [XPath](@ref howtoXPath) to select.
2572 * @param[in] format Format of any prefixes in @p xpath.
2573 * @param[in] prefix_data Format-specific prefix data.
2574 * @param[in] vars Optional [sized array](@ref sizedarrays) of XPath variables.
2575 * @param[out] ret_type XPath type of the result selecting which of @p node_set, @p string, @p number, and @p boolean to use.
2576 * @param[out] node_set XPath node set result.
2577 * @param[out] string XPath string result.
2578 * @param[out] number XPath number result.
2579 * @param[out] boolean XPath boolean result.
2580 * @return LY_SUCCESS on success.
2581 * @return LY_ERR value on error.
2582 */
2583LIBYANG_API_DECL LY_ERR lyd_eval_xpath4(const struct lyd_node *ctx_node, const struct lyd_node *tree,
2584 const struct lys_module *cur_mod, const char *xpath, LY_VALUE_FORMAT format, void *prefix_data,
2585 const struct lyxp_var *vars, LY_XPATH_TYPE *ret_type, struct ly_set **node_set, char **string,
2586 long double *number, ly_bool *boolean);
2587
2588/**
Michal Vasko99a77882024-01-04 14:50:51 +01002589 * @brief Evaluate an XPath on data and free all the nodes except the subtrees selected by the expression.
2590 *
2591 * @param[in,out] tree Data tree to evaluate on and trim.
2592 * @param[in] xpath [XPath](@ref howtoXPath) to select in JSON format.
2593 * @param[in] vars Optional [sized array](@ref sizedarrays) of XPath variables.
2594 * @return LY_SUCCESS on success.
2595 * @return LY_ERR value on error.
2596 */
2597LIBYANG_API_DEF LY_ERR lyd_trim_xpath(struct lyd_node **tree, const char *xpath, const struct lyxp_var *vars);
2598
2599/**
Michal Vaskoc84c9962021-05-18 16:16:29 +02002600 * @brief Search in given data for a node uniquely identified by a path.
Michal Vasko3e1f6552021-01-14 09:27:55 +01002601 *
Michal Vasko257bdcf2021-01-14 13:15:30 +01002602 * Always works in constant (*O(1)*) complexity. To be exact, it is *O(n)* where *n* is the depth
2603 * of the path used.
2604 *
Michal Vaskofbd0da42023-08-17 14:57:44 +02002605 * Opaque nodes are NEVER found/traversed.
2606 *
Michal Vasko3e1f6552021-01-14 09:27:55 +01002607 * @param[in] ctx_node Path context node.
2608 * @param[in] path [Path](@ref howtoXPath) to find.
2609 * @param[in] output Whether to search in RPC/action output nodes or in input nodes.
2610 * @param[out] match Can be NULL, otherwise the found data node.
2611 * @return LY_SUCCESS on success, @p match is set to the found node.
2612 * @return LY_EINCOMPLETE if only a parent of the node was found, @p match is set to this parent node.
2613 * @return LY_ENOTFOUND if no nodes in the path were found.
2614 * @return LY_ERR on other errors.
2615 */
Michal Vasko55896172022-02-17 10:47:21 +01002616LIBYANG_API_DECL LY_ERR lyd_find_path(const struct lyd_node *ctx_node, const char *path, ly_bool output,
2617 struct lyd_node **match);
Michal Vasko3e1f6552021-01-14 09:27:55 +01002618
Michal Vasko43297a02021-05-19 11:12:37 +02002619/**
Michal Vaskobb22b182021-06-14 08:14:21 +02002620 * @brief Find the target node of a compiled path (::lyd_value instance-identifier).
2621 *
2622 * @param[in] path Compiled path structure.
2623 * @param[in] tree Data tree to be searched.
2624 * @param[out] match Can be NULL, otherwise the found data node.
2625 * @return LY_SUCCESS on success, @p match is set to the found node.
2626 * @return LY_ENOTFOUND if no match was found.
2627 * @return LY_ERR on other errors.
2628 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002629LIBYANG_API_DECL LY_ERR lyd_find_target(const struct ly_path *path, const struct lyd_node *tree, struct lyd_node **match);
Michal Vaskobb22b182021-06-14 08:14:21 +02002630
2631/**
Michal Vasko9b560332023-04-24 15:43:56 +02002632 * @brief Get current timezone (including DST setting) UTC (GMT) time offset in seconds.
Michal Vaskof17bb2a2023-02-10 11:34:55 +01002633 *
2634 * @return Timezone shift in seconds.
2635 */
2636LIBYANG_API_DECL int ly_time_tz_offset(void);
2637
2638/**
Michal Vasko9b560332023-04-24 15:43:56 +02002639 * @brief Get UTC (GMT) timezone offset in seconds at a specific timestamp (including DST setting).
2640 *
2641 * @param[in] time Timestamp to get the offset at.
2642 * @return Timezone shift in seconds.
2643 */
2644LIBYANG_API_DECL int ly_time_tz_offset_at(time_t time);
2645
2646/**
Michal Vasko43297a02021-05-19 11:12:37 +02002647 * @brief Convert date-and-time from string to UNIX timestamp and fractions of a second.
2648 *
2649 * @param[in] value Valid string date-and-time value.
2650 * @param[out] time UNIX timestamp.
2651 * @param[out] fractions_s Optional fractions of a second, set to NULL if none.
2652 * @return LY_ERR value.
2653 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002654LIBYANG_API_DECL LY_ERR ly_time_str2time(const char *value, time_t *time, char **fractions_s);
Michal Vasko43297a02021-05-19 11:12:37 +02002655
2656/**
2657 * @brief Convert UNIX timestamp and fractions of a second into canonical date-and-time string value.
2658 *
2659 * @param[in] time UNIX timestamp.
2660 * @param[in] fractions_s Fractions of a second, if any.
Michal Vaskoc515a2b2021-05-19 11:55:00 +02002661 * @param[out] str String date-and-time value in the local timezone.
Michal Vasko43297a02021-05-19 11:12:37 +02002662 * @return LY_ERR value.
2663 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002664LIBYANG_API_DECL LY_ERR ly_time_time2str(time_t time, const char *fractions_s, char **str);
Michal Vasko43297a02021-05-19 11:12:37 +02002665
2666/**
2667 * @brief Convert date-and-time from string to timespec.
2668 *
2669 * @param[in] value Valid string date-and-time value.
2670 * @param[out] ts Timespec.
2671 * @return LY_ERR value.
2672 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002673LIBYANG_API_DECL LY_ERR ly_time_str2ts(const char *value, struct timespec *ts);
Michal Vasko43297a02021-05-19 11:12:37 +02002674
2675/**
2676 * @brief Convert timespec into date-and-time string value.
2677 *
2678 * @param[in] ts Timespec.
Michal Vaskoc515a2b2021-05-19 11:55:00 +02002679 * @param[out] str String date-and-time value in the local timezone.
Michal Vasko43297a02021-05-19 11:12:37 +02002680 * @return LY_ERR value.
2681 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +01002682LIBYANG_API_DECL LY_ERR ly_time_ts2str(const struct timespec *ts, char **str);
Michal Vasko43297a02021-05-19 11:12:37 +02002683
stewegf9041a22024-01-18 13:29:12 +01002684/**
2685 * @brief Gets the leafref links record for given node
2686 *
Michal Vaskoeeec27a2024-01-22 14:32:34 +01002687 * This API requires usage of ::LY_CTX_LEAFREF_LINKING context flag.
stewegf9041a22024-01-18 13:29:12 +01002688 *
2689 * @param[in] node The term data node.
2690 * @param[out] record The leafref links record
2691 * @return LY_SUCCESS on success.
2692 * @return LY_ERR value on error.
2693 */
2694LIBYANG_API_DECL LY_ERR lyd_leafref_get_links(const struct lyd_node_term *node, const struct lyd_leafref_links_rec **record);
2695
2696/**
2697 * @brief Traverse through data tree including root node siblings and adds leafrefs links to the given nodes
2698 *
Michal Vaskoeeec27a2024-01-22 14:32:34 +01002699 * This API requires usage of ::LY_CTX_LEAFREF_LINKING context flag.
stewegf9041a22024-01-18 13:29:12 +01002700 *
2701 * @param[in] tree The data tree root node.
2702 * @return LY_SUCCESS on success.
2703 * @return LY_ERR value on error.
2704 */
2705LIBYANG_API_DECL LY_ERR lyd_leafref_link_node_tree(const struct lyd_node *tree);
2706
Radek Krejcie7b95092019-05-15 11:03:07 +02002707#ifdef __cplusplus
2708}
2709#endif
2710
2711#endif /* LY_TREE_DATA_H_ */