blob: 1cc58c657bd8b1ada69be1a4d8b34943f4cacc1b [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
2 * @file tree_data_internal.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
Michal Vaskodbf3e652022-10-21 08:46:25 +02004 * @author Michal Vasko <mvasko@cesnet.cz>
Radek Krejcie7b95092019-05-15 11:03:07 +02005 * @brief internal functions for YANG schema trees.
6 *
Michal Vasko271d2e32023-01-31 15:43:19 +01007 * Copyright (c) 2015 - 2023 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_INTERNAL_H_
17#define LY_TREE_DATA_INTERNAL_H_
18
Radek Krejci857189e2020-09-01 13:26:36 +020019#include "log.h"
Radek Krejciaca74032019-06-04 08:53:06 +020020#include "plugins_types.h"
Michal Vasko60ea6352020-06-29 13:39:39 +020021#include "tree_data.h"
Radek Krejcie7b95092019-05-15 11:03:07 +020022
Michal Vasko52927e22020-03-16 17:26:14 +010023#include <stddef.h>
24
Michal Vasko004d3152020-06-11 19:59:22 +020025struct ly_path_predicate;
Michal Vasko8cc3f662022-03-29 11:25:51 +020026struct lyd_ctx;
Michal Vaskoa6669ba2020-08-06 16:14:26 +020027struct lysc_module;
Michal Vasko004d3152020-06-11 19:59:22 +020028
Radek Krejcif13b87b2020-12-01 22:02:17 +010029#define LY_XML_SUFFIX ".xml"
30#define LY_XML_SUFFIX_LEN 4
31#define LY_JSON_SUFFIX ".json"
32#define LY_JSON_SUFFIX_LEN 5
33#define LY_LYB_SUFFIX ".lyb"
34#define LY_LYB_SUFFIX_LEN 4
35
Radek Krejcie7b95092019-05-15 11:03:07 +020036/**
Michal Vasko271d2e32023-01-31 15:43:19 +010037 * @brief Internal item structure for remembering "used" instances of duplicate node instances.
Michal Vaskod7c048c2021-05-18 16:12:55 +020038 */
39struct lyd_dup_inst {
Michal Vasko271d2e32023-01-31 15:43:19 +010040 struct ly_set *set;
Michal Vaskod7c048c2021-05-18 16:12:55 +020041 uint32_t used;
42};
43
44/**
Michal Vasko271d2e32023-01-31 15:43:19 +010045 * @brief Update a found inst using a duplicate instance cache hash table. Needs to be called for every "used"
Michal Vaskod7c048c2021-05-18 16:12:55 +020046 * (that should not be considered next time) instance.
47 *
48 * @param[in,out] inst Found instance, is updated so that the same instance is not returned twice.
49 * @param[in] siblings Siblings where @p inst was found.
Michal Vasko271d2e32023-01-31 15:43:19 +010050 * @param[in] dup_inst_ht Duplicate instance cache hash table.
Michal Vaskod7c048c2021-05-18 16:12:55 +020051 * @return LY_ERR value.
52 */
Michal Vasko8efac242023-03-30 08:24:56 +020053LY_ERR lyd_dup_inst_next(struct lyd_node **inst, const struct lyd_node *siblings, struct ly_ht **dup_inst_ht);
Michal Vaskod7c048c2021-05-18 16:12:55 +020054
55/**
56 * @brief Free duplicate instance cache.
57 *
Michal Vasko271d2e32023-01-31 15:43:19 +010058 * @param[in] dup_inst Duplicate instance cache hash table to free.
Michal Vaskod7c048c2021-05-18 16:12:55 +020059 */
Michal Vasko8efac242023-03-30 08:24:56 +020060void lyd_dup_inst_free(struct ly_ht *dup_inst_ht);
Michal Vaskod7c048c2021-05-18 16:12:55 +020061
62/**
Radek Krejci8678fa42020-08-18 16:07:28 +020063 * @brief Just like ::lys_getnext() but iterates over all data instances of the schema nodes.
Michal Vaskoa6669ba2020-08-06 16:14:26 +020064 *
65 * @param[in] last Last returned data node.
66 * @param[in] sibling Data node sibling to search in.
67 * @param[in,out] slast Schema last node, set to NULL for first call and do not change afterwards.
68 * May not be set if the function is used only for any suitable node existence check (such as the existence
69 * of any choice case data).
70 * @param[in] parent Schema parent of the iterated children nodes.
71 * @param[in] module Schema module of the iterated top-level nodes.
72 * @return Next matching data node,
73 * @return NULL if last data node was already returned.
74 */
75struct lyd_node *lys_getnext_data(const struct lyd_node *last, const struct lyd_node *sibling,
Michal Vasko106f0862021-11-02 11:49:27 +010076 const struct lysc_node **slast, const struct lysc_node *parent, const struct lysc_module *module);
77
78/**
79 * @brief Get address of a node's child pointer if any.
80 *
81 * @param[in] node Node to check.
82 * @return Address of the node's child member,
83 * @return NULL if there is no child pointer.
84 */
85struct lyd_node **lyd_node_child_p(struct lyd_node *node);
86
87/**
88 * @brief Update node pointer to point to the first data node of a module, leave unchanged if there is none.
89 *
90 * @param[in,out] node Node pointer, may be updated.
91 * @param[in] mod Module whose data to search for.
92 */
93void lyd_first_module_sibling(struct lyd_node **node, const struct lys_module *mod);
94
95/**
96 * @brief Iterate over implemented modules for functions that accept specific modules or the whole context.
97 *
98 * @param[in] tree Data tree.
99 * @param[in] module Selected module, NULL for all.
100 * @param[in] ctx Context, NULL for selected modules.
101 * @param[in,out] i Iterator, set to 0 on first call.
102 * @param[out] first First sibling of the returned module.
103 * @return Next module.
104 * @return NULL if all modules were traversed.
105 */
106const struct lys_module *lyd_mod_next_module(struct lyd_node *tree, const struct lys_module *module,
107 const struct ly_ctx *ctx, uint32_t *i, struct lyd_node **first);
108
109/**
110 * @brief Iterate over modules for functions that want to traverse all the top-level data.
111 *
112 * @param[in,out] next Pointer to the next module data, set to first top-level sibling on first call.
113 * @param[out] first First sibling of the returned module.
114 * @return Next module.
115 * @return NULL if all modules were traversed.
116 */
117const struct lys_module *lyd_data_next_module(struct lyd_node **next, struct lyd_node **first);
118
119/**
Michal Vasko4754d4a2022-12-01 10:11:21 +0100120 * @brief Set dflt flag for a NP container if applicable, recursively for parents.
121 *
122 * @param[in] node Node whose criteria for the dflt flag has changed.
123 */
124void lyd_cont_set_dflt(struct lyd_node *node);
125
126/**
Michal Vasko59892dd2022-05-13 11:02:30 +0200127 * @brief Search in the given siblings (NOT recursively) for the first schema node data instance.
128 * Uses hashes - should be used whenever possible for best performance.
129 *
130 * @param[in] siblings Siblings to search in including preceding and succeeding nodes.
131 * @param[in] schema Target data node schema to find.
132 * @param[out] match Can be NULL, otherwise the found data node.
133 * @return LY_SUCCESS on success, @p match set.
134 * @return LY_ENOTFOUND if not found, @p match set to NULL.
135 * @return LY_ERR value if another error occurred.
136 */
137LY_ERR lyd_find_sibling_schema(const struct lyd_node *siblings, const struct lysc_node *schema, struct lyd_node **match);
138
139/**
Michal Vasko106f0862021-11-02 11:49:27 +0100140 * @brief Check whether a node to be deleted is the root node, move it if it is.
141 *
142 * @param[in] root Root sibling.
143 * @param[in] to_del Node to be deleted.
144 * @param[in] mod If set, it is expected @p tree should point to the first node of @p mod. Otherwise it will simply be
145 * the first top-level sibling.
146 */
147void lyd_del_move_root(struct lyd_node **root, const struct lyd_node *to_del, const struct lys_module *mod);
148
149/**
Michal Vasko8cc3f662022-03-29 11:25:51 +0200150 * @brief Try to get schema node for data with a parent based on an extension instance.
151 *
152 * @param[in] parent Parsed parent data node. Set if @p sparent is NULL.
153 * @param[in] sparent Schema parent node. Set if @p sparent is NULL.
154 * @param[in] prefix Element prefix, if any.
155 * @param[in] prefix_len Length of @p prefix.
156 * @param[in] format Format of @p prefix.
157 * @param[in] prefix_data Format-specific data.
158 * @param[in] name Element name.
159 * @param[in] name_len Length of @p name.
160 * @param[out] snode Found schema node, NULL if no suitable was found.
Michal Vasko66330fc2022-11-21 15:52:24 +0100161 * @param[out] ext Optional extension instance that provided @p snode.
Michal Vasko8cc3f662022-03-29 11:25:51 +0200162 * @return LY_SUCCESS on success;
163 * @return LY_ENOT if no extension instance parsed the data;
164 * @return LY_ERR on error.
165 */
166LY_ERR ly_nested_ext_schema(const struct lyd_node *parent, const struct lysc_node *sparent, const char *prefix,
167 size_t prefix_len, LY_VALUE_FORMAT format, void *prefix_data, const char *name, size_t name_len,
168 const struct lysc_node **snode, struct lysc_ext_instance **ext);
169
170/**
Michal Vasko106f0862021-11-02 11:49:27 +0100171 * @brief Free stored prefix data.
172 *
173 * @param[in] format Format of the prefixes.
174 * @param[in] prefix_data Format-specific data to free:
175 * LY_PREF_SCHEMA - const struct lysp_module * (module used for resolving prefixes from imports)
176 * LY_PREF_SCHEMA_RESOLVED - struct lyd_value_prefix * (sized array of pairs: prefix - module)
177 * LY_PREF_XML - const struct ly_set * (set with defined namespaces stored as ::lyxml_ns)
178 * LY_PREF_JSON - NULL
179 */
180void ly_free_prefix_data(LY_VALUE_FORMAT format, void *prefix_data);
181
182/**
183 * @brief Duplicate prefix data.
184 *
185 * @param[in] ctx libyang context.
186 * @param[in] format Format of the prefixes in the value.
187 * @param[in] prefix_data Prefix data to duplicate.
188 * @param[out] prefix_data_p Duplicated prefix data.
189 * @return LY_ERR value.
190 */
191LY_ERR ly_dup_prefix_data(const struct ly_ctx *ctx, LY_VALUE_FORMAT format, const void *prefix_data, void **prefix_data_p);
192
193/**
194 * @brief Store used prefixes in a string.
195 *
196 * If @p prefix_data_p are non-NULL, they are treated as valid according to the @p format_p and new possible
197 * prefixes are simply added. This way it is possible to store prefix data for several strings together.
198 *
199 * @param[in] ctx libyang context.
200 * @param[in] value Value to be parsed.
201 * @param[in] value_len Length of the @p value.
202 * @param[in] format Format of the prefixes in the value.
203 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
204 * @param[in,out] format_p Resulting format of the prefixes.
205 * @param[in,out] prefix_data_p Resulting prefix data for the value in format @p format_p.
206 * @return LY_ERR value.
207 */
208LY_ERR ly_store_prefix_data(const struct ly_ctx *ctx, const void *value, size_t value_len, LY_VALUE_FORMAT format,
209 const void *prefix_data, LY_VALUE_FORMAT *format_p, void **prefix_data_p);
210
211/**
212 * @brief Get string name of the format.
213 *
214 * @param[in] format Format whose name to get.
215 * @return Format string name.
216 */
217const char *ly_format2str(LY_VALUE_FORMAT format);
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200218
219/**
Michal Vasko9b368d32020-02-14 13:53:31 +0100220 * @brief Create a term (leaf/leaf-list) node from a string value.
221 *
222 * Hash is calculated and new node flag is set.
Michal Vasko90932a92020-02-12 14:33:03 +0100223 *
224 * @param[in] schema Schema node of the new data node.
225 * @param[in] value String value to be parsed.
Michal Vaskof03ed032020-03-04 13:31:44 +0100226 * @param[in] value_len Length of @p value, must be set correctly.
Michal Vasko989cdb42023-10-06 15:32:37 +0200227 * @param[in] is_utf8 Whether @p value is a valid UTF-8 string, if applicable.
Michal Vasko90932a92020-02-12 14:33:03 +0100228 * @param[in,out] dynamic Flag if @p value is dynamically allocated, is adjusted when @p value is consumed.
Michal Vasko90932a92020-02-12 14:33:03 +0100229 * @param[in] format Input format of @p value.
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200230 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200231 * @param[in] hints [Value hints](@ref lydvalhints) from the parser regarding the value type.
232 * @param[out] incomplete Whether the value needs to be resolved.
Michal Vasko90932a92020-02-12 14:33:03 +0100233 * @param[out] node Created node.
234 * @return LY_SUCCESS on success.
235 * @return LY_EINCOMPLETE in case data tree is needed to finish the validation.
236 * @return LY_ERR value if an error occurred.
237 */
Michal Vasko989cdb42023-10-06 15:32:37 +0200238LY_ERR lyd_create_term(const struct lysc_node *schema, const char *value, size_t value_len, ly_bool is_utf8,
239 ly_bool *dynamic, LY_VALUE_FORMAT format, void *prefix_data, uint32_t hints, ly_bool *incomplete,
240 struct lyd_node **node);
Michal Vasko90932a92020-02-12 14:33:03 +0100241
242/**
Michal Vasko9b368d32020-02-14 13:53:31 +0100243 * @brief Create a term (leaf/leaf-list) node from a parsed value by duplicating it.
244 *
245 * Hash is calculated and new node flag is set.
246 *
247 * @param[in] schema Schema node of the new data node.
248 * @param[in] val Parsed value to use.
249 * @param[out] node Created node.
250 * @return LY_SUCCESS on success.
251 * @return LY_ERR value if an error occurred.
252 */
253LY_ERR lyd_create_term2(const struct lysc_node *schema, const struct lyd_value *val, struct lyd_node **node);
254
255/**
256 * @brief Create an inner (container/list/RPC/action/notification) node.
257 *
258 * Hash is calculated and new node flag is set except
259 * for list with keys, when the hash is not calculated!
260 * Also, non-presence container has its default flag set.
Michal Vasko90932a92020-02-12 14:33:03 +0100261 *
262 * @param[in] schema Schema node of the new data node.
263 * @param[out] node Created node.
264 * @return LY_SUCCESS on success.
265 * @return LY_ERR value if an error occurred.
266 */
267LY_ERR lyd_create_inner(const struct lysc_node *schema, struct lyd_node **node);
268
269/**
Michal Vasko9b368d32020-02-14 13:53:31 +0100270 * @brief Create a list with all its keys (cannot be used for key-less list).
271 *
272 * Hash is calculated and new node flag is set.
Michal Vasko90932a92020-02-12 14:33:03 +0100273 *
274 * @param[in] schema Schema node of the new data node.
Michal Vasko004d3152020-06-11 19:59:22 +0200275 * @param[in] predicates Compiled key list predicates.
Michal Vasko90189962023-02-28 12:10:34 +0100276 * @param[in] vars Array of defined variables to use in predicates, may be NULL.
Michal Vasko90932a92020-02-12 14:33:03 +0100277 * @param[out] node Created node.
278 * @return LY_SUCCESS on success.
279 * @return LY_ERR value if an error occurred.
280 */
Michal Vasko90189962023-02-28 12:10:34 +0100281LY_ERR lyd_create_list(const struct lysc_node *schema, const struct ly_path_predicate *predicates,
282 const struct lyxp_var *vars, struct lyd_node **node);
Michal Vasko90932a92020-02-12 14:33:03 +0100283
284/**
Michal Vasko59892dd2022-05-13 11:02:30 +0200285 * @brief Create a list with all its keys (cannot be used for key-less list).
286 *
287 * Hash is calculated and new node flag is set.
288 *
289 * @param[in] schema Schema node of the new data node.
290 * @param[in] keys Key list predicates.
291 * @param[in] keys_len Length of @p keys.
292 * @param[out] node Created node.
293 * @return LY_SUCCESS on success.
294 * @return LY_ERR value if an error occurred.
295 */
296LY_ERR lyd_create_list2(const struct lysc_node *schema, const char *keys, size_t keys_len, struct lyd_node **node);
297
298/**
Michal Vasko9b368d32020-02-14 13:53:31 +0100299 * @brief Create an anyxml/anydata node.
300 *
301 * Hash is calculated and flags are properly set based on @p is_valid.
Michal Vasko90932a92020-02-12 14:33:03 +0100302 *
303 * @param[in] schema Schema node of the new data node.
Michal Vasko366a4a12020-12-04 16:23:57 +0100304 * @param[in] value Value of the any node.
Michal Vasko90932a92020-02-12 14:33:03 +0100305 * @param[in] value_type Value type of the value.
Michal Vasko742a5b12022-02-24 16:07:27 +0100306 * @param[in] use_value Whether to use dynamic @p value or duplicate it.
Michal Vasko90932a92020-02-12 14:33:03 +0100307 * @param[out] node Created node.
308 * @return LY_SUCCESS on success.
309 * @return LY_ERR value if an error occurred.
310 */
Michal Vasko9b368d32020-02-14 13:53:31 +0100311LY_ERR lyd_create_any(const struct lysc_node *schema, const void *value, LYD_ANYDATA_VALUETYPE value_type,
Michal Vasko366a4a12020-12-04 16:23:57 +0100312 ly_bool use_value, struct lyd_node **node);
Michal Vasko90932a92020-02-12 14:33:03 +0100313
314/**
Michal Vasko52927e22020-03-16 17:26:14 +0100315 * @brief Create an opaque node.
316 *
317 * @param[in] ctx libyang context.
318 * @param[in] name Element name.
319 * @param[in] name_len Length of @p name, must be set correctly.
Michal Vasko52927e22020-03-16 17:26:14 +0100320 * @param[in] prefix Element prefix.
321 * @param[in] pref_len Length of @p prefix, must be set correctly.
Radek Krejci1798aae2020-07-14 13:26:06 +0200322 * @param[in] module_key Mandatory key to reference module, can be namespace or name.
323 * @param[in] module_key_len Length of @p module_key, must be set correctly.
Michal Vasko501af032020-11-11 20:27:44 +0100324 * @param[in] value String value to be parsed.
325 * @param[in] value_len Length of @p value, must be set correctly.
326 * @param[in,out] dynamic Flag if @p value is dynamically allocated, is adjusted when @p value is consumed.
327 * @param[in] format Input format of @p value and @p ns.
Radek Krejciec9ad602021-01-04 10:46:30 +0100328 * @param[in] val_prefix_data Format-specific prefix data, param is spent (even in case the function fails):
329 * LY_PREF_SCHEMA - const struct lysp_module * (module used for resolving prefixes from imports)
330 * LY_PREF_SCHEMA_RESOLVED - struct lyd_value_prefix * (sized array of pairs: prefix - module)
331 * LY_PREF_XML - const struct ly_set * (set with defined namespaces stored as ::lyxml_ns)
332 * LY_PREF_JSON - NULL
Michal Vasko501af032020-11-11 20:27:44 +0100333 * @param[in] hints [Hints](@ref lydhints) from the parser regarding the node/value type.
Michal Vasko52927e22020-03-16 17:26:14 +0100334 * @param[out] node Created node.
335 * @return LY_SUCCESS on success.
336 * @return LY_ERR value if an error occurred.
337 */
Michal Vasko501af032020-11-11 20:27:44 +0100338LY_ERR lyd_create_opaq(const struct ly_ctx *ctx, const char *name, size_t name_len, const char *prefix, size_t pref_len,
339 const char *module_key, size_t module_key_len, const char *value, size_t value_len, ly_bool *dynamic,
Radek Krejci8df109d2021-04-23 12:19:08 +0200340 LY_VALUE_FORMAT format, void *val_prefix_data, uint32_t hints, struct lyd_node **node);
Michal Vasko52927e22020-03-16 17:26:14 +0100341
342/**
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200343 * @brief Check the existence and create any non-existing implicit siblings, recursively for the created nodes.
344 *
345 * @param[in] parent Parent of the potential default values, NULL for top-level siblings.
346 * @param[in,out] first First sibling.
347 * @param[in] sparent Schema parent of the siblings, NULL if schema of @p parent can be used.
348 * @param[in] mod Module of the default values, NULL for nested siblings.
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200349 * @param[in] node_when Optional set to add nodes with "when" conditions into.
Michal Vaskoc43c8ab2021-03-05 13:32:44 +0100350 * @param[in] node_types Optional set to add nodes with unresolved types into.
Michal Vaskofcbd78f2022-08-26 08:34:15 +0200351 * @param[in] ext_node Optional set to add nodes with extension instance node callbacks into.
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200352 * @param[in] impl_opts Implicit options (@ref implicitoptions).
353 * @param[in,out] diff Validation diff.
354 * @return LY_ERR value.
355 */
356LY_ERR lyd_new_implicit_r(struct lyd_node *parent, struct lyd_node **first, const struct lysc_node *sparent,
Michal Vaskofcbd78f2022-08-26 08:34:15 +0200357 const struct lys_module *mod, struct ly_set *node_when, struct ly_set *node_types, struct ly_set *ext_node,
358 uint32_t impl_opts, struct lyd_node **diff);
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200359
360/**
Michal Vaskob104f112020-07-17 09:54:54 +0200361 * @brief Find the next node, before which to insert the new node.
Michal Vasko90932a92020-02-12 14:33:03 +0100362 *
Michal Vaskob104f112020-07-17 09:54:54 +0200363 * @param[in] first_sibling First sibling of the nodes to consider.
364 * @param[in] new_node Node that will be inserted.
365 * @return Node to insert after.
366 * @return NULL if the new node should be first.
Michal Vasko90932a92020-02-12 14:33:03 +0100367 */
Michal Vaskob104f112020-07-17 09:54:54 +0200368struct lyd_node *lyd_insert_get_next_anchor(const struct lyd_node *first_sibling, const struct lyd_node *new_node);
Michal Vasko90932a92020-02-12 14:33:03 +0100369
370/**
Michal Vaskoc61dd062022-06-07 11:01:28 +0200371 * @brief Insert node after a sibling.
372 *
373 * Handles inserting into NP containers and key-less lists.
374 *
375 * @param[in] sibling Sibling to insert after.
376 * @param[in] node Node to insert.
377 */
378void lyd_insert_after_node(struct lyd_node *sibling, struct lyd_node *node);
379
380/**
381 * @brief Insert node before a sibling.
382 *
383 * Handles inserting into NP containers and key-less lists.
384 *
385 * @param[in] sibling Sibling to insert before.
386 * @param[in] node Node to insert.
387 */
388void lyd_insert_before_node(struct lyd_node *sibling, struct lyd_node *node);
389
390/**
Michal Vaskob104f112020-07-17 09:54:54 +0200391 * @brief Insert a node into parent/siblings. Order and hashes are fully handled.
Michal Vasko90932a92020-02-12 14:33:03 +0100392 *
Michal Vasko9b368d32020-02-14 13:53:31 +0100393 * @param[in] parent Parent to insert into, NULL for top-level sibling.
394 * @param[in,out] first_sibling First sibling, NULL if no top-level sibling exist yet. Can be also NULL if @p parent is set.
Michal Vasko90932a92020-02-12 14:33:03 +0100395 * @param[in] node Individual node (without siblings) to insert.
aPiecek827cfac2023-12-01 14:56:12 +0100396 * @param[in] last If set, do not search for the correct anchor but always insert at the end.
397 * For (leaf-)lists that have the LYS_ORDBY_SYSTEM flag set, the @p last (due to optimization) causes
398 * the sorting tree (lyds_tree) not to be created. However, it is possible to implicitly create
399 * the lyds_tree by inserting another node without setting the @p last. After that, the @p last MUST NOT be
400 * set for a given (leaf-list) instance, as this will cause the order to be corrupted.
Michal Vasko90932a92020-02-12 14:33:03 +0100401 */
Michal Vasko6ee6f432021-07-16 09:49:14 +0200402void lyd_insert_node(struct lyd_node *parent, struct lyd_node **first_sibling, struct lyd_node *node, ly_bool last);
Michal Vasko90932a92020-02-12 14:33:03 +0100403
404/**
Michal Vasko2e784f82024-01-11 09:51:22 +0100405 * @brief Unlink the specified data subtree.
406 *
407 * @param[in] node Data tree node to be unlinked (together with all the children).
408 */
409void lyd_unlink(struct lyd_node *node);
410
411/**
Michal Vaskoa5da3292020-08-12 13:10:50 +0200412 * @brief Insert a metadata (last) into a parent
413 *
414 * @param[in] parent Parent of the metadata.
415 * @param[in] meta Metadata (list) to be added into the @p parent.
Michal Vasko871a0252020-11-11 18:35:24 +0100416 * @param[in] clear_dflt Whether to clear dflt flag starting from @p parent, recursively all NP containers.
Michal Vaskoa5da3292020-08-12 13:10:50 +0200417 */
Michal Vasko871a0252020-11-11 18:35:24 +0100418void lyd_insert_meta(struct lyd_node *parent, struct lyd_meta *meta, ly_bool clear_dflt);
Michal Vaskoa5da3292020-08-12 13:10:50 +0200419
420/**
aPiecek0e92afc2023-11-08 10:48:02 +0100421 * @brief Unlink a single metadata instance.
422 *
423 * @param[in] meta Metadata to unlink.
424 */
425void lyd_unlink_meta_single(struct lyd_meta *meta);
426
427/**
Michal Vasko52927e22020-03-16 17:26:14 +0100428 * @brief Create and insert a metadata (last) into a parent.
Michal Vasko90932a92020-02-12 14:33:03 +0100429 *
Michal Vasko52927e22020-03-16 17:26:14 +0100430 * @param[in] parent Parent of the metadata, can be NULL.
Michal Vasko9f96a052020-03-10 09:41:45 +0100431 * @param[in,out] meta Metadata list to add at its end if @p parent is NULL, returned created attribute.
432 * @param[in] mod Metadata module (with the annotation definition).
Michal Vasko90932a92020-02-12 14:33:03 +0100433 * @param[in] name Attribute name.
Michal Vaskof03ed032020-03-04 13:31:44 +0100434 * @param[in] name_len Length of @p name, must be set correctly.
Michal Vasko90932a92020-02-12 14:33:03 +0100435 * @param[in] value String value to be parsed.
Michal Vaskof03ed032020-03-04 13:31:44 +0100436 * @param[in] value_len Length of @p value, must be set correctly.
Michal Vasko989cdb42023-10-06 15:32:37 +0200437 * @param[in] is_utf8 Whether @p value is a valid UTF-8 string, if applicable.
Michal Vasko90932a92020-02-12 14:33:03 +0100438 * @param[in,out] dynamic Flag if @p value is dynamically allocated, is adjusted when @p value is consumed.
Michal Vasko90932a92020-02-12 14:33:03 +0100439 * @param[in] format Input format of @p value.
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200440 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200441 * @param[in] hints [Value hints](@ref lydvalhints) from the parser regarding the value type.
Michal Vaskoddd76592022-01-17 13:34:48 +0100442 * @param[in] ctx_node Value context node, may be NULL for metadata.
Michal Vasko871a0252020-11-11 18:35:24 +0100443 * @param[in] clear_dflt Whether to clear dflt flag starting from @p parent, recursively all NP containers.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200444 * @param[out] incomplete Whether the value needs to be resolved.
Michal Vasko90932a92020-02-12 14:33:03 +0100445 * @return LY_SUCCESS on success.
446 * @return LY_EINCOMPLETE in case data tree is needed to finish the validation.
447 * @return LY_ERR value if an error occurred.
448 */
Michal Vasko9f96a052020-03-10 09:41:45 +0100449LY_ERR lyd_create_meta(struct lyd_node *parent, struct lyd_meta **meta, const struct lys_module *mod, const char *name,
Michal Vasko989cdb42023-10-06 15:32:37 +0200450 size_t name_len, const char *value, size_t value_len, ly_bool is_utf8, ly_bool *dynamic, LY_VALUE_FORMAT format,
Michal Vaskoddd76592022-01-17 13:34:48 +0100451 void *prefix_data, uint32_t hints, const struct lysc_node *ctx_node, ly_bool clear_dflt, ly_bool *incomplete);
Radek Krejci1798aae2020-07-14 13:26:06 +0200452
453/**
aPiecek41680342023-11-08 10:19:44 +0100454 * @brief Create a copy of the metadata.
455 *
456 * @param[in] parent_ctx Target context for duplicated nodes.
457 * @param[in] meta Metadata to copy.
458 * @param[in] parent Node where to append the new metadata.
459 * @param[out] dup Optional created metadata copy.
460 * @return LY_ERR value.
461 */
462LY_ERR lyd_dup_meta_single_to_ctx(const struct ly_ctx *parent_ctx, const struct lyd_meta *meta, struct lyd_node *parent,
463 struct lyd_meta **dup);
464
465/**
Michal Vaskoa5da3292020-08-12 13:10:50 +0200466 * @brief Insert an attribute (last) into a parent
Radek Krejci1798aae2020-07-14 13:26:06 +0200467 *
Michal Vaskoa5da3292020-08-12 13:10:50 +0200468 * @param[in] parent Parent of the attributes.
469 * @param[in] attr Attribute (list) to be added into the @p parent.
Radek Krejci1798aae2020-07-14 13:26:06 +0200470 */
Michal Vaskoa5da3292020-08-12 13:10:50 +0200471void lyd_insert_attr(struct lyd_node *parent, struct lyd_attr *attr);
Michal Vasko90932a92020-02-12 14:33:03 +0100472
473/**
Michal Vasko52927e22020-03-16 17:26:14 +0100474 * @brief Create and insert a generic attribute (last) into a parent.
475 *
476 * @param[in] parent Parent of the attribute, can be NULL.
477 * @param[in,out] attr Attribute list to add at its end if @p parent is NULL, returned created attribute.
478 * @param[in] ctx libyang context.
479 * @param[in] name Attribute name.
480 * @param[in] name_len Length of @p name, must be set correctly.
Michal Vasko52927e22020-03-16 17:26:14 +0100481 * @param[in] prefix Attribute prefix.
482 * @param[in] prefix_len Attribute prefix length.
Radek Krejci1798aae2020-07-14 13:26:06 +0200483 * @param[in] module_key Mandatory key to reference module, can be namespace or name.
484 * @param[in] module_key_len Length of @p module_key, must be set correctly.
Michal Vasko501af032020-11-11 20:27:44 +0100485 * @param[in] value String value to be parsed.
486 * @param[in] value_len Length of @p value, must be set correctly.
487 * @param[in,out] dynamic Flag if @p value is dynamically allocated, is adjusted when @p value is consumed.
488 * @param[in] format Input format of @p value and @p ns.
489 * @param[in] val_prefix_data Format-specific prefix data, param is spent (even in case the function fails).
490 * @param[in] hints [Hints](@ref lydhints) from the parser regarding the node/value type.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200491 * @return LY_SUCCESS on success,
492 * @return LY_ERR value on error.
Michal Vasko52927e22020-03-16 17:26:14 +0100493 */
Radek Krejci1798aae2020-07-14 13:26:06 +0200494LY_ERR lyd_create_attr(struct lyd_node *parent, struct lyd_attr **attr, const struct ly_ctx *ctx, const char *name,
Michal Vasko501af032020-11-11 20:27:44 +0100495 size_t name_len, const char *prefix, size_t prefix_len, const char *module_key, size_t module_key_len,
Radek Krejci8df109d2021-04-23 12:19:08 +0200496 const char *value, size_t value_len, ly_bool *dynamic, LY_VALUE_FORMAT format, void *val_prefix_data, uint32_t hints);
Radek Krejci1798aae2020-07-14 13:26:06 +0200497
498/**
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200499 * @brief Store and canonize the given @p value into @p val according to the schema node type rules.
Radek Krejci38d85362019-09-05 16:26:38 +0200500 *
Michal Vasko8d544252020-03-02 10:19:52 +0100501 * @param[in] ctx libyang context.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200502 * @param[in,out] val Storage for the value.
503 * @param[in] type Type of the value.
Radek Krejcif9943642021-04-26 10:18:21 +0200504 * @param[in] value Value to be parsed, must not be NULL.
Michal Vaskof03ed032020-03-04 13:31:44 +0100505 * @param[in] value_len Length of the give @p value, must be set correctly.
Michal Vasko989cdb42023-10-06 15:32:37 +0200506 * @param[in] is_utf8 Whether @p value is a valid UTF-8 string, if applicable.
Michal Vasko90932a92020-02-12 14:33:03 +0100507 * @param[in,out] dynamic Flag if @p value is dynamically allocated, is adjusted when @p value is consumed.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200508 * @param[in] format Input format of @p value.
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200509 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200510 * @param[in] hints [Value hints](@ref lydvalhints) from the parser.
511 * @param[in] ctx_node Context schema node.
512 * @param[out] incomplete Optional, set if the value also needs to be resolved.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200513 * @return LY_SUCCESS on success,
514 * @return LY_ERR value on error.
Radek Krejci38d85362019-09-05 16:26:38 +0200515 */
Radek Krejcif9943642021-04-26 10:18:21 +0200516LY_ERR lyd_value_store(const struct ly_ctx *ctx, struct lyd_value *val, const struct lysc_type *type, const void *value,
Michal Vasko989cdb42023-10-06 15:32:37 +0200517 size_t value_len, ly_bool is_utf8, ly_bool *dynamic, LY_VALUE_FORMAT format, void *prefix_data, uint32_t hints,
Radek Krejci2efc45b2020-12-22 16:25:44 +0100518 const struct lysc_node *ctx_node, ly_bool *incomplete);
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200519
520/**
521 * @brief Validate previously incompletely stored value.
522 *
523 * @param[in] ctx libyang context.
524 * @param[in] type Schema type of the value (not the stored one, but the original one).
525 * @param[in,out] val Stored value to resolve.
526 * @param[in] ctx_node Context node for the resolution.
527 * @param[in] tree Data tree for the resolution.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200528 * @return LY_SUCCESS on success,
529 * @return LY_ERR value on error.
530 */
531LY_ERR lyd_value_validate_incomplete(const struct ly_ctx *ctx, const struct lysc_type *type, struct lyd_value *val,
Radek Krejci2efc45b2020-12-22 16:25:44 +0100532 const struct lyd_node *ctx_node, const struct lyd_node *tree);
Radek Krejci38d85362019-09-05 16:26:38 +0200533
Michal Vaskoaebbce02021-04-06 09:23:37 +0200534/**
Michal Vasko583b4642023-05-25 10:39:34 +0200535 * @brief Check type restrictions applicable to the particular leaf/leaf-list with the given string @p value.
Michal Vaskoaebbce02021-04-06 09:23:37 +0200536 *
537 * This function check just the type's restriction, if you want to check also the data tree context (e.g. in case of
538 * require-instance restriction), use ::lyd_value_validate().
539 *
540 * @param[in] ctx libyang context for logging (function does not log errors when @p ctx is NULL)
541 * @param[in] node Schema node for the @p value.
542 * @param[in] value String value to be checked, expected to be in JSON format.
543 * @param[in] value_len Length of the given @p value (mandatory).
544 * @param[in] format Value prefix format.
545 * @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
Michal Vasko583b4642023-05-25 10:39:34 +0200546 * @param[in] hints Value encoding hints.
Michal Vaskoaebbce02021-04-06 09:23:37 +0200547 * @return LY_SUCCESS on success
548 * @return LY_ERR value if an error occurred.
549 */
Michal Vasko583b4642023-05-25 10:39:34 +0200550LY_ERR ly_value_validate(const struct ly_ctx *ctx, const struct lysc_node *node, const char *value, size_t value_len,
551 LY_VALUE_FORMAT format, void *prefix_data, uint32_t hints);
Michal Vaskof937cfe2020-08-03 16:07:12 +0200552
Radek Krejci38d85362019-09-05 16:26:38 +0200553/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200554 * @defgroup datahash Data nodes hash manipulation
555 * @ingroup datatree
Michal Vasko8081a812021-07-15 09:19:43 +0200556 * @{
Radek Krejcie7b95092019-05-15 11:03:07 +0200557 */
558
559/**
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200560 * @brief Generate hash for the node.
561 *
562 * @param[in] node Data node to (re)generate hash value.
563 * @return LY_ERR value.
564 */
565LY_ERR lyd_hash(struct lyd_node *node);
566
567/**
568 * @brief Insert hash of the node into the hash table of its parent.
569 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200570 * @param[in] node Data node which hash will be inserted into the ::lyd_node_inner.children_ht hash table of its parent.
Radek Krejci1f05b6a2019-07-18 16:15:06 +0200571 * @return LY_ERR value.
572 */
573LY_ERR lyd_insert_hash(struct lyd_node *node);
574
575/**
Radek Krejcie7b95092019-05-15 11:03:07 +0200576 * @brief Maintain node's parent's children hash table when unlinking the node.
577 *
578 * When completely freeing data tree, it is expected to free the parent's children hash table first, at once.
579 *
580 * @param[in] node The data node being unlinked from its parent.
581 */
582void lyd_unlink_hash(struct lyd_node *node);
583
584/** @} datahash */
585
Radek Krejci084289f2019-07-09 17:35:30 +0200586/**
Michal Vaskod59035b2020-07-08 12:00:06 +0200587 * @brief Append all list key predicates to path.
588 *
589 * @param[in] node Node with keys to print.
590 * @param[in,out] buffer Buffer to print to.
591 * @param[in,out] buflen Current buffer length.
592 * @param[in,out] bufused Current number of characters used in @p buffer.
593 * @param[in] is_static Whether buffer is static or can be reallocated.
Michal Vaskodbf3e652022-10-21 08:46:25 +0200594 * @return LY_ERR value.
Michal Vaskod59035b2020-07-08 12:00:06 +0200595 */
Radek Krejci857189e2020-09-01 13:26:36 +0200596LY_ERR lyd_path_list_predicate(const struct lyd_node *node, char **buffer, size_t *buflen, size_t *bufused, ly_bool is_static);
Michal Vaskod59035b2020-07-08 12:00:06 +0200597
Michal Vasko413af592021-12-13 11:50:51 +0100598/**
Michal Vaskodbf3e652022-10-21 08:46:25 +0200599 * @brief Generate a path similar to ::lyd_path() except read the parents from a set.
600 *
601 * @param[in] dnodes Set with the data nodes, from parent to the last descendant.
602 * @param[in] pathtype Type of data path to generate.
603 * @return Generated data path.
604 */
605char *lyd_path_set(const struct ly_set *dnodes, LYD_PATH_TYPE pathtype);
606
607/**
Michal Vasko413af592021-12-13 11:50:51 +0100608 * @brief Remove an object on the specific set index keeping the order of the other objects.
609 *
610 * @param[in] set Set from which a node will be removed.
611 * @param[in] index Index of the object to remove in the \p set.
612 * @param[in] destructor Optional function to free the objects being removed.
Michal Vaskodbf3e652022-10-21 08:46:25 +0200613 * @return LY_ERR value.
Michal Vasko413af592021-12-13 11:50:51 +0100614 */
615LY_ERR ly_set_rm_index_ordered(struct ly_set *set, uint32_t index, void (*destructor)(void *obj));
616
stewegf9041a22024-01-18 13:29:12 +0100617/**
618 * @brief Frees data within leafref links record
619 *
620 * @param[in] rec The leafref links record
621 */
622void lyd_free_leafref_links_rec(struct lyd_leafref_links_rec *rec);
623
624/**
625 * @brief Frees all leafref nodes and target node of given data node
626 *
627 * @param[in] node The data node, which leafref nodes and/or target node should be cleared.
628 */
629void lyd_free_leafref_nodes(const struct lyd_node_term *node);
630
631/**
632 * @brief Gets or creates the leafref links record.
633 *
634 * @param[in] node The term data node.
635 * @param[out] record The leafref links record.
636 * @param[in] create Whether to create record if not exists.
637 * @return LY_SUCCESS on success.
638 * @return LY_ERR value on error.
639 */
640LY_ERR lyd_get_or_create_leafref_links_record(const struct lyd_node_term *node, struct lyd_leafref_links_rec **record, ly_bool create);
641
642/**
steweg67388952024-01-25 12:14:50 +0100643 * @brief Adds links between leafref and data node.
stewegf9041a22024-01-18 13:29:12 +0100644 *
645 * If the links were already added, it will not be added again.
646 * This API requires usage of LY_CTX_LEAFREF_LINKING context flag.
647 *
648 * @param[in] node Data node to which, the leafref is pointing to.
649 * @param[in] leafref_node The leafref, which points to given node.
650 * @return LY_SUCCESS on success.
651 * @return LY_ERR value on error.
652 */
653LY_ERR lyd_link_leafref_node(const struct lyd_node_term *node, const struct lyd_node_term *leafref_node);
654
655/**
steweg67388952024-01-25 12:14:50 +0100656 * @brief Removes links between leafref and data node.
stewegf9041a22024-01-18 13:29:12 +0100657 *
658 * If the links were never added, it will be silently ignored.
659 * This API requires usage of LY_CTX_LEAFREF_LINKING context flag.
660 *
661 * @param[in] node Data node to which, the leafref is pointing to.
662 * @param[in] leafref_node The leafref, which points to given node.
663 * @return LY_SUCCESS on success.
664 * @return LY_ERR value on error.
665 */
666LY_ERR lyd_unlink_leafref_node(const struct lyd_node_term *node, const struct lyd_node_term *leafref_node);
667
Radek Krejcie7b95092019-05-15 11:03:07 +0200668#endif /* LY_TREE_DATA_INTERNAL_H_ */