blob: 2f8411d4ac851241094ffd2b398d1431726cbe07 [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
2 * @file tree_data.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief libyang representation of YANG data trees.
5 *
6 * Copyright (c) 2015 - 2019 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_TREE_DATA_H_
16#define LY_TREE_DATA_H_
17
18#include <stddef.h>
19#include <stdint.h>
20
21#include "log.h"
Michal Vasko9b368d32020-02-14 13:53:31 +010022#include "set.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020023#include "tree.h"
24#include "tree_schema.h"
25
26struct ly_ctx;
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/**
33 * @defgroup datatree Data Tree
34 * @{
35 *
36 * Data structures and functions to manipulate and access instance data tree.
37 */
38
39/**
40 * @brief Macro to iterate via all elements in a data tree. This is the opening part
41 * to the #LYD_TREE_DFS_END - they always have to be used together.
42 *
43 * The function follows deep-first search algorithm:
44 * <pre>
45 * 1
46 * / \
47 * 2 4
48 * / / \
49 * 3 5 6
50 * </pre>
51 *
Radek Krejci0935f412019-08-20 16:15:18 +020052 * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While
Radek Krejcie7b95092019-05-15 11:03:07 +020053 * START can be any of the lyd_node* types, NEXT and ELEM variables are expected
54 * to be pointers to a generic struct lyd_node.
55 *
56 * Since the next node is selected as part of #LYD_TREE_DFS_END, do not use
57 * continue statement between the #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END.
58 *
59 * Use with opening curly bracket '{' after the macro.
60 *
61 * @param START Pointer to the starting element processed first.
62 * @param NEXT Temporary storage, do not use.
63 * @param ELEM Iterator intended for use in the block.
64 */
65#define LYD_TREE_DFS_BEGIN(START, NEXT, ELEM) \
66 for ((ELEM) = (NEXT) = (START); \
67 (ELEM); \
68 (ELEM) = (NEXT))
69
70/**
71 * @brief Macro to iterate via all elements in a tree. This is the closing part
72 * to the #LYD_TREE_DFS_BEGIN - they always have to be used together.
73 *
74 * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While
75 * START can be any of the lyd_node* types, NEXT and ELEM variables are expected
76 * to be pointers to a generic struct lyd_node.
77 *
78 * Use with closing curly bracket '}' after the macro.
79 *
80 * @param START Pointer to the starting element processed first.
81 * @param NEXT Temporary storage, do not use.
82 * @param ELEM Iterator intended for use in the block.
83 */
84
85#define LYD_TREE_DFS_END(START, NEXT, ELEM) \
86 /* select element for the next run - children first */ \
87 (NEXT) = (struct lyd_node*)lyd_node_children((struct lyd_node*)ELEM); \
88 if (!(NEXT)) { \
89 /* no children */ \
90 if ((ELEM) == (struct lyd_node*)(START)) { \
91 /* we are done, (START) has no children */ \
92 break; \
93 } \
94 /* try siblings */ \
95 (NEXT) = (ELEM)->next; \
96 } \
97 while (!(NEXT)) { \
98 /* parent is already processed, go to its sibling */ \
99 (ELEM) = (struct lyd_node*)(ELEM)->parent; \
100 /* no siblings, go back through parents */ \
101 if ((ELEM)->parent == (START)->parent) { \
102 /* we are done, no next element to process */ \
103 break; \
104 } \
105 (NEXT) = (ELEM)->next; \
106 }
107
108/**
Michal Vasko03ff5a72019-09-11 13:49:33 +0200109 * @brief Macro to get context from a data tree node.
110 */
111#define LYD_NODE_CTX(node) ((node)->schema->module->ctx)
112
113/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200114 * @brief Data input/output formats supported by libyang [parser](@ref howtodataparsers) and
115 * [printer](@ref howtodataprinters) functions.
116 */
117typedef enum {
118 LYD_UNKNOWN = 0, /**< unknown format, used as return value in case of error */
119 LYD_XML, /**< XML format of the instance data */
Radek Krejcie7b95092019-05-15 11:03:07 +0200120 LYD_JSON, /**< JSON format of the instance data */
Radek Krejci355bf4f2019-07-16 17:14:16 +0200121#if 0
Radek Krejcie7b95092019-05-15 11:03:07 +0200122 LYD_LYB, /**< LYB format of the instance data */
123#endif
124} LYD_FORMAT;
125
126/**
Radek Krejci59583bb2019-09-11 12:57:55 +0200127 * @brief List of possible value types stored in ::lyd_node_any.
Radek Krejcie7b95092019-05-15 11:03:07 +0200128 */
129typedef enum {
Radek Krejci22ebdba2019-07-25 13:59:43 +0200130 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 +0200131 is directly connected into the anydata node without duplication, caller is supposed to not manipulate
132 with the data after a successful call (including calling lyd_free() on the provided data) */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200133 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 +0200134 as string). XML sensitive characters (such as & or \>) are automatically escaped when the anydata
135 is printed in XML format. */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200136 LYD_ANYDATA_XML, /**< Value is a string containing the serialized XML data. */
137 LYD_ANYDATA_JSON, /**< Value is a string containing the data modeled by YANG and encoded as I-JSON. */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200138#if 0 /* TODO LYB format */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200139 LYD_ANYDATA_LYB, /**< Value is a memory chunk with the serialized data tree in LYB format. */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200140#endif
Radek Krejcie7b95092019-05-15 11:03:07 +0200141} LYD_ANYDATA_VALUETYPE;
142
143/** @} */
144
145/**
146 * @brief YANG data representation
147 */
148struct lyd_value {
Radek Krejci950f6a52019-09-12 17:15:32 +0200149 const char *original; /**< Original string representation of the value. It is never NULL, but (canonical) string representation
150 of the value should be always obtained via the type's printer callback (lyd_value::realtype::plugin::print). */
Radek Krejcie7b95092019-05-15 11:03:07 +0200151 union {
Radek Krejcie7b95092019-05-15 11:03:07 +0200152 int8_t boolean; /**< 0 as false, 1 as true */
153 int64_t dec64; /**< decimal64: value = dec64 / 10^fraction-digits */
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200154 int8_t int8; /**< 8-bit signed integer */
155 int16_t int16; /**< 16-bit signed integer */
156 int32_t int32; /**< 32-bit signed integer */
157 int64_t int64; /**< 64-bit signed integer */
158 uint8_t uint8; /**< 8-bit unsigned integer */
159 uint16_t uint16; /**< 16-bit signed integer */
160 uint32_t uint32; /**< 32-bit signed integer */
161 uint64_t uint64; /**< 64-bit signed integer */
Radek Krejcie7b95092019-05-15 11:03:07 +0200162 struct lysc_type_bitenum_item *enum_item; /**< pointer to the definition of the enumeration value */
Radek Krejci849a62a2019-05-22 15:29:05 +0200163 struct lysc_type_bitenum_item **bits_items; /**< list of set pointers to the specification of the set bits ([sized array](@ref sizedarrays)) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200164 struct lysc_ident *ident; /**< pointer to the schema definition of the identityref value */
Radek Krejciefbb3922019-07-15 12:58:00 +0200165
166 struct lyd_value_subvalue {
167 struct lyd_value_prefix {
168 const char *prefix; /**< prefix string used in the canonized string to identify the mod of the YANG schema */
169 const struct lys_module *mod; /**< YANG schema module identified by the prefix string */
170 } *prefixes; /**< list of mappings between prefix in canonized value to a YANG schema ([sized array](@ref sizedarrays)) */
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200171 struct lyd_value *value; /**< representation of the value according to the selected union's subtype (stored as lyd_value::realpath
172 here, in subvalue structure */
173 } *subvalue; /**< data to represent data with multiple types (union). Original value is stored in the main
Michal Vasko9b368d32020-02-14 13:53:31 +0100174 lyd_value:canonical_cache while the lyd_value_subvalue::value contains representation according to the
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200175 one of the union's type. The lyd_value_subvalue:prefixes provides (possible) mappings from prefixes
176 in original value to YANG modules. These prefixes are necessary to parse original value to the union's
177 subtypes. */
Radek Krejci084289f2019-07-09 17:35:30 +0200178
179 struct lyd_value_path {
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200180 const struct lysc_node *node; /**< Schema node representing the path segment */
Radek Krejci084289f2019-07-09 17:35:30 +0200181 struct lyd_value_path_predicate {
182 union {
183 struct {
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200184 const struct lysc_node *key; /**< key node of the predicate, in case of the leaf-list-predicate, it is the leaf-list node itself */
185 struct lyd_value *value; /**< value representation according to the key's type */
186 }; /**< key-value pair for leaf-list-predicate and key-predicate (type 1 and 2) */
187 uint64_t position; /**< position value for the position-predicate (type 0) */
Radek Krejci084289f2019-07-09 17:35:30 +0200188 };
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200189 uint8_t type; /**< Predicate types (see YANG ABNF): 0 - position, 1 - key-predicate, 2 - leaf-list-predicate */
190 } *predicates; /**< [Sized array](@ref sizedarrays) of the path segment's predicates */
191 } *target; /**< [Sized array](@ref sizedarrays) of (instance-identifier's) path segments. */
Radek Krejci084289f2019-07-09 17:35:30 +0200192
Radek Krejcie7b95092019-05-15 11:03:07 +0200193 void *ptr; /**< generic data type structure used to store the data */
Radek Krejci8dc4f2d2019-07-16 12:24:00 +0200194 }; /**< The union is just a list of shorthands to possible values stored by a type's plugin. libyang itself uses the lyd_value::realtype
195 plugin's callbacks to work with the data. */
Radek Krejci084289f2019-07-09 17:35:30 +0200196
Radek Krejci950f6a52019-09-12 17:15:32 +0200197 struct lysc_type *realtype; /**< pointer to the real type of the data stored in the value structure. This type can differ from the type
Radek Krejci62903c32019-07-15 14:42:05 +0200198 in the schema node of the data node since the type's store plugin can use other types/plugins for
199 storing data. Speaking about built-in types, this is the case of leafref which stores data as its
200 target type. In contrast, union type also use its subtype's callbacks, but inside an internal data
201 lyd_value::subvalue structure, so here is the pointer to the union type.
202 In general, this type is used to get free callback for this lyd_value structure, so it must reflect
203 the type used to store data directly in the same lyd_value instance. */
Radek Krejci950f6a52019-09-12 17:15:32 +0200204 void *canonical_cache; /**< Generic cache for type plugins to store data necessary to print canonical value. It can be the canonical
205 value itself or anything else useful to print the canonical form of the value. Plugin is responsible for
206 freeing the cache in its free callback. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200207};
208
209/**
210 * @brief Attribute structure.
211 *
212 * The structure provides information about attributes of a data element. Such attributes must map to
213 * annotations as specified in RFC 7952. The only exception is the filter type (in NETCONF get operations)
214 * and edit-config's operation attributes. In XML, they are represented as standard XML attributes. In JSON,
215 * they are represented as JSON elements starting with the '@' character (for more information, see the
216 * YANG metadata RFC.
217 *
218 */
219struct lyd_attr {
220 struct lyd_node *parent; /**< data node where the attribute is placed */
221 struct lyd_attr *next; /**< pointer to the next attribute of the same element */
Radek Krejci38d85362019-09-05 16:26:38 +0200222 struct lysc_ext_instance *annotation; /**< pointer to the attribute/annotation's definition */
Radek Krejcie7b95092019-05-15 11:03:07 +0200223 const char *name; /**< attribute name */
Radek Krejci38d85362019-09-05 16:26:38 +0200224 struct lyd_value value; /**< attribute's value representation */
Radek Krejcie7b95092019-05-15 11:03:07 +0200225};
226
227
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200228#define LYD_NODE_INNER (LYS_CONTAINER|LYS_LIST|LYS_ACTION|LYS_NOTIF) /**< Schema nodetype mask for lyd_node_inner */
Radek Krejcie7b95092019-05-15 11:03:07 +0200229#define LYD_NODE_TERM (LYS_LEAF|LYS_LEAFLIST) /**< Schema nodetype mask for lyd_node_term */
230#define LYD_NODE_ANY (LYS_ANYDATA) /**< Schema nodetype mask for lyd_node_any */
231
232/**
Michal Vasko9b368d32020-02-14 13:53:31 +0100233 * @defgroup dnodeflags Data node flags
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200234 * @ingroup datatree
235 * @{
236 *
237 * Various flags of data nodes.
238 *
239 * 1 - container 5 - anydata/anyxml
240 * 2 - list 6 - rpc/action
241 * 3 - leaf 7 - notification
242 * 4 - leaflist
243 *
244 * bit name 1 2 3 4 5 6 7
245 * ---------------------+-+-+-+-+-+-+-+
246 * 1 LYD_DEFAULT |x| |x|x| | | |
247 * +-+-+-+-+-+-+-+
Michal Vasko5c4e5892019-11-14 12:31:38 +0100248 * 2 LYD_WHEN_TRUE |x|x|x|x|x| | |
Michal Vasko9b368d32020-02-14 13:53:31 +0100249 * +-+-+-+-+-+-+-+
250 * 3 LYD_NEW |x|x|x|x|x|x|x|
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200251 * ---------------------+-+-+-+-+-+-+-+
252 *
253 */
254
Michal Vasko5c4e5892019-11-14 12:31:38 +0100255#define LYD_DEFAULT 0x01 /**< default (implicit) node */
256#define LYD_WHEN_TRUE 0x02 /**< all when conditions of this node were evaluated to true */
Michal Vasko9b368d32020-02-14 13:53:31 +0100257#define LYD_NEW 0x04 /**< node was created after the last validation, is needed for the next validation */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200258/** @} */
259
260/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200261 * @brief Generic structure for a data node.
262 */
263struct lyd_node {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200264 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
265 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
266 used to get know that nodes are not equal, it cannot be used to decide that the
267 nodes are equal due to possible collisions. */
268 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Michal Vaskoecd62de2019-11-13 12:35:11 +0100269 const struct lysc_node *schema; /**< pointer to the schema definition of this node, note that the target can be not just
270 ::struct lysc_node but ::struct lysc_action or ::struct lysc_notif as well */
Radek Krejcie7b95092019-05-15 11:03:07 +0200271 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
272 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
273 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
274 never NULL. If there is no sibling node, pointer points to the node
275 itself. In case of the first node, this pointer points to the last
276 node in the list. */
277 struct lyd_attr *attr; /**< pointer to the list of attributes of this node */
278
279#ifdef LY_ENABLED_LYD_PRIV
280 void *priv; /**< private user data, not used by libyang */
281#endif
282};
283
284/**
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200285 * @brief Data node structure for the inner data tree nodes - containers, lists, RPCs, actions and Notifications.
Radek Krejcie7b95092019-05-15 11:03:07 +0200286 */
287struct lyd_node_inner {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200288 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
289 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
290 used to get know that nodes are not equal, it cannot be used to decide that the
291 nodes are equal due to possible collisions. */
292 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200293 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
294 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
295 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
296 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
297 never NULL. If there is no sibling node, pointer points to the node
298 itself. In case of the first node, this pointer points to the last
299 node in the list. */
300 struct lyd_attr *attr; /**< pointer to the list of attributes of this node */
301
302#ifdef LY_ENABLED_LYD_PRIV
303 void *priv; /**< private user data, not used by libyang */
304#endif
305
306 struct lyd_node *child; /**< pointer to the first child node. */
307 struct hash_table *children_ht; /**< hash table with all the direct children (except keys for a list, lists without keys) */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200308#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 +0200309};
310
311/**
312 * @brief Data node structure for the terminal data tree nodes - leafs and leaf-lists.
313 */
314struct lyd_node_term {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200315 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
316 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
317 used to get know that nodes are not equal, it cannot be used to decide that the
318 nodes are equal due to possible collisions. */
319 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200320 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
321 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
322 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
323 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
324 never NULL. If there is no sibling node, pointer points to the node
325 itself. In case of the first node, this pointer points to the last
326 node in the list. */
327 struct lyd_attr *attr; /**< pointer to the list of attributes of this node */
328
329#ifdef LY_ENABLED_LYD_PRIV
330 void *priv; /**< private user data, not used by libyang */
331#endif
332
333 struct lyd_value value; /**< node's value representation */
334};
335
336/**
337 * @brief Data node structure for the anydata data tree nodes - anydatas and anyxmls.
338 */
339struct lyd_node_any {
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200340 uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or
341 hashes of all nodes of subtree in case of keyless list). Note that while hash can be
342 used to get know that nodes are not equal, it cannot be used to decide that the
343 nodes are equal due to possible collisions. */
344 uint32_t flags; /**< [data node flags](@ref dnodeflags) */
Radek Krejcie7b95092019-05-15 11:03:07 +0200345 const struct lysc_node *schema; /**< pointer to the schema definition of this node */
346 struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */
347 struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */
348 struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is
349 never NULL. If there is no sibling node, pointer points to the node
350 itself. In case of the first node, this pointer points to the last
351 node in the list. */
352 struct lyd_attr *attr; /**< pointer to the list of attributes of this node */
353
354#ifdef LY_ENABLED_LYD_PRIV
355 void *priv; /**< private user data, not used by libyang */
356#endif
357
Radek Krejciee4cab22019-07-17 17:07:47 +0200358 union {
359 struct lyd_node *tree; /**< data tree */
360 const char *str; /**< Generic string data */
361 const char *xml; /**< Serialized XML data */
362 const char *json; /**< I-JSON encoded string */
363 char *mem; /**< LYD_ANYDATA_LYB memory chunk */
364 } value; /**< pointer to the stored value representation of the anydata/anyxml node */
365 LYD_ANYDATA_VALUETYPE value_type;/**< type of the data stored as lyd_node_any::value */
Radek Krejcie7b95092019-05-15 11:03:07 +0200366};
367
368/**
369 * @defgroup dataparseroptions Data parser options
370 * @ingroup datatree
371 *
372 * Various options to change the data tree parsers behavior.
373 *
Michal Vasko9b368d32020-02-14 13:53:31 +0100374 * Default parser behavior:
Radek Krejcie7b95092019-05-15 11:03:07 +0200375 * - in case of XML, parser reads all data from its input (file, memory, XML tree) including the case of not well-formed
376 * XML document (multiple top-level elements) and if there is an unknown element, it is skipped including its subtree
377 * (see the next point). This can be changed by the #LYD_OPT_NOSIBLINGS option which make parser to read only a single
Michal Vasko9b368d32020-02-14 13:53:31 +0100378 * tree (with a single root element) from its input,
379 * - parser silently ignores the data without a matching node in schema trees. If the caller wants to stop
Radek Krejcie7b95092019-05-15 11:03:07 +0200380 * parsing in case of presence of unknown data, the #LYD_OPT_STRICT can be used. The strict mode is useful for
381 * NETCONF servers, since NETCONF clients should always send data according to the capabilities announced by the server.
382 * On the other hand, the default non-strict mode is useful for clients receiving data from NETCONF server since
383 * clients are not required to understand everything the server does. Of course, the optimal strategy for clients is
Michal Vasko9b368d32020-02-14 13:53:31 +0100384 * to use filtering to get only the required data. Having an unknown element of the known namespace is always an error,
385 * - using obsolete statements (status set to obsolete) just generates a warning, but the processing continues
386 * (see #LYD_OPT_OBSOLETE).
387 *
388 * Default parser validation behavior:
389 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
390 * and performs data validation according to all YANG rules, specifics follow,
391 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
392 * all the keys, leaf(-lists) correct values),
393 * - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised,
394 * - data from several cases cause a validation error,
395 * - default values are added.
Radek Krejcie7b95092019-05-15 11:03:07 +0200396 * @{
397 */
398
Michal Vasko9b368d32020-02-14 13:53:31 +0100399#define LYD_OPT_DATA 0x0 /**< Default type of data - complete datastore content with configuration as well as
Michal Vaskoe444f752020-02-10 12:20:06 +0100400 state data. */
Michal Vasko9b368d32020-02-14 13:53:31 +0100401#define LYD_OPT_CONFIG LYD_VALOPT_NO_STATE /**< A configuration datastore - complete datastore without state data. */
Michal Vaskoe444f752020-02-10 12:20:06 +0100402#define LYD_OPT_GET LYD_OPT_PARSE_ONLY /**< Data content from a NETCONF reply message to the NETCONF
403 \<get\> operation. */
Michal Vasko9b368d32020-02-14 13:53:31 +0100404#define LYD_OPT_GETCONFIG LYD_OPT_PARSE_ONLY | LYD_VALOPT_NO_STATE /**< Data content from a NETCONF reply message to
Michal Vaskoe444f752020-02-10 12:20:06 +0100405 the NETCONF \<get-config\> operation. */
Michal Vasko9b368d32020-02-14 13:53:31 +0100406#define LYD_OPT_EDIT LYD_OPT_PARSE_ONLY | LYD_VALOPT_NO_STATE | LYD_OPT_EMPTY_INST /**< Content of
Michal Vaskoe444f752020-02-10 12:20:06 +0100407 the NETCONF \<edit-config\>'s config element. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200408
Michal Vasko9b368d32020-02-14 13:53:31 +0100409#define LYD_OPT_PARSE_ONLY 0x0001 /**< Data will be only parsed and no validation will be performed. When statements
410 are kept unevaluated, union types may not be fully resolved, and default values
411 are not added (only the ones parsed are present). */
412#define LYD_OPT_TRUSTED 0x0002 /**< Data are considered trusted so they will be parsed as validated. If the parsed
413 data are not valid, using this flag may lead to some unexpected behavior!
414 This flag can be used only with #LYD_OPT_PARSE_ONLY. */
415#define LYD_OPT_STRICT 0x0004 /**< Instead of silently ignoring data without schema definition raise an error. */
416#define LYD_OPT_EMPTY_INST 0x0008 /**< Allow leaf/leaf-list instances without values and lists without keys. */
Michal Vaskoa3881362020-01-21 15:57:35 +0100417//#define LYD_OPT_NOSIBLINGS 0x1000 /**< Parse only a single XML tree from the input. This option applies only to
418// XML input data. */
Michal Vasko9b368d32020-02-14 13:53:31 +0100419
420/** @} dataparseroptions */
421
422/**
423 * @defgroup datavalidationoptions Data validation options
424 * @ingroup datatree
425 *
426 * Various options to change data validation behaviour, both for the parser and separate validation.
427 *
428 * Default separate validation behavior:
429 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
430 * and performs data validation according to all YANG rules, specifics follow,
431 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
432 * all the keys, leaf(-lists) correct values),
433 * - when statements on existing nodes are evaluated. Depending on the previous when state (from previous validation
434 * or parsing), the node is silently auto-deleted if the state changed from true to false, otherwise a validation error
435 * is raised if it evaluates to false,
436 * - data from several cases behave based on their previous state (from previous validation or parsing). If there existed
437 * already a case and another one was added, the previous one is silently auto-deleted. Otherwise (if data from 2 or
438 * more cases were created) a validation error is raised,
439 * - default values are added.
440 *
441 * @{
442 */
443
444#define LYD_VALOPT_NO_STATE 0x00010000 /**< Consider state data not allowed and raise an error if they are found. */
445#define LYD_VALOPT_DATA_ONLY 0x00020000 /**< Validate only modules whose data actually exist. */
446//#define LYD_VALOPT_OBSOLETE 0x0800 /**< Raise an error when an obsolete statement (status set to obsolete) is used. */
447
448/** @} datavalidationoptions */
449
Michal Vaskoa3881362020-01-21 15:57:35 +0100450//#define LYD_OPT_VAL_DIFF 0x40000 /**< Flag only for validation, store all the data node changes performed by the validation
451// in a diff structure. */
452//#define LYD_OPT_DATA_TEMPLATE 0x1000000 /**< Data represents YANG data template. */
Radek Krejcie7b95092019-05-15 11:03:07 +0200453
Radek Krejcie7b95092019-05-15 11:03:07 +0200454/**
455 * @brief Get the node's children list if any.
456 *
457 * Decides the node's type and in case it has a children list, returns it.
458 * @param[in] node Node to check.
459 * @return Pointer to the first child node (if any) of the \p node.
460 */
461const struct lyd_node *lyd_node_children(const struct lyd_node *node);
462
463/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200464 * @brief Parse (and validate) data from memory.
465 *
466 * In case of LY_XML format, the data string is parsed completely. It means that when it contains
467 * a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The
468 * returned data node is a root of the first tree with other trees connected via the next pointer.
469 * This behavior can be changed by #LYD_OPT_NOSIBLINGS option.
470 *
471 * @param[in] ctx Context to connect with the data tree being built here.
472 * @param[in] data Serialized data in the specified format.
473 * @param[in] format Format of the input data to be parsed.
Michal Vaskoa3881362020-01-21 15:57:35 +0100474 * @param[in] options Parser options, see @ref parseroptions. \p format LYD_LYB uses #LYD_OPT_PARSE_ONLY implicitly.
Radek Krejcie7b95092019-05-15 11:03:07 +0200475 * @return Pointer to the built data tree or NULL in case of empty \p data. To free the returned structure,
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200476 * use lyd_free_all().
477 * @return NULL in case of error. The error information can be then obtained using ly_err* functions.
Radek Krejcie7b95092019-05-15 11:03:07 +0200478 */
Michal Vaskoa3881362020-01-21 15:57:35 +0100479struct lyd_node *lyd_parse_mem(struct ly_ctx *ctx, const char *data, LYD_FORMAT format, int options);
Radek Krejcie7b95092019-05-15 11:03:07 +0200480
481/**
482 * @brief Read (and validate) data from the given file descriptor.
483 *
484 * \note Current implementation supports only reading data from standard (disk) file, not from sockets, pipes, etc.
485 *
486 * In case of LY_XML format, the file content is parsed completely. It means that when it contains
487 * a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The
488 * returned data node is a root of the first tree with other trees connected via the next pointer.
489 * This behavior can be changed by #LYD_OPT_NOSIBLINGS option.
490 *
491 * @param[in] ctx Context to connect with the data tree being built here.
492 * @param[in] fd The standard file descriptor of the file containing the data tree in the specified format.
493 * @param[in] format Format of the input data to be parsed.
Michal Vaskoa3881362020-01-21 15:57:35 +0100494 * @param[in] options Parser options, see @ref parseroptions. \p format LYD_LYB uses #LYD_OPT_PARSE_ONLY implicitly.
Radek Krejcie7b95092019-05-15 11:03:07 +0200495 * @return Pointer to the built data tree or NULL in case of empty file. To free the returned structure,
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200496 * use lyd_free_all().
497 * @return NULL in case of error. The error information can be then obtained using ly_err* functions.
Radek Krejcie7b95092019-05-15 11:03:07 +0200498 */
Michal Vaskoa3881362020-01-21 15:57:35 +0100499struct lyd_node *lyd_parse_fd(struct ly_ctx *ctx, int fd, LYD_FORMAT format, int options);
Radek Krejcie7b95092019-05-15 11:03:07 +0200500
501/**
502 * @brief Read (and validate) data from the given file path.
503 *
504 * In case of LY_XML format, the file content is parsed completely. It means that when it contains
505 * a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The
506 * returned data node is a root of the first tree with other trees connected via the next pointer.
507 * This behavior can be changed by #LYD_OPT_NOSIBLINGS option.
508 *
509 * @param[in] ctx Context to connect with the data tree being built here.
510 * @param[in] path Path to the file containing the data tree in the specified format.
511 * @param[in] format Format of the input data to be parsed.
Michal Vaskoa3881362020-01-21 15:57:35 +0100512 * @param[in] options Parser options, see @ref parseroptions. \p format LYD_LYB uses #LYD_OPT_PARSE_ONLY implicitly.
Radek Krejcie7b95092019-05-15 11:03:07 +0200513 * @return Pointer to the built data tree or NULL in case of empty file. To free the returned structure,
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200514 * use lyd_free_all().
515 * @return NULL in case of error. The error information can be then obtained using ly_err* functions.
Radek Krejcie7b95092019-05-15 11:03:07 +0200516 */
Michal Vaskoa3881362020-01-21 15:57:35 +0100517struct lyd_node *lyd_parse_path(struct ly_ctx *ctx, const char *path, LYD_FORMAT format, int options);
Radek Krejcie7b95092019-05-15 11:03:07 +0200518
519/**
Radek Krejcib0849a22019-07-25 12:31:04 +0200520 * @brief Free all the nodes (even parents of the node) in the data tree.
Radek Krejcie7b95092019-05-15 11:03:07 +0200521 *
522 * @param[in] node Any of the nodes inside the tree.
523 */
524void lyd_free_all(struct lyd_node *node);
525
526/**
Radek Krejcib0849a22019-07-25 12:31:04 +0200527 * @brief Free all the sibling nodes.
528 *
529 * @param[in] node Any of the sibling nodes to free.
530 */
531void lyd_free_withsiblings(struct lyd_node *node);
532
533/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200534 * @brief Free (and unlink) the specified data (sub)tree.
535 *
536 * __PARTIAL CHANGE__ - validate after the final change on the data tree (see @ref howtodatamanipulators).
537 *
538 * @param[in] node Root of the (sub)tree to be freed.
539 */
540void lyd_free_tree(struct lyd_node *node);
541
542/**
543 * @brief Unlink the specified data subtree. All referenced namespaces are copied.
544 *
545 * Note, that the node's connection with the schema tree is kept. Therefore, in case of
546 * reconnecting the node to a data tree using lyd_paste() it is necessary to paste it
547 * to the appropriate place in the data tree following the schema.
548 *
549 * __PARTIAL CHANGE__ - validate after the final change on the data tree (see @ref howtodatamanipulators).
550 *
551 * @param[in] node Data tree node to be unlinked (together with all children).
552 * @return LY_SUCCESS for success
553 * @return LY_E* values in case of error
554 */
555LY_ERR lyd_unlink_tree(struct lyd_node *node);
556
557/**
558 * @brief Destroy data attribute.
559 *
560 * @param[in] ctx Context where the attribute was created.
561 * @param[in] attr Attribute to destroy
562 * @param[in] recursive Zero to destroy only the attribute (the attribute list is corrected),
563 * non-zero to destroy also all the subsequent attributes in the list.
564 */
565void lyd_free_attr(struct ly_ctx *ctx, struct lyd_attr *attr, int recursive);
566
Radek Krejci084289f2019-07-09 17:35:30 +0200567/**
Radek Krejci576b23f2019-07-12 14:06:32 +0200568 * @brief Prepare ([sized array](@ref sizedarrays)) of data trees required by various (mostly validation) functions.
569 *
570 * @param[in] count Number of trees to include (including the mandatory @p tree).
571 * @param[in] tree First (and mandatory) tree to be included into the resulting ([sized array](@ref sizedarrays)).
572 * @return NULL in case of memory allocation failure or invalid argument, prepared ([sized array](@ref sizedarrays)) otherwise.
573 */
574const struct lyd_node **lyd_trees_new(size_t count, const struct lyd_node *tree, ...);
575
576/**
Radek Krejcif3b6fec2019-07-24 15:53:11 +0200577 * @brief Add tree into the ([sized array](@ref sizedarrays)) of data trees created by lyd_trees_new(),
578 *
579 * @param[in] trees Existing [sized array](@ref sizedarrays)) of data trees to be extended.
580 * @param[in] tree Data tree to be included into the provided @p trees ([sized array](@ref sizedarrays)).
581 * @return NULL in case of memory allocation failure or invalid argument, extended @p trees ([sized array](@ref sizedarrays)) otherwise.
582 */
583const struct lyd_node **lyd_trees_add(const struct lyd_node **trees, const struct lyd_node *tree);
584
585/**
Radek Krejci576b23f2019-07-12 14:06:32 +0200586 * @brief Free the trees ([sized array](@ref sizedarrays)).
587 *
588 * @param[in] trees ([Sized array](@ref sizedarrays)) of data trees.
589 * @param[in] free_data Flag to free also the particular trees in the @p trees ([sized array](@ref sizedarrays)).
590 * If set to zero, only the trees envelope is freed and data are untouched.
591 */
592void lyd_trees_free(const struct lyd_node **trees, int free_data);
593
594/**
Radek Krejci084289f2019-07-09 17:35:30 +0200595 * @brief Check type restrictions applicable to the particular leaf/leaf-list with the given string @p value.
596 *
597 * The given node is not modified in any way - it is just checked if the @p value can be set to the node.
598 *
599 * If there is no data node instance and you are fine with checking just the type's restrictions without the
600 * data tree context (e.g. for the case of require-instance restriction), use lys_value_validate().
601 *
602 * @param[in] ctx libyang context for logging (function does not log errors when @p ctx is NULL)
603 * @param[in] node Data node for the @p value.
604 * @param[in] value String value to be checked.
605 * @param[in] value_len Length of the given @p value (mandatory).
606 * @param[in] get_prefix Callback function to resolve prefixes used in the @p value string.
607 * @param[in] get_prefix_data Private data for the @p get_prefix callback.
608 * @param[in] format Input format of the data.
609 * @param[in] trees ([Sized array](@ref sizedarrays)) of data trees (e.g. when validating RPC/Notification) where the required
610 * data instance (leafref target, instance-identifier) can be placed. NULL in case the data tree are not yet complete,
Radek Krejci576b23f2019-07-12 14:06:32 +0200611 * then LY_EINCOMPLETE can be returned. To simply prepare this structure, use lyd_trees_new().
Radek Krejci084289f2019-07-09 17:35:30 +0200612 * @return LY_SUCCESS on success
613 * @return LY_EINCOMPLETE in case the @p trees is not provided and it was needed to finish the validation (e.g. due to require-instance).
614 * @return LY_ERR value if an error occurred.
615 */
616LY_ERR lyd_value_validate(struct ly_ctx *ctx, const struct lyd_node_term *node, const char *value, size_t value_len,
Radek Krejci576b23f2019-07-12 14:06:32 +0200617 ly_clb_resolve_prefix get_prefix, void *get_prefix_data, LYD_FORMAT format, const struct lyd_node **trees);
Radek Krejci084289f2019-07-09 17:35:30 +0200618
619/**
620 * @brief Compare the node's value with the given string value. The string value is first validated according to the node's type.
621 *
622 * @param[in] node Data node to compare.
623 * @param[in] value String value to be compared. It does not need to be in a canonical form - as part of the process,
624 * it is validated and canonized if possible.
625 * @param[in] value_len Length of the given @p value (mandatory).
626 * @param[in] get_prefix Callback function to resolve prefixes used in the @p value string.
627 * @param[in] get_prefix_data Private data for the @p get_prefix callback.
628 * @param[in] format Input format of the data.
629 * @param[in] trees ([Sized array](@ref sizedarrays)) of data trees (e.g. when validating RPC/Notification) where the required
630 * data instance (leafref target, instance-identifier) can be placed. NULL in case the data tree are not yet complete,
Radek Krejci576b23f2019-07-12 14:06:32 +0200631 * then LY_EINCOMPLETE can be returned in case the validation was not completed, but values matches. To simply prepare
632 * this structure, use lyd_trees_new(). To simply prepare this structure, use lyd_trees_new().
Radek Krejci084289f2019-07-09 17:35:30 +0200633 * @return LY_SUCCESS on success
634 * @return LY_EINCOMPLETE in case of success when the @p trees is not provided and it was needed to finish the validation of
635 * the given string @p value (e.g. due to require-instance).
636 * @return LY_ERR value if an error occurred.
637 */
638LY_ERR lyd_value_compare(const struct lyd_node_term *node, const char *value, size_t value_len,
Radek Krejci576b23f2019-07-12 14:06:32 +0200639 ly_clb_resolve_prefix get_prefix, void *get_prefix_data, LYD_FORMAT format, const struct lyd_node **trees);
Radek Krejci084289f2019-07-09 17:35:30 +0200640
Radek Krejci576b23f2019-07-12 14:06:32 +0200641/**
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200642 * @defgroup datacompareoptions Data compare options
643 * @ingroup datatree
644 *
Radek Krejci22ebdba2019-07-25 13:59:43 +0200645 * Various options to change the lyd_compare() behavior.
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200646 */
647#define LYD_COMPARE_FULL_RECURSION 0x01 /* lists and containers are the same only in case all they children
648 (subtree, so direct as well as indirect children) are the same. By default,
649 containers are the same in case of the same schema node and lists are the same
650 in case of equal keys (keyless lists do the full recursion comparison all the time). */
651#define LYD_COMPARE_DEFAULTS 0x02 /* By default, implicit and explicit default nodes are considered to be equal. This flag
652 changes this behavior and implicit (automatically created default node) and explicit
653 (explicitly created node with the default value) default nodes are considered different. */
Radek Krejci22ebdba2019-07-25 13:59:43 +0200654/**@} datacompareoptions */
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200655
656/**
657 * @brief Compare 2 data nodes if they are equivalent.
658 *
659 * @param[in] node1 The first node to compare.
660 * @param[in] node2 The second node to compare.
Radek Krejcic5ad9652019-09-11 11:31:51 +0200661 * @param[in] options Various @ref datacompareoptions.
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200662 * @return LY_SUCCESS if the nodes are equivalent.
663 * @return LY_ENOT if the nodes are not equivalent.
664 */
665LY_ERR lyd_compare(const struct lyd_node *node1, const struct lyd_node *node2, int options);
666
667/**
Radek Krejci22ebdba2019-07-25 13:59:43 +0200668 * @defgroup dupoptions Data duplication options
669 * @ingroup datatree
670 *
671 * Various options to change lyd_dup() behavior.
672 *
673 * Default behavior:
674 * - only the specified node is duplicated without siblings, parents, or children.
675 * - all the attributes of the duplicated nodes are also duplicated.
676 * @{
677 */
678
679#define LYD_DUP_RECURSIVE 0x01 /**< Duplicate not just the node but also all the children. Note that
680 list's keys are always duplicated. */
681#define LYD_DUP_NO_ATTR 0x02 /**< Do not duplicate attributes of any node. */
682#define LYD_DUP_WITH_PARENTS 0x04 /**< If a nested node is being duplicated, duplicate also all the parents.
683 Keys are also duplicated for lists. Return value does not change! */
684#define LYD_DUP_WITH_SIBLINGS 0x08 /**< Duplicate also all the sibling of the given node. */
685#define LYD_DUP_WITH_WHEN 0x10 /**< Also copy any when evaluation state flags. This is useful in case the copied
686 nodes are actually still part of the same datastore meaning no dependency data
687 could have changed. Otherwise nothing is assumed about the copied node when
688 state and it is evaluated from scratch during validation. */
689
690/** @} dupoptions */
691
692/**
693 * @brief Create a copy of the specified data tree \p node. Schema references are kept the same.
694 *
695 * __PARTIAL CHANGE__ - validate after the final change on the data tree (see @ref howtodatamanipulators).
696 *
697 * @param[in] node Data tree node to be duplicated.
698 * @param[in] parent Optional parent node where to connect the duplicated node(s).
699 * If set in combination with LYD_DUP_WITH_PARENTS, the parents chain is duplicated until it comes to and connect with the @p parent
700 * (if the parents chain does not match at some node the schema node of the provided @p parent, duplication fails).
701 * @param[in] options Bitmask of options flags, see @ref dupoptions.
702 * @return Created copy of the provided data \p node (the first of the duplicated siblings when LYD_DUP_WITH_SIBLINGS used).
703 * Note that in case the parents chain is duplicated for the duplicated node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node
704 * is still returned, not a pointer to the duplicated parents.
705 */
706struct lyd_node *lyd_dup(const struct lyd_node *node, struct lyd_node_inner *parent, int options);
707
708/**
Radek Krejci576b23f2019-07-12 14:06:32 +0200709 * @brief Resolve instance-identifier defined by lyd_value_path structure.
710 *
711 * @param[in] path Path structure specifying the instance-identifier target.
712 * @param[in] trees ([Sized array](@ref sizedarrays)) of data trees to be searched.
713 * To simply prepare this structure, use lyd_trees_new().
714 * @return Target node of the instance-identifier present in the given data @p trees.
715 */
716const struct lyd_node_term *lyd_target(struct lyd_value_path *path, const struct lyd_node **trees);
Radek Krejci084289f2019-07-09 17:35:30 +0200717
Michal Vasko5ec7cda2019-09-11 13:43:08 +0200718/**
719 * @brief Get string value of a term data \p node.
720 *
721 * @param[in] node Data tree node with the value.
722 * @param[out] dynamic Whether the string value was dynmically allocated.
723 * @return String value of @p node, if @p dynamic, needs to be freed.
724 */
725const char *lyd_value2str(const struct lyd_node_term *node, int *dynamic);
726
727/**
728 * @brief Get string value of an attribute \p attr.
729 *
730 * @param[in] attr Attribute with the value.
731 * @param[out] dynamic Whether the string value was dynmically allocated.
732 * @return String value of @p attr, if @p dynamic, needs to be freed.
733 */
734const char *lyd_attr2str(const struct lyd_attr *attr, int *dynamic);
735
736/**
737 * @brief Types of the different data paths.
738 */
739typedef enum {
Michal Vasko14654712020-02-06 08:35:21 +0100740 LYD_PATH_LOG, /**< Descriptive path format used in log messages */
Michal Vasko5ec7cda2019-09-11 13:43:08 +0200741} LYD_PATH_TYPE;
742
743/**
744 * @brief Generate path of the given node in the requested format.
745 *
746 * @param[in] node Schema path of this node will be generated.
747 * @param[in] pathtype Format of the path to generate.
748 * @param[in,out] buffer Prepared buffer of the @p buflen length to store the generated path.
749 * If NULL, memory for the complete path is allocated.
750 * @param[in] buflen Size of the provided @p buffer.
751 * @return NULL in case of memory allocation error, path of the node otherwise.
752 * In case the @p buffer is NULL, the returned string is dynamically allocated and caller is responsible to free it.
753 */
754char *lyd_path(const struct lyd_node *node, LYD_PATH_TYPE pathtype, char *buffer, size_t buflen);
755
Michal Vaskoe444f752020-02-10 12:20:06 +0100756/**
Michal Vaskoe444f752020-02-10 12:20:06 +0100757 * @brief Find the node, in the list, satisfying the given restrictions.
758 * Does **not** use hashes - should not be used unless necessary for best performance.
759 *
760 * @param[in] first Starting sibling node for search, only succeeding ones are searched.
761 * @param[in] module Module of the node to find.
762 * @param[in] name Name of the node to find.
763 * @param[in] name_len Optional length of the @p name argument in case it is not NULL-terminated string.
764 * @param[in] key_or_value Expected value depends on the type of @p name node:
765 * LYS_CONTAINER:
766 * LYS_ANYXML:
767 * LYS_ANYDATA:
768 * LYS_NOTIF:
769 * LYS_RPC:
770 * LYS_ACTION:
771 * NULL should be always set, will be ignored.
772 * LYS_LEAF:
773 * LYS_LEAFLIST:
Michal Vasko90932a92020-02-12 14:33:03 +0100774 * Optional restriction on the specific leaf(-list) value.
Michal Vaskoe444f752020-02-10 12:20:06 +0100775 * LYS_LIST:
776 * Optional keys values of the matching list instances in the form of "[key1='val1'][key2='val2']...".
Michal Vasko90932a92020-02-12 14:33:03 +0100777 * The keys do not have to be ordered and not all keys need to be specified.
778 *
779 * Note that any explicit values (leaf, leaf-list or list key values) will be canonized first
780 * before comparison. But values that do not have a canonical value are expected to be in the
781 * JSON format!
Michal Vaskoe444f752020-02-10 12:20:06 +0100782 * @param[in] val_len Optional length of the @p key_or_value argument in case it is not NULL-terminated string.
783 * @param[out] match Found data node.
784 * @return LY_SUCCESS on success, @p match set.
785 * @return LY_ENOTFOUND if not found, @p match set to NULL.
786 * @return LY_ERR value if another error occurred.
787 */
788LY_ERR lyd_find_sibling_next(const struct lyd_node *first, const struct lys_module *module, const char *name,
789 size_t name_len, const char *key_or_value, size_t val_len, struct lyd_node **match);
790
791/**
792 * @brief Search in the given siblings (NOT recursively) for the first target instance.
793 * Uses hashes - should be used whenever possible for best performance.
794 *
795 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
796 * @param[in] target Target node to find.
Michal Vasko9b368d32020-02-14 13:53:31 +0100797 * @param[out] match Can be NULL, otherwise the found data node.
Michal Vaskoe444f752020-02-10 12:20:06 +0100798 * @return LY_SUCCESS on success, @p match set.
799 * @return LY_ENOTFOUND if not found, @p match set to NULL.
800 * @return LY_ERR value if another error occurred.
801 */
802LY_ERR lyd_find_sibling_first(const struct lyd_node *siblings, const struct lyd_node *target, struct lyd_node **match);
803
804/**
805 * @brief Search in the given siblings for all target instances.
806 * Uses hashes - should be used whenever possible for best performance.
807 *
808 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
809 * @param[in] target Target node to find. Key-less lists are compared based on
810 * all its descendants (both direct and indirect).
811 * @param[out] set Found nodes in a set in case of success.
812 * @return LY_SUCCESS on success.
813 * @return LY_ENOTFOUND if no matching siblings found.
814 * @return LY_ERR value if another error occurred.
815 */
816LY_ERR lyd_find_sibling_set(const struct lyd_node *siblings, const struct lyd_node *target, struct ly_set **set);
817
818/**
819 * @brief Search in the given siblings for the first schema instance.
820 * Uses hashes - should be used whenever possible for best performance.
821 *
822 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
823 * @param[in] schema Schema node of the data node to find.
824 * @param[in] key_or_value Expected value depends on the type of \p schema:
825 * LYS_CONTAINER:
826 * LYS_LEAF:
827 * LYS_ANYXML:
828 * LYS_ANYDATA:
829 * LYS_NOTIF:
830 * LYS_RPC:
831 * LYS_ACTION:
832 * NULL should be always set, will be ignored.
833 * LYS_LEAFLIST:
834 * Searched instance value.
835 * LYS_LIST:
Michal Vasko90932a92020-02-12 14:33:03 +0100836 * Searched instance key values in the form of "[key1='val1'][key2='val2']...".
837 * The keys do not have to be ordered but all of them must be set.
838 *
839 * Note that any explicit values (leaf-list or list key values) will be canonized first
840 * before comparison. But values that do not have a canonical value are expected to be in the
841 * JSON format!
Michal Vasko9b368d32020-02-14 13:53:31 +0100842 * @param[out] match Can be NULL, otherwise the found data node.
Michal Vaskoe444f752020-02-10 12:20:06 +0100843 * @return LY_SUCCESS on success, @p match set.
844 * @return LY_ENOTFOUND if not found, @p match set to NULL.
845 * @return LY_EINVAL if @p schema is a key-less list.
846 * @return LY_ERR value if another error occurred.
847 */
848LY_ERR lyd_find_sibling_val(const struct lyd_node *siblings, const struct lysc_node *schema, const char *key_or_value,
849 size_t val_len, struct lyd_node **match);
850
Radek Krejcie7b95092019-05-15 11:03:07 +0200851#ifdef __cplusplus
852}
853#endif
854
855#endif /* LY_TREE_DATA_H_ */