Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 1 | /** |
| 2 | * @file tree_data.h |
| 3 | * @author Radek Krejci <rkrejci@cesnet.cz> |
| 4 | * @brief libyang representation of YANG data trees. |
| 5 | * |
| 6 | * Copyright (c) 2015 - 2019 CESNET, z.s.p.o. |
| 7 | * |
| 8 | * This source code is licensed under BSD 3-Clause License (the "License"). |
| 9 | * You may not use this file except in compliance with the License. |
| 10 | * You may obtain a copy of the License at |
| 11 | * |
| 12 | * https://opensource.org/licenses/BSD-3-Clause |
| 13 | */ |
| 14 | |
| 15 | #ifndef LY_TREE_DATA_H_ |
| 16 | #define LY_TREE_DATA_H_ |
| 17 | |
| 18 | #include <stddef.h> |
| 19 | #include <stdint.h> |
| 20 | |
| 21 | #include "log.h" |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 22 | |
Radek Krejci | ca376bd | 2020-06-11 16:04:06 +0200 | [diff] [blame] | 23 | #ifdef __cplusplus |
| 24 | extern "C" { |
| 25 | #endif |
| 26 | |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 27 | struct ly_ctx; |
Michal Vasko | 004d315 | 2020-06-11 19:59:22 +0200 | [diff] [blame] | 28 | struct ly_path; |
Radek Krejci | 535ea9f | 2020-05-29 16:01:05 +0200 | [diff] [blame] | 29 | struct ly_set; |
| 30 | struct lyd_node; |
| 31 | struct lyd_node_opaq; |
| 32 | struct lys_module; |
| 33 | struct lysc_node; |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 34 | |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 35 | /** |
| 36 | * @defgroup datatree Data Tree |
Radek Krejci | 2ff0d57 | 2020-05-21 15:27:28 +0200 | [diff] [blame] | 37 | * @ingroup trees |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 38 | * @{ |
| 39 | * |
| 40 | * Data structures and functions to manipulate and access instance data tree. |
| 41 | */ |
| 42 | |
| 43 | /** |
| 44 | * @brief Macro to iterate via all elements in a data tree. This is the opening part |
| 45 | * to the #LYD_TREE_DFS_END - they always have to be used together. |
| 46 | * |
| 47 | * The function follows deep-first search algorithm: |
| 48 | * <pre> |
| 49 | * 1 |
| 50 | * / \ |
Michal Vasko | c193ce9 | 2020-03-06 11:04:48 +0100 | [diff] [blame] | 51 | * 2 4 |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 52 | * / / \ |
Michal Vasko | c193ce9 | 2020-03-06 11:04:48 +0100 | [diff] [blame] | 53 | * 3 5 6 |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 54 | * </pre> |
| 55 | * |
Radek Krejci | 0935f41 | 2019-08-20 16:15:18 +0200 | [diff] [blame] | 56 | * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 57 | * START can be any of the lyd_node* types, NEXT and ELEM variables are expected |
| 58 | * to be pointers to a generic struct lyd_node. |
| 59 | * |
| 60 | * Since the next node is selected as part of #LYD_TREE_DFS_END, do not use |
| 61 | * continue statement between the #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. |
| 62 | * |
| 63 | * Use with opening curly bracket '{' after the macro. |
| 64 | * |
| 65 | * @param START Pointer to the starting element processed first. |
| 66 | * @param NEXT Temporary storage, do not use. |
| 67 | * @param ELEM Iterator intended for use in the block. |
| 68 | */ |
| 69 | #define LYD_TREE_DFS_BEGIN(START, NEXT, ELEM) \ |
| 70 | for ((ELEM) = (NEXT) = (START); \ |
| 71 | (ELEM); \ |
| 72 | (ELEM) = (NEXT)) |
| 73 | |
| 74 | /** |
| 75 | * @brief Macro to iterate via all elements in a tree. This is the closing part |
| 76 | * to the #LYD_TREE_DFS_BEGIN - they always have to be used together. |
| 77 | * |
| 78 | * Use the same parameters for #LYD_TREE_DFS_BEGIN and #LYD_TREE_DFS_END. While |
| 79 | * START can be any of the lyd_node* types, NEXT and ELEM variables are expected |
| 80 | * to be pointers to a generic struct lyd_node. |
| 81 | * |
| 82 | * Use with closing curly bracket '}' after the macro. |
| 83 | * |
| 84 | * @param START Pointer to the starting element processed first. |
| 85 | * @param NEXT Temporary storage, do not use. |
| 86 | * @param ELEM Iterator intended for use in the block. |
| 87 | */ |
| 88 | |
| 89 | #define LYD_TREE_DFS_END(START, NEXT, ELEM) \ |
| 90 | /* select element for the next run - children first */ \ |
Michal Vasko | 5bfd4be | 2020-06-23 13:26:19 +0200 | [diff] [blame] | 91 | (NEXT) = lyd_node_children((struct lyd_node*)ELEM, 0); \ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 92 | if (!(NEXT)) { \ |
| 93 | /* no children */ \ |
| 94 | if ((ELEM) == (struct lyd_node*)(START)) { \ |
| 95 | /* we are done, (START) has no children */ \ |
| 96 | break; \ |
| 97 | } \ |
| 98 | /* try siblings */ \ |
| 99 | (NEXT) = (ELEM)->next; \ |
| 100 | } \ |
| 101 | while (!(NEXT)) { \ |
| 102 | /* parent is already processed, go to its sibling */ \ |
| 103 | (ELEM) = (struct lyd_node*)(ELEM)->parent; \ |
| 104 | /* no siblings, go back through parents */ \ |
| 105 | if ((ELEM)->parent == (START)->parent) { \ |
| 106 | /* we are done, no next element to process */ \ |
| 107 | break; \ |
| 108 | } \ |
| 109 | (NEXT) = (ELEM)->next; \ |
| 110 | } |
| 111 | |
| 112 | /** |
Michal Vasko | 03ff5a7 | 2019-09-11 13:49:33 +0200 | [diff] [blame] | 113 | * @brief Macro to get context from a data tree node. |
| 114 | */ |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 115 | #define LYD_NODE_CTX(node) ((node)->schema ? (node)->schema->module->ctx : ((struct lyd_node_opaq *)(node))->ctx) |
Michal Vasko | 03ff5a7 | 2019-09-11 13:49:33 +0200 | [diff] [blame] | 116 | |
| 117 | /** |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 118 | * @brief Data input/output formats supported by libyang [parser](@ref howtodataparsers) and |
Radek Krejci | d91d4da | 2020-05-18 11:28:02 +0200 | [diff] [blame] | 119 | * [printer](@ref howtodataprinters) functions. Also used for value prefix format (TODO link to prefix formats descriptions). |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 120 | */ |
| 121 | typedef enum { |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 122 | LYD_SCHEMA = 0, /**< invalid instance data format, value prefixes map to YANG import prefixes */ |
| 123 | LYD_XML, /**< XML instance data format, value prefixes map to XML namespace prefixes */ |
| 124 | LYD_JSON, /**< JSON instance data format, value prefixes map to module names */ |
Michal Vasko | 60ea635 | 2020-06-29 13:39:39 +0200 | [diff] [blame] | 125 | LYD_LYB, /**< LYB instance data format, invalid value prefix format (same as LYD_JSON) */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 126 | } LYD_FORMAT; |
| 127 | |
| 128 | /** |
Radek Krejci | 59583bb | 2019-09-11 12:57:55 +0200 | [diff] [blame] | 129 | * @brief List of possible value types stored in ::lyd_node_any. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 130 | */ |
| 131 | typedef enum { |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 132 | LYD_ANYDATA_DATATREE, /**< Value is a pointer to lyd_node structure (first sibling). When provided as input parameter, the pointer |
Radek Krejci | ee4cab2 | 2019-07-17 17:07:47 +0200 | [diff] [blame] | 133 | is directly connected into the anydata node without duplication, caller is supposed to not manipulate |
| 134 | with the data after a successful call (including calling lyd_free() on the provided data) */ |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 135 | LYD_ANYDATA_STRING, /**< Value is a generic string without any knowledge about its format (e.g. anyxml value in JSON encoded |
Radek Krejci | ee4cab2 | 2019-07-17 17:07:47 +0200 | [diff] [blame] | 136 | as string). XML sensitive characters (such as & or \>) are automatically escaped when the anydata |
| 137 | is printed in XML format. */ |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 138 | LYD_ANYDATA_XML, /**< Value is a string containing the serialized XML data. */ |
| 139 | LYD_ANYDATA_JSON, /**< Value is a string containing the data modeled by YANG and encoded as I-JSON. */ |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 140 | LYD_ANYDATA_LYB, /**< Value is a memory chunk with the serialized data tree in LYB format. */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 141 | } LYD_ANYDATA_VALUETYPE; |
| 142 | |
| 143 | /** @} */ |
| 144 | |
| 145 | /** |
| 146 | * @brief YANG data representation |
| 147 | */ |
| 148 | struct lyd_value { |
Radek Krejci | 950f6a5 | 2019-09-12 17:15:32 +0200 | [diff] [blame] | 149 | 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 Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 151 | union { |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 152 | int8_t boolean; /**< 0 as false, 1 as true */ |
| 153 | int64_t dec64; /**< decimal64: value = dec64 / 10^fraction-digits */ |
Radek Krejci | 8dc4f2d | 2019-07-16 12:24:00 +0200 | [diff] [blame] | 154 | 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 Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 162 | struct lysc_type_bitenum_item *enum_item; /**< pointer to the definition of the enumeration value */ |
Radek Krejci | 849a62a | 2019-05-22 15:29:05 +0200 | [diff] [blame] | 163 | struct lysc_type_bitenum_item **bits_items; /**< list of set pointers to the specification of the set bits ([sized array](@ref sizedarrays)) */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 164 | struct lysc_ident *ident; /**< pointer to the schema definition of the identityref value */ |
Radek Krejci | efbb392 | 2019-07-15 12:58:00 +0200 | [diff] [blame] | 165 | |
| 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 Krejci | 8dc4f2d | 2019-07-16 12:24:00 +0200 | [diff] [blame] | 171 | 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 Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 174 | lyd_value:canonical_cache while the lyd_value_subvalue::value contains representation according to the |
Radek Krejci | 8dc4f2d | 2019-07-16 12:24:00 +0200 | [diff] [blame] | 175 | 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 Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 178 | |
Michal Vasko | 004d315 | 2020-06-11 19:59:22 +0200 | [diff] [blame] | 179 | struct ly_path *target; /**< Instance-identifier's target path. */ |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 180 | |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 181 | void *ptr; /**< generic data type structure used to store the data */ |
Radek Krejci | 8dc4f2d | 2019-07-16 12:24:00 +0200 | [diff] [blame] | 182 | }; /**< The union is just a list of shorthands to possible values stored by a type's plugin. libyang itself uses the lyd_value::realtype |
| 183 | plugin's callbacks to work with the data. */ |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 184 | |
Radek Krejci | 950f6a5 | 2019-09-12 17:15:32 +0200 | [diff] [blame] | 185 | 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 Krejci | 62903c3 | 2019-07-15 14:42:05 +0200 | [diff] [blame] | 186 | in the schema node of the data node since the type's store plugin can use other types/plugins for |
| 187 | storing data. Speaking about built-in types, this is the case of leafref which stores data as its |
| 188 | target type. In contrast, union type also use its subtype's callbacks, but inside an internal data |
| 189 | lyd_value::subvalue structure, so here is the pointer to the union type. |
| 190 | In general, this type is used to get free callback for this lyd_value structure, so it must reflect |
| 191 | the type used to store data directly in the same lyd_value instance. */ |
Radek Krejci | 950f6a5 | 2019-09-12 17:15:32 +0200 | [diff] [blame] | 192 | void *canonical_cache; /**< Generic cache for type plugins to store data necessary to print canonical value. It can be the canonical |
| 193 | value itself or anything else useful to print the canonical form of the value. Plugin is responsible for |
| 194 | freeing the cache in its free callback. */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 195 | }; |
| 196 | |
| 197 | /** |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 198 | * @brief Metadata structure. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 199 | * |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 200 | * The structure provides information about metadata of a data element. Such attributes must map to |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 201 | * annotations as specified in RFC 7952. The only exception is the filter type (in NETCONF get operations) |
| 202 | * and edit-config's operation attributes. In XML, they are represented as standard XML attributes. In JSON, |
| 203 | * they are represented as JSON elements starting with the '@' character (for more information, see the |
| 204 | * YANG metadata RFC. |
| 205 | * |
| 206 | */ |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 207 | struct lyd_meta { |
| 208 | struct lyd_node *parent; /**< data node where the metadata is placed */ |
| 209 | struct lyd_meta *next; /**< pointer to the next metadata of the same element */ |
| 210 | struct lysc_ext_instance *annotation; /**< pointer to the annotation's definition */ |
| 211 | const char *name; /**< metadata name */ |
| 212 | struct lyd_value value; /**< metadata value representation */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 213 | }; |
| 214 | |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 215 | /** |
| 216 | * @brief Generic prefix and namespace mapping, meaning depends on the format. |
| 217 | */ |
| 218 | struct ly_prefix { |
| 219 | const char *pref; |
| 220 | const char *ns; |
| 221 | }; |
| 222 | |
| 223 | /** |
| 224 | * @brief Generic attribute structure. |
| 225 | */ |
| 226 | struct ly_attr { |
| 227 | struct lyd_node_opaq *parent; /**< data node where the attribute is placed */ |
| 228 | struct ly_attr *next; |
| 229 | struct ly_prefix *val_prefs; /**< list of prefixes in the value ([sized array](@ref sizedarrays)) */ |
| 230 | const char *name; |
| 231 | const char *value; |
| 232 | |
| 233 | LYD_FORMAT format; |
| 234 | struct ly_prefix prefix; /**< name prefix, it is stored because they are a real pain to generate properly */ |
| 235 | |
| 236 | }; |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 237 | |
Michal Vasko | 1bf0939 | 2020-03-27 12:38:10 +0100 | [diff] [blame] | 238 | #define LYD_NODE_INNER (LYS_CONTAINER|LYS_LIST|LYS_RPC|LYS_ACTION|LYS_NOTIF) /**< Schema nodetype mask for lyd_node_inner */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 239 | #define LYD_NODE_TERM (LYS_LEAF|LYS_LEAFLIST) /**< Schema nodetype mask for lyd_node_term */ |
| 240 | #define LYD_NODE_ANY (LYS_ANYDATA) /**< Schema nodetype mask for lyd_node_any */ |
| 241 | |
| 242 | /** |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 243 | * @defgroup dnodeflags Data node flags |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 244 | * @ingroup datatree |
| 245 | * @{ |
| 246 | * |
| 247 | * Various flags of data nodes. |
| 248 | * |
| 249 | * 1 - container 5 - anydata/anyxml |
| 250 | * 2 - list 6 - rpc/action |
| 251 | * 3 - leaf 7 - notification |
| 252 | * 4 - leaflist |
| 253 | * |
| 254 | * bit name 1 2 3 4 5 6 7 |
| 255 | * ---------------------+-+-+-+-+-+-+-+ |
| 256 | * 1 LYD_DEFAULT |x| |x|x| | | | |
| 257 | * +-+-+-+-+-+-+-+ |
Michal Vasko | 5c4e589 | 2019-11-14 12:31:38 +0100 | [diff] [blame] | 258 | * 2 LYD_WHEN_TRUE |x|x|x|x|x| | | |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 259 | * +-+-+-+-+-+-+-+ |
| 260 | * 3 LYD_NEW |x|x|x|x|x|x|x| |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 261 | * ---------------------+-+-+-+-+-+-+-+ |
| 262 | * |
| 263 | */ |
| 264 | |
Michal Vasko | 5c4e589 | 2019-11-14 12:31:38 +0100 | [diff] [blame] | 265 | #define LYD_DEFAULT 0x01 /**< default (implicit) node */ |
| 266 | #define LYD_WHEN_TRUE 0x02 /**< all when conditions of this node were evaluated to true */ |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 267 | #define LYD_NEW 0x04 /**< node was created after the last validation, is needed for the next validation */ |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 268 | |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 269 | /** @} */ |
| 270 | |
| 271 | /** |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 272 | * @brief Callback provided by the data/schema parsers to type plugins to resolve (format-specific) mapping between prefixes used |
| 273 | * in the value strings to the YANG schemas. |
| 274 | * |
| 275 | * Reverse function to ly_clb_get_prefix. |
| 276 | * |
| 277 | * XML uses XML namespaces, JSON uses schema names as prefixes, YIN/YANG uses prefixes of the imports. |
| 278 | * |
| 279 | * @param[in] ctx libyang context to find the schema. |
| 280 | * @param[in] prefix Prefix found in the value string |
| 281 | * @param[in] prefix_len Length of the @p prefix. |
| 282 | * @param[in] private Internal data needed by the callback. |
| 283 | * @return Pointer to the YANG schema identified by the provided prefix or NULL if no mapping found. |
| 284 | */ |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 285 | typedef const struct lys_module *(*ly_clb_resolve_prefix)(const struct ly_ctx *ctx, const char *prefix, size_t prefix_len, |
| 286 | void *private); |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 287 | |
| 288 | /** |
| 289 | * @brief Callback provided by the data/schema printers to type plugins to resolve (format-specific) mapping between YANG module of a data object |
| 290 | * to prefixes used in the value strings. |
| 291 | * |
| 292 | * Reverse function to ly_clb_resolve_prefix. |
| 293 | * |
| 294 | * XML uses XML namespaces, JSON uses schema names as prefixes, YIN/YANG uses prefixes of the imports. |
| 295 | * |
| 296 | * @param[in] mod YANG module of the object. |
| 297 | * @param[in] private Internal data needed by the callback. |
| 298 | * @return String representing prefix for the object of the given YANG module @p mod. |
| 299 | */ |
| 300 | typedef const char *(*ly_clb_get_prefix)(const struct lys_module *mod, void *private); |
| 301 | |
| 302 | /** |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 303 | * @brief Generic structure for a data node. |
| 304 | */ |
| 305 | struct lyd_node { |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 306 | uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or |
| 307 | hashes of all nodes of subtree in case of keyless list). Note that while hash can be |
| 308 | used to get know that nodes are not equal, it cannot be used to decide that the |
| 309 | nodes are equal due to possible collisions. */ |
| 310 | uint32_t flags; /**< [data node flags](@ref dnodeflags) */ |
Michal Vasko | ecd62de | 2019-11-13 12:35:11 +0100 | [diff] [blame] | 311 | const struct lysc_node *schema; /**< pointer to the schema definition of this node, note that the target can be not just |
| 312 | ::struct lysc_node but ::struct lysc_action or ::struct lysc_notif as well */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 313 | struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */ |
| 314 | struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */ |
| 315 | struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is |
| 316 | never NULL. If there is no sibling node, pointer points to the node |
| 317 | itself. In case of the first node, this pointer points to the last |
| 318 | node in the list. */ |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 319 | struct lyd_meta *meta; /**< pointer to the list of metadata of this node */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 320 | |
| 321 | #ifdef LY_ENABLED_LYD_PRIV |
| 322 | void *priv; /**< private user data, not used by libyang */ |
| 323 | #endif |
| 324 | }; |
| 325 | |
| 326 | /** |
Radek Krejci | f3b6fec | 2019-07-24 15:53:11 +0200 | [diff] [blame] | 327 | * @brief Data node structure for the inner data tree nodes - containers, lists, RPCs, actions and Notifications. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 328 | */ |
| 329 | struct lyd_node_inner { |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 330 | uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or |
| 331 | hashes of all nodes of subtree in case of keyless list). Note that while hash can be |
| 332 | used to get know that nodes are not equal, it cannot be used to decide that the |
| 333 | nodes are equal due to possible collisions. */ |
| 334 | uint32_t flags; /**< [data node flags](@ref dnodeflags) */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 335 | const struct lysc_node *schema; /**< pointer to the schema definition of this node */ |
| 336 | struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */ |
| 337 | struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */ |
| 338 | struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is |
| 339 | never NULL. If there is no sibling node, pointer points to the node |
| 340 | itself. In case of the first node, this pointer points to the last |
| 341 | node in the list. */ |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 342 | struct lyd_meta *meta; /**< pointer to the list of metadata of this node */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 343 | |
| 344 | #ifdef LY_ENABLED_LYD_PRIV |
| 345 | void *priv; /**< private user data, not used by libyang */ |
| 346 | #endif |
| 347 | |
| 348 | struct lyd_node *child; /**< pointer to the first child node. */ |
| 349 | struct hash_table *children_ht; /**< hash table with all the direct children (except keys for a list, lists without keys) */ |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 350 | #define LYD_HT_MIN_ITEMS 4 /**< minimal number of children to create lyd_node_inner::children_ht hash table. */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 351 | }; |
| 352 | |
| 353 | /** |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 354 | * @brief Data node structure for the terminal data tree nodes - leaves and leaf-lists. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 355 | */ |
| 356 | struct lyd_node_term { |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 357 | uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or |
| 358 | hashes of all nodes of subtree in case of keyless list). Note that while hash can be |
| 359 | used to get know that nodes are not equal, it cannot be used to decide that the |
| 360 | nodes are equal due to possible collisions. */ |
| 361 | uint32_t flags; /**< [data node flags](@ref dnodeflags) */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 362 | const struct lysc_node *schema; /**< pointer to the schema definition of this node */ |
| 363 | struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */ |
| 364 | struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */ |
| 365 | struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is |
| 366 | never NULL. If there is no sibling node, pointer points to the node |
| 367 | itself. In case of the first node, this pointer points to the last |
| 368 | node in the list. */ |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 369 | struct lyd_meta *meta; /**< pointer to the list of metadata of this node */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 370 | |
| 371 | #ifdef LY_ENABLED_LYD_PRIV |
| 372 | void *priv; /**< private user data, not used by libyang */ |
| 373 | #endif |
| 374 | |
| 375 | struct lyd_value value; /**< node's value representation */ |
| 376 | }; |
| 377 | |
| 378 | /** |
| 379 | * @brief Data node structure for the anydata data tree nodes - anydatas and anyxmls. |
| 380 | */ |
| 381 | struct lyd_node_any { |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 382 | uint32_t hash; /**< hash of this particular node (module name + schema name + key string values if list or |
| 383 | hashes of all nodes of subtree in case of keyless list). Note that while hash can be |
| 384 | used to get know that nodes are not equal, it cannot be used to decide that the |
| 385 | nodes are equal due to possible collisions. */ |
| 386 | uint32_t flags; /**< [data node flags](@ref dnodeflags) */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 387 | const struct lysc_node *schema; /**< pointer to the schema definition of this node */ |
| 388 | struct lyd_node_inner *parent; /**< pointer to the parent node, NULL in case of root node */ |
| 389 | struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */ |
| 390 | struct lyd_node *prev; /**< pointer to the previous sibling node \note Note that this pointer is |
| 391 | never NULL. If there is no sibling node, pointer points to the node |
| 392 | itself. In case of the first node, this pointer points to the last |
| 393 | node in the list. */ |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 394 | struct lyd_meta *meta; /**< pointer to the list of attributes of this node */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 395 | |
| 396 | #ifdef LY_ENABLED_LYD_PRIV |
| 397 | void *priv; /**< private user data, not used by libyang */ |
| 398 | #endif |
| 399 | |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 400 | union lyd_any_value { |
Radek Krejci | ee4cab2 | 2019-07-17 17:07:47 +0200 | [diff] [blame] | 401 | struct lyd_node *tree; /**< data tree */ |
| 402 | const char *str; /**< Generic string data */ |
| 403 | const char *xml; /**< Serialized XML data */ |
| 404 | const char *json; /**< I-JSON encoded string */ |
| 405 | char *mem; /**< LYD_ANYDATA_LYB memory chunk */ |
| 406 | } value; /**< pointer to the stored value representation of the anydata/anyxml node */ |
| 407 | LYD_ANYDATA_VALUETYPE value_type;/**< type of the data stored as lyd_node_any::value */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 408 | }; |
| 409 | |
| 410 | /** |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 411 | * @brief Data node structure for unparsed (opaque) nodes. |
| 412 | */ |
| 413 | struct lyd_node_opaq { |
| 414 | uint32_t hash; /**< always 0 */ |
| 415 | uint32_t flags; /**< always 0 */ |
| 416 | const struct lysc_node *schema; /**< always NULL */ |
| 417 | struct lyd_node *parent; /**< pointer to the parent node (NULL in case of root node) */ |
| 418 | struct lyd_node *next; /**< pointer to the next sibling node (NULL if there is no one) */ |
| 419 | struct lyd_node *prev; /**< pointer to the previous sibling node (last sibling if there is none) */ |
| 420 | struct ly_attr *attr; |
| 421 | |
| 422 | #ifdef LY_ENABLED_LYD_PRIV |
| 423 | void *priv; /**< private user data, not used by libyang */ |
| 424 | #endif |
| 425 | |
| 426 | struct lyd_node *child; /**< pointer to the child node (NULL if there are none) */ |
| 427 | const char *name; |
| 428 | LYD_FORMAT format; |
| 429 | struct ly_prefix prefix; /**< name prefix */ |
| 430 | struct ly_prefix *val_prefs; /**< list of prefixes in the value ([sized array](@ref sizedarrays)) */ |
| 431 | const char *value; /**< original value */ |
| 432 | const struct ly_ctx *ctx; /**< libyang context */ |
| 433 | }; |
| 434 | |
| 435 | /** |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 436 | * @defgroup dataparseroptions Data parser options |
| 437 | * @ingroup datatree |
| 438 | * |
| 439 | * Various options to change the data tree parsers behavior. |
| 440 | * |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 441 | * Default parser behavior: |
Michal Vasko | e75ecfd | 2020-03-06 14:12:28 +0100 | [diff] [blame] | 442 | * - complete input file is always parsed. In case of XML, even not well-formed XML document (multiple top-level |
| 443 | * elements) is parsed in its entirety, |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 444 | * - parser silently ignores data without matching schema node definition, |
| 445 | * - list instances are checked whether they have all the keys, error is raised if not. |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 446 | * |
| 447 | * Default parser validation behavior: |
| 448 | * - the provided data are expected to provide complete datastore content (both the configuration and state data) |
| 449 | * and performs data validation according to all YANG rules, specifics follow, |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 450 | * - list instances are expected to have all the keys (it is not checked), |
Michal Vasko | e75ecfd | 2020-03-06 14:12:28 +0100 | [diff] [blame] | 451 | * - instantiated (status) obsolete data print a warning, |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 452 | * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have |
| 453 | * all the keys, leaf(-lists) correct values), |
| 454 | * - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised, |
Michal Vasko | c193ce9 | 2020-03-06 11:04:48 +0100 | [diff] [blame] | 455 | * - if-feature statements are evaluated, |
| 456 | * - invalid multiple data instances/data from several cases cause a validation error, |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 457 | * - default values are added. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 458 | * @{ |
| 459 | */ |
| 460 | |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 461 | #define LYD_OPT_PARSE_ONLY 0x0001 /**< Data will be only parsed and no validation will be performed. When statements |
| 462 | are kept unevaluated, union types may not be fully resolved, if-feature |
| 463 | statements are not checked, and default values are not added (only the ones |
| 464 | parsed are present). */ |
| 465 | #define LYD_OPT_TRUSTED 0x0002 /**< Data are considered trusted so they will be parsed as validated. If the parsed |
| 466 | data are not valid, using this flag may lead to some unexpected behavior! |
| 467 | This flag can be used only with #LYD_OPT_PARSE_ONLY. */ |
| 468 | #define LYD_OPT_STRICT 0x0004 /**< Instead of silently ignoring data without schema definition raise an error. |
| 469 | Do not combine with #LYD_OPT_OPAQ. */ |
| 470 | #define LYD_OPT_OPAQ 0x0008 /**< Instead of silently ignoring data without definition, parse them into |
| 471 | an opaq node. Do not combine with #LYD_OPT_STRICT. */ |
| 472 | #define LYD_OPT_NO_STATE 0x0010 /**< Forbid state data in the parsed data. */ |
Michal Vasko | 60ea635 | 2020-06-29 13:39:39 +0200 | [diff] [blame] | 473 | #define LYD_OPT_LYB_MOD_UPDATE 0x0020 /**< Only for LYB format, allow parsing data printed using a specific module |
| 474 | revision to be loaded even with a module with the same name but newer |
| 475 | revision. */ |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 476 | |
| 477 | #define LYD_OPT_MASK 0xFFFF /**< Mask for all the parser options. */ |
Michal Vasko | 5b37a35 | 2020-03-06 13:38:33 +0100 | [diff] [blame] | 478 | |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 479 | /** @} dataparseroptions */ |
| 480 | |
| 481 | /** |
| 482 | * @defgroup datavalidationoptions Data validation options |
| 483 | * @ingroup datatree |
| 484 | * |
| 485 | * Various options to change data validation behaviour, both for the parser and separate validation. |
| 486 | * |
| 487 | * Default separate validation behavior: |
| 488 | * - the provided data are expected to provide complete datastore content (both the configuration and state data) |
| 489 | * and performs data validation according to all YANG rules, specifics follow, |
Michal Vasko | e75ecfd | 2020-03-06 14:12:28 +0100 | [diff] [blame] | 490 | * - instantiated (status) obsolete data print a warning, |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 491 | * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have |
| 492 | * all the keys, leaf(-lists) correct values), |
| 493 | * - when statements on existing nodes are evaluated. Depending on the previous when state (from previous validation |
| 494 | * or parsing), the node is silently auto-deleted if the state changed from true to false, otherwise a validation error |
| 495 | * is raised if it evaluates to false, |
Michal Vasko | c193ce9 | 2020-03-06 11:04:48 +0100 | [diff] [blame] | 496 | * - if-feature statements are evaluated, |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 497 | * - data from several cases behave based on their previous state (from previous validation or parsing). If there existed |
| 498 | * already a case and another one was added, the previous one is silently auto-deleted. Otherwise (if data from 2 or |
| 499 | * more cases were created) a validation error is raised, |
| 500 | * - default values are added. |
| 501 | * |
| 502 | * @{ |
| 503 | */ |
| 504 | |
| 505 | #define LYD_VALOPT_NO_STATE 0x00010000 /**< Consider state data not allowed and raise an error if they are found. */ |
| 506 | #define LYD_VALOPT_DATA_ONLY 0x00020000 /**< Validate only modules whose data actually exist. */ |
Michal Vasko | cb7526d | 2020-03-30 15:08:26 +0200 | [diff] [blame] | 507 | #define LYD_VALOPT_INPUT 0x00040000 /**< Validate RPC/action request (input parameters). */ |
| 508 | #define LYD_VALOPT_OUTPUT 0x00080000 /**< Validate RPC/action reply (output parameters). */ |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 509 | |
Michal Vasko | 5b37a35 | 2020-03-06 13:38:33 +0100 | [diff] [blame] | 510 | #define LYD_VALOPT_MASK 0xFFFF0000 /**< Mask for all the validation options. */ |
| 511 | |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 512 | /** @} datavalidationoptions */ |
| 513 | |
Michal Vasko | a388136 | 2020-01-21 15:57:35 +0100 | [diff] [blame] | 514 | //#define LYD_OPT_VAL_DIFF 0x40000 /**< Flag only for validation, store all the data node changes performed by the validation |
| 515 | // in a diff structure. */ |
| 516 | //#define LYD_OPT_DATA_TEMPLATE 0x1000000 /**< Data represents YANG data template. */ |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 517 | |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 518 | /** |
Michal Vasko | 5bfd4be | 2020-06-23 13:26:19 +0200 | [diff] [blame] | 519 | * @defgroup children_options Children traversal options. |
| 520 | * @ingroup datatree |
| 521 | */ |
| 522 | |
| 523 | #define LYD_CHILDREN_SKIP_KEYS 0x01 /**< If list children are returned, skip its keys. */ |
| 524 | |
| 525 | /** @} children_options */ |
| 526 | |
| 527 | /** |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 528 | * @brief Get the node's children list if any. |
| 529 | * |
| 530 | * Decides the node's type and in case it has a children list, returns it. |
| 531 | * @param[in] node Node to check. |
Michal Vasko | 5bfd4be | 2020-06-23 13:26:19 +0200 | [diff] [blame] | 532 | * @param[in] options Bitmask of options, see @ref |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 533 | * @return Pointer to the first child node (if any) of the \p node. |
| 534 | */ |
Michal Vasko | 5bfd4be | 2020-06-23 13:26:19 +0200 | [diff] [blame] | 535 | struct lyd_node *lyd_node_children(const struct lyd_node *node, int options); |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 536 | |
| 537 | /** |
Michal Vasko | c193ce9 | 2020-03-06 11:04:48 +0100 | [diff] [blame] | 538 | * @brief Get the owner module of the data node. It is the module of the top-level schema node. Generally, |
| 539 | * in case of augments it is the target module, recursively, otherwise it is the module where the data node is defined. |
| 540 | * |
| 541 | * @param[in] node Data node to examine. |
| 542 | * @return Module owner of the node. |
| 543 | */ |
| 544 | const struct lys_module *lyd_owner_module(const struct lyd_node *node); |
| 545 | |
| 546 | /** |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 547 | * @brief Parse (and validate) data from memory. |
| 548 | * |
| 549 | * In case of LY_XML format, the data string is parsed completely. It means that when it contains |
| 550 | * a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The |
| 551 | * returned data node is a root of the first tree with other trees connected via the next pointer. |
| 552 | * This behavior can be changed by #LYD_OPT_NOSIBLINGS option. |
| 553 | * |
| 554 | * @param[in] ctx Context to connect with the data tree being built here. |
| 555 | * @param[in] data Serialized data in the specified format. |
| 556 | * @param[in] format Format of the input data to be parsed. |
Michal Vasko | 5b37a35 | 2020-03-06 13:38:33 +0100 | [diff] [blame] | 557 | * @param[in] options Parser and validation options, see @ref parseroptions. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 558 | * @return Pointer to the built data tree or NULL in case of empty \p data. To free the returned structure, |
Radek Krejci | f3b6fec | 2019-07-24 15:53:11 +0200 | [diff] [blame] | 559 | * use lyd_free_all(). |
| 560 | * @return NULL in case of error. The error information can be then obtained using ly_err* functions. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 561 | */ |
Michal Vasko | a388136 | 2020-01-21 15:57:35 +0100 | [diff] [blame] | 562 | struct lyd_node *lyd_parse_mem(struct ly_ctx *ctx, const char *data, LYD_FORMAT format, int options); |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 563 | |
| 564 | /** |
| 565 | * @brief Read (and validate) data from the given file descriptor. |
| 566 | * |
| 567 | * \note Current implementation supports only reading data from standard (disk) file, not from sockets, pipes, etc. |
| 568 | * |
| 569 | * In case of LY_XML format, the file content is parsed completely. It means that when it contains |
| 570 | * a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The |
| 571 | * returned data node is a root of the first tree with other trees connected via the next pointer. |
| 572 | * This behavior can be changed by #LYD_OPT_NOSIBLINGS option. |
| 573 | * |
| 574 | * @param[in] ctx Context to connect with the data tree being built here. |
| 575 | * @param[in] fd The standard file descriptor of the file containing the data tree in the specified format. |
| 576 | * @param[in] format Format of the input data to be parsed. |
Michal Vasko | a388136 | 2020-01-21 15:57:35 +0100 | [diff] [blame] | 577 | * @param[in] options Parser options, see @ref parseroptions. \p format LYD_LYB uses #LYD_OPT_PARSE_ONLY implicitly. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 578 | * @return Pointer to the built data tree or NULL in case of empty file. To free the returned structure, |
Radek Krejci | f3b6fec | 2019-07-24 15:53:11 +0200 | [diff] [blame] | 579 | * use lyd_free_all(). |
| 580 | * @return NULL in case of error. The error information can be then obtained using ly_err* functions. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 581 | */ |
Michal Vasko | a388136 | 2020-01-21 15:57:35 +0100 | [diff] [blame] | 582 | struct lyd_node *lyd_parse_fd(struct ly_ctx *ctx, int fd, LYD_FORMAT format, int options); |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 583 | |
| 584 | /** |
| 585 | * @brief Read (and validate) data from the given file path. |
| 586 | * |
| 587 | * In case of LY_XML format, the file content is parsed completely. It means that when it contains |
| 588 | * a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The |
| 589 | * returned data node is a root of the first tree with other trees connected via the next pointer. |
| 590 | * This behavior can be changed by #LYD_OPT_NOSIBLINGS option. |
| 591 | * |
| 592 | * @param[in] ctx Context to connect with the data tree being built here. |
| 593 | * @param[in] path Path to the file containing the data tree in the specified format. |
| 594 | * @param[in] format Format of the input data to be parsed. |
Michal Vasko | a388136 | 2020-01-21 15:57:35 +0100 | [diff] [blame] | 595 | * @param[in] options Parser options, see @ref parseroptions. \p format LYD_LYB uses #LYD_OPT_PARSE_ONLY implicitly. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 596 | * @return Pointer to the built data tree or NULL in case of empty file. To free the returned structure, |
Radek Krejci | f3b6fec | 2019-07-24 15:53:11 +0200 | [diff] [blame] | 597 | * use lyd_free_all(). |
| 598 | * @return NULL in case of error. The error information can be then obtained using ly_err* functions. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 599 | */ |
Michal Vasko | a388136 | 2020-01-21 15:57:35 +0100 | [diff] [blame] | 600 | struct lyd_node *lyd_parse_path(struct ly_ctx *ctx, const char *path, LYD_FORMAT format, int options); |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 601 | |
| 602 | /** |
Michal Vasko | 60ea635 | 2020-06-29 13:39:39 +0200 | [diff] [blame] | 603 | * @brief Learn the length of LYB data. |
| 604 | * |
| 605 | * @param[in] data LYB data to examine. |
| 606 | * @return Length of the LYB data chunk, |
| 607 | * @return -1 on error. |
| 608 | */ |
| 609 | int lyd_lyb_data_length(const char *data); |
| 610 | |
| 611 | /** |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 612 | * @brief Fully validate a data tree. |
| 613 | * |
Michal Vasko | b1b5c26 | 2020-03-05 14:29:47 +0100 | [diff] [blame] | 614 | * @param[in,out] tree Data tree to recursively validate. May be changed by validation. |
| 615 | * @param[in] ctx libyang context. Can be NULL if @p tree is set. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 616 | * @param[in] val_opts Validation options (@ref datavalidationoptions). |
| 617 | * @return LY_SUCCESS on success. |
| 618 | * @return LY_ERR error on error. |
| 619 | */ |
Michal Vasko | b1b5c26 | 2020-03-05 14:29:47 +0100 | [diff] [blame] | 620 | LY_ERR lyd_validate(struct lyd_node **tree, const struct ly_ctx *ctx, int val_opts); |
| 621 | |
| 622 | /** |
| 623 | * @brief Fully validate a data tree. |
| 624 | * |
| 625 | * @param[in,out] tree Data tree to recursively validate. May be changed by validation. |
| 626 | * @param[in] modules Array of modules to validate. |
| 627 | * @param[in] mod_count Number of @p modules. |
| 628 | * @param[in] val_opts Validation options (@ref datavalidationoptions). |
| 629 | * @return LY_SUCCESS on success. |
| 630 | * @return LY_ERR error on error. |
| 631 | */ |
| 632 | LY_ERR lyd_validate_modules(struct lyd_node **tree, const struct lys_module **modules, int mod_count, int val_opts); |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 633 | |
| 634 | /** |
Michal Vasko | cb7526d | 2020-03-30 15:08:26 +0200 | [diff] [blame] | 635 | * @brief Validate an RPC/action, notification, or RPC/action reply. |
Michal Vasko | fea12c6 | 2020-03-30 11:00:15 +0200 | [diff] [blame] | 636 | * |
Michal Vasko | cb7526d | 2020-03-30 15:08:26 +0200 | [diff] [blame] | 637 | * @param[in,out] op_tree Operation tree with any parents. It can point to the operation itself or any of |
| 638 | * its parents, only the operation subtree is actually validated. |
| 639 | * @param[in] tree Tree to be used for validating references from the operation subtree. |
| 640 | * @param[in] val_opts Specific validation option (@ref datavalidationoptions): |
| 641 | * 0 - no validation option for validation notifications, |
| 642 | * ::LYD_VALOPT_INPUT - for validating RPC/action request (input), |
| 643 | * ::LYD_VALOPT_OUTPUT - for validatin RPC/action reply (output). |
Michal Vasko | fea12c6 | 2020-03-30 11:00:15 +0200 | [diff] [blame] | 644 | * @return LY_SUCCESS on success. |
| 645 | * @return LY_ERR error on error. |
| 646 | */ |
Michal Vasko | cb7526d | 2020-03-30 15:08:26 +0200 | [diff] [blame] | 647 | LY_ERR lyd_validate_op(struct lyd_node *op_tree, const struct lyd_node *tree, int val_opts); |
Michal Vasko | fea12c6 | 2020-03-30 11:00:15 +0200 | [diff] [blame] | 648 | |
| 649 | /** |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 650 | * @brief Create a new inner node in the data tree. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 651 | * |
| 652 | * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 653 | * @param[in] module Module of the node being created. If NULL, @p parent module will be used. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 654 | * @param[in] name Schema node name of the new data node. The node can be #LYS_CONTAINER, #LYS_NOTIF, #LYS_RPC, or #LYS_ACTION. |
| 655 | * @return New created node. |
| 656 | * @return NULL on error. |
| 657 | */ |
| 658 | struct lyd_node *lyd_new_inner(struct lyd_node *parent, const struct lys_module *module, const char *name); |
| 659 | |
| 660 | /** |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 661 | * @brief Create a new list node in the data tree. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 662 | * |
| 663 | * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 664 | * @param[in] module Module of the node being created. If NULL, @p parent module will be used. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 665 | * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST. |
| 666 | * @param[in] ... Ordered key values of the new list instance, all must be set. In case of an instance-identifier |
Michal Vasko | 004d315 | 2020-06-11 19:59:22 +0200 | [diff] [blame] | 667 | * or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for |
| 668 | * key-less lists. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 669 | * @return New created node. |
| 670 | * @return NULL on error. |
| 671 | */ |
| 672 | struct lyd_node *lyd_new_list(struct lyd_node *parent, const struct lys_module *module, const char *name, ...); |
| 673 | |
| 674 | /** |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 675 | * @brief Create a new list node in the data tree. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 676 | * |
| 677 | * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 678 | * @param[in] module Module of the node being created. If NULL, @p parent module will be used. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 679 | * @param[in] name Schema node name of the new data node. The node must be #LYS_LIST. |
| 680 | * @param[in] keys All key values predicate in the form of "[key1='val1'][key2='val2']...", they do not have to be ordered. |
| 681 | * In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes). |
Michal Vasko | 004d315 | 2020-06-11 19:59:22 +0200 | [diff] [blame] | 682 | * Use NULL or string of length 0 in case of key-less list. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 683 | * @return New created node. |
| 684 | * @return NULL on error. |
| 685 | */ |
| 686 | struct lyd_node *lyd_new_list2(struct lyd_node *parent, const struct lys_module *module, const char *name, const char *keys); |
| 687 | |
| 688 | /** |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 689 | * @brief Create a new term node in the data tree. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 690 | * |
| 691 | * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 692 | * @param[in] module Module of the node being created. If NULL, @p parent module will be used. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 693 | * @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST. |
| 694 | * @param[in] val_str String form of the value of the node being created. In case of an instance-identifier or identityref |
| 695 | * value, the JSON format is expected (module names instead of prefixes). |
| 696 | * @return New created node. |
| 697 | * @return NULL on error. |
| 698 | */ |
| 699 | struct lyd_node *lyd_new_term(struct lyd_node *parent, const struct lys_module *module, const char *name, const char *val_str); |
| 700 | |
| 701 | /** |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 702 | * @brief Create a new any node in the data tree. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 703 | * |
| 704 | * @param[in] parent Parent node for the node being created. NULL in case of creating a top level element. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 705 | * @param[in] module Module of the node being created. If NULL, @p parent module will be used. |
Michal Vasko | 013a818 | 2020-03-03 10:46:53 +0100 | [diff] [blame] | 706 | * @param[in] name Schema node name of the new data node. The node can be #LYS_ANYDATA or #LYS_ANYXML. |
| 707 | * @param[in] value Value to be directly assigned to the node. Expected type is determined by @p value_type. |
| 708 | * @param[in] value_type Type of the provided value in @p value. |
| 709 | * @return New created node. |
| 710 | * @return NULL on error. |
| 711 | */ |
| 712 | struct lyd_node *lyd_new_any(struct lyd_node *parent, const struct lys_module *module, const char *name, |
| 713 | const void *value, LYD_ANYDATA_VALUETYPE value_type); |
| 714 | |
| 715 | /** |
Michal Vasko | d86997b | 2020-05-26 15:19:54 +0200 | [diff] [blame] | 716 | * @brief Create new metadata for a data node. |
| 717 | * |
| 718 | * @param[in] parent Parent node for the metadata being created. |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 719 | * @param[in] module Module of the metadata being created. If NULL, @p name must include module name as the prefix. |
Michal Vasko | d86997b | 2020-05-26 15:19:54 +0200 | [diff] [blame] | 720 | * @param[in] name Annotation name of the new metadata. It can include the annotation module as the prefix. |
| 721 | * If the prefix is specified it is always used but if not specified, @p module must be set. |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 722 | * @param[in] val_str String form of the value of the metadata. In case of an instance-identifier or identityref |
Michal Vasko | d86997b | 2020-05-26 15:19:54 +0200 | [diff] [blame] | 723 | * value, the JSON format is expected (module names instead of prefixes). |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 724 | * @return New created metadata of @p parent. |
Michal Vasko | d86997b | 2020-05-26 15:19:54 +0200 | [diff] [blame] | 725 | * @return NULL on error. |
| 726 | */ |
| 727 | struct lyd_meta *lyd_new_meta(struct lyd_node *parent, const struct lys_module *module, const char *name, |
| 728 | const char *val_str); |
| 729 | |
| 730 | /** |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 731 | * @brief Create a new opaque node in the data tree. |
| 732 | * |
| 733 | * @param[in] parent Parent node for the node beaing created. NULL in case of creating a top level element. |
| 734 | * @param[in] ctx libyang context. If NULL, @p parent context will be used. |
| 735 | * @param[in] name Node name. |
| 736 | * @param[in] value Node value, may be NULL. |
| 737 | * @param[in] module_name Node module name. |
| 738 | * @return New created node. |
| 739 | * @return NULL on error. |
| 740 | */ |
| 741 | struct lyd_node *lyd_new_opaq(struct lyd_node *parent, const struct ly_ctx *ctx, const char *name, const char *value, |
| 742 | const char *module_name); |
| 743 | |
| 744 | /** |
| 745 | * @brief Create new attribute for an opaque data node. |
| 746 | * |
| 747 | * @param[in] parent Parent opaque node for the attribute being created. |
| 748 | * @param[in] module Module name of the attribute being created. There may be none. |
| 749 | * @param[in] name Attribute name. It can include the module name as the prefix. |
| 750 | * @param[in] val_str String value of the attribute. Is stored directly. |
| 751 | * @return New created attribute of @p parent. |
| 752 | * @return NULL on error. |
| 753 | */ |
| 754 | struct ly_attr *lyd_new_attr(struct lyd_node *parent, const char *module_name, const char *name, const char *val_str); |
| 755 | |
| 756 | /** |
| 757 | * @defgroup pathoptions Data path creation options |
| 758 | * @ingroup datatree |
| 759 | * |
| 760 | * Various options to change lyd_new_path*() behavior. |
| 761 | * |
| 762 | * Default behavior: |
| 763 | * - if the target node already exists (and is not default), an error is returned. |
| 764 | * - the whole path to the target node is created (with any missing parents) if necessary. |
| 765 | * - RPC output schema children are completely ignored in all modules. Input is searched and nodes created normally. |
| 766 | * @{ |
| 767 | */ |
| 768 | |
| 769 | #define LYD_NEWOPT_UPDATE 0x01 /**< If the target node exists, is a leaf, and it is updated with a new value or its |
| 770 | default flag is changed, it is returned. If the target node exists and is not |
| 771 | a leaf or generally no change occurs in the @p parent tree, NULL is returned and |
| 772 | no error set. */ |
| 773 | #define LYD_NEWOPT_OUTPUT 0x02 /**< Changes the behavior to ignoring RPC/action input schema nodes and using only |
| 774 | output ones. */ |
| 775 | #define LYD_NEWOPT_OPAQ 0x04 /**< Enables the creation of opaque nodes with some specific rules. If the __last node__ |
| 776 | in the path is not uniquely defined ((leaf-)list without a predicate) or has an |
| 777 | invalid value (leaf/leaf-list), it is created as opaque. */ |
| 778 | |
| 779 | /** @} pathoptions */ |
| 780 | |
| 781 | /** |
| 782 | * @brief Create a new node in the data tree based on a path. Cannot be used for anyxml/anydata nodes, |
| 783 | * for those use ::lyd_new_path_any. |
| 784 | * |
| 785 | * If @p path points to a list key and the list instance does not exist, the key value from the predicate is used |
| 786 | * and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path |
| 787 | * and @p value is set, the predicate is preferred. |
| 788 | * |
| 789 | * @param[in] parent Data parent to add to/modify, can be NULL. |
| 790 | * @param[in] ctx libyang context, must be set if @p parent is NULL. |
| 791 | * @param[in] path Path to create (TODO ref path). |
| 792 | * @param[in] value Value of the new leaf/leaf-list. For other node types, it is ignored. |
| 793 | * @param[in] options Bitmask of options, see @ref pathoptions. |
Michal Vasko | a8f9eb3 | 2020-06-16 13:07:12 +0200 | [diff] [blame] | 794 | * @return First created node. |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 795 | * @return NULL on error. |
| 796 | */ |
| 797 | struct lyd_node *lyd_new_path(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const char *value, |
| 798 | int options); |
| 799 | |
| 800 | /** |
| 801 | * @brief Create a new node in the data tree based on a path. All node types can be created. |
| 802 | * |
| 803 | * If @p path points to a list key and the list instance does not exist, the key value from the predicate is used |
| 804 | * and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path |
| 805 | * and @p value is set, the predicate is preferred. |
| 806 | * |
| 807 | * @param[in] parent Data parent to add to/modify, can be NULL. |
| 808 | * @param[in] ctx libyang context, must be set if @p parent is NULL. |
| 809 | * @param[in] path Path to create (TODO ref path). |
| 810 | * @param[in] value Value of the new leaf/leaf-list/anyxml/anydata. For other node types, it is ignored. |
| 811 | * @param[in] value_type Anyxml/anydata node @p value type. |
| 812 | * @param[in] options Bitmask of options, see @ref pathoptions. |
Michal Vasko | a8f9eb3 | 2020-06-16 13:07:12 +0200 | [diff] [blame] | 813 | * @return First created node. |
Michal Vasko | 00cbf53 | 2020-06-15 13:58:47 +0200 | [diff] [blame] | 814 | * @return NULL on error. |
| 815 | */ |
| 816 | struct lyd_node *lyd_new_path_any(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const void *value, |
| 817 | LYD_ANYDATA_VALUETYPE value_type, int options); |
| 818 | |
| 819 | /** |
| 820 | * @brief Create a new node in the data tree based on a path. All node types can be created. |
| 821 | * |
| 822 | * If @p path points to a list key and the list instance does not exist, the key value from the predicate is used |
| 823 | * and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path |
| 824 | * and @p value is set, the predicate is preferred. |
| 825 | * |
| 826 | * @param[in] parent Data parent to add to/modify, can be NULL. |
| 827 | * @param[in] ctx libyang context, must be set if @p parent is NULL. |
| 828 | * @param[in] path Path to create (TODO ref path). |
| 829 | * @param[in] value Value of the new leaf/leaf-list/anyxml/anydata. For other node types, it is ignored. |
| 830 | * @param[in] value_type Anyxml/anydata node @p value type. |
| 831 | * @param[in] options Bitmask of options, see @ref pathoptions. |
| 832 | * @param[out] new_parent First parent node created, can be NULL. If only one node was created, equals to @p new_node. |
| 833 | * @param[out] new_node Last node created, can be NULL. |
| 834 | * @return LY_ERR value. |
| 835 | */ |
| 836 | LY_ERR lyd_new_path2(struct lyd_node *parent, const struct ly_ctx *ctx, const char *path, const void *value, |
| 837 | LYD_ANYDATA_VALUETYPE value_type, int options, struct lyd_node **new_parent, struct lyd_node **new_node); |
| 838 | |
| 839 | /** |
| 840 | * @brief Change the value of a term (leaf or leaf-list) node. |
| 841 | * |
| 842 | * Node changed this way is always considered explicitly set, meaning its default flag |
| 843 | * is always cleared. |
| 844 | * |
| 845 | * @param[in] term Term node to change. |
| 846 | * @param[in] val_str New value to set, any prefixes are expected in JSON format. |
| 847 | * @return LY_SUCCESS if value was changed, |
| 848 | * @return LY_EEXIST if value was the same and only the default flag was cleared, |
| 849 | * @return LY_ENOT if the values were equal and no change occured, |
| 850 | * @return LY_ERR value on other errors. |
| 851 | */ |
| 852 | LY_ERR lyd_change_term(struct lyd_node *term, const char *val_str); |
| 853 | |
| 854 | /** |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 855 | * @brief Insert a child into a parent. It is inserted as the last child. |
| 856 | * |
| 857 | * - if the node is part of some other tree, it is automatically unlinked. |
| 858 | * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted. |
| 859 | * |
| 860 | * @param[in] parent Parent node to insert into. |
| 861 | * @param[in] node Node to insert. |
| 862 | * @return LY_SUCCESS on success. |
| 863 | * @return LY_ERR error on error. |
| 864 | */ |
| 865 | LY_ERR lyd_insert(struct lyd_node *parent, struct lyd_node *node); |
| 866 | |
| 867 | /** |
Michal Vasko | b1b5c26 | 2020-03-05 14:29:47 +0100 | [diff] [blame] | 868 | * @brief Insert a node into siblings. It is inserted as the last sibling. |
| 869 | * |
| 870 | * - if the node is part of some other tree, it is automatically unlinked. |
| 871 | * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted. |
| 872 | * |
| 873 | * @param[in] sibling Siblings to insert into. |
| 874 | * @param[in] node Node to insert. |
| 875 | * @return LY_SUCCESS on success. |
| 876 | * @return LY_ERR error on error. |
| 877 | */ |
| 878 | LY_ERR lyd_insert_sibling(struct lyd_node *sibling, struct lyd_node *node); |
| 879 | |
| 880 | /** |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 881 | * @brief Insert a node before another node that is its schema sibling. |
| 882 | * |
| 883 | * - if the node is part of some other tree, it is automatically unlinked. |
| 884 | * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted. |
| 885 | * |
| 886 | * @param[in] sibling Sibling node to insert before. |
| 887 | * @param[in] node Node to insert. |
| 888 | * @return LY_SUCCESS on success. |
| 889 | * @return LY_ERR error on error. |
| 890 | */ |
| 891 | LY_ERR lyd_insert_before(struct lyd_node *sibling, struct lyd_node *node); |
| 892 | |
| 893 | /** |
| 894 | * @brief Insert a node after another node that is its schema sibling. |
| 895 | * |
| 896 | * - if the node is part of some other tree, it is automatically unlinked. |
| 897 | * - if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted. |
| 898 | * |
| 899 | * @param[in] sibling Sibling node to insert after. |
| 900 | * @param[in] node Node to insert. |
| 901 | * @return LY_SUCCESS on success. |
| 902 | * @return LY_ERR error on error. |
| 903 | */ |
| 904 | LY_ERR lyd_insert_after(struct lyd_node *sibling, struct lyd_node *node); |
| 905 | |
| 906 | /** |
| 907 | * @brief Unlink the specified data subtree. |
| 908 | * |
| 909 | * @param[in] node Data tree node to be unlinked (together with all the children). |
| 910 | */ |
| 911 | void lyd_unlink_tree(struct lyd_node *node); |
| 912 | |
| 913 | /** |
Radek Krejci | b0849a2 | 2019-07-25 12:31:04 +0200 | [diff] [blame] | 914 | * @brief Free all the nodes (even parents of the node) in the data tree. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 915 | * |
| 916 | * @param[in] node Any of the nodes inside the tree. |
| 917 | */ |
| 918 | void lyd_free_all(struct lyd_node *node); |
| 919 | |
| 920 | /** |
Radek Krejci | b0849a2 | 2019-07-25 12:31:04 +0200 | [diff] [blame] | 921 | * @brief Free all the sibling nodes. |
| 922 | * |
| 923 | * @param[in] node Any of the sibling nodes to free. |
| 924 | */ |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 925 | void lyd_free_siblings(struct lyd_node *node); |
Radek Krejci | b0849a2 | 2019-07-25 12:31:04 +0200 | [diff] [blame] | 926 | |
| 927 | /** |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 928 | * @brief Free (and unlink) the specified data (sub)tree. |
| 929 | * |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 930 | * @param[in] node Root of the (sub)tree to be freed. |
| 931 | */ |
| 932 | void lyd_free_tree(struct lyd_node *node); |
| 933 | |
| 934 | /** |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 935 | * @brief Destroy metadata. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 936 | * |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 937 | * @param[in] ctx Context where the metadata was created. |
| 938 | * @param[in] meta Metadata to destroy |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 939 | * @param[in] recursive Zero to destroy only the single metadata (the metadata list is corrected), |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 940 | * non-zero to destroy also all the subsequent metadata in the list. |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 941 | */ |
Michal Vasko | 52927e2 | 2020-03-16 17:26:14 +0100 | [diff] [blame] | 942 | void lyd_free_meta(const struct ly_ctx *ctx, struct lyd_meta *meta, int recursive); |
| 943 | |
| 944 | /** |
| 945 | * @brief Destroy attributes. |
| 946 | * |
| 947 | * @param[in] ctx Context where the attributes were created. |
| 948 | * @param[in] attr Attributes to destroy. |
| 949 | * @param[in] recursive Zero to destroy only the single attribute (the attribute list is corrected), |
| 950 | * non-zero to destroy also all the subsequent attributes in the list. |
| 951 | */ |
| 952 | void ly_free_attr(const struct ly_ctx *ctx, struct ly_attr *attr, int recursive); |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 953 | |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 954 | /** |
| 955 | * @brief Check type restrictions applicable to the particular leaf/leaf-list with the given string @p value. |
| 956 | * |
| 957 | * The given node is not modified in any way - it is just checked if the @p value can be set to the node. |
| 958 | * |
| 959 | * If there is no data node instance and you are fine with checking just the type's restrictions without the |
| 960 | * data tree context (e.g. for the case of require-instance restriction), use lys_value_validate(). |
| 961 | * |
| 962 | * @param[in] ctx libyang context for logging (function does not log errors when @p ctx is NULL) |
| 963 | * @param[in] node Data node for the @p value. |
| 964 | * @param[in] value String value to be checked. |
| 965 | * @param[in] value_len Length of the given @p value (mandatory). |
| 966 | * @param[in] get_prefix Callback function to resolve prefixes used in the @p value string. |
| 967 | * @param[in] get_prefix_data Private data for the @p get_prefix callback. |
| 968 | * @param[in] format Input format of the data. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 969 | * @param[in] tree Data tree (e.g. when validating RPC/Notification) where the required data instance (leafref target, |
| 970 | * instance-identifier) can be placed. NULL in case the data tree is not yet complete, |
| 971 | * then LY_EINCOMPLETE can be returned. |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 972 | * @return LY_SUCCESS on success |
| 973 | * @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). |
| 974 | * @return LY_ERR value if an error occurred. |
| 975 | */ |
Michal Vasko | 44685da | 2020-03-17 15:38:06 +0100 | [diff] [blame] | 976 | LY_ERR lyd_value_validate(const struct ly_ctx *ctx, const struct lyd_node_term *node, const char *value, size_t value_len, |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 977 | ly_clb_resolve_prefix get_prefix, void *get_prefix_data, LYD_FORMAT format, const struct lyd_node *tree); |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 978 | |
| 979 | /** |
| 980 | * @brief Compare the node's value with the given string value. The string value is first validated according to the node's type. |
| 981 | * |
| 982 | * @param[in] node Data node to compare. |
| 983 | * @param[in] value String value to be compared. It does not need to be in a canonical form - as part of the process, |
| 984 | * it is validated and canonized if possible. |
| 985 | * @param[in] value_len Length of the given @p value (mandatory). |
| 986 | * @param[in] get_prefix Callback function to resolve prefixes used in the @p value string. |
| 987 | * @param[in] get_prefix_data Private data for the @p get_prefix callback. |
| 988 | * @param[in] format Input format of the data. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 989 | * @param[in] tree Data tree (e.g. when validating RPC/Notification) where the required data instance (leafref target, |
| 990 | * instance-identifier) can be placed. NULL in case the data tree is not yet complete, |
| 991 | * then LY_EINCOMPLETE can be returned. |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 992 | * @return LY_SUCCESS on success |
| 993 | * @return LY_EINCOMPLETE in case of success when the @p trees is not provided and it was needed to finish the validation of |
| 994 | * the given string @p value (e.g. due to require-instance). |
| 995 | * @return LY_ERR value if an error occurred. |
| 996 | */ |
| 997 | LY_ERR lyd_value_compare(const struct lyd_node_term *node, const char *value, size_t value_len, |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 998 | ly_clb_resolve_prefix get_prefix, void *get_prefix_data, LYD_FORMAT format, const struct lyd_node *tree); |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 999 | |
Radek Krejci | 576b23f | 2019-07-12 14:06:32 +0200 | [diff] [blame] | 1000 | /** |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 1001 | * @defgroup datacompareoptions Data compare options |
| 1002 | * @ingroup datatree |
| 1003 | * |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 1004 | * Various options to change the lyd_compare() behavior. |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 1005 | */ |
| 1006 | #define LYD_COMPARE_FULL_RECURSION 0x01 /* lists and containers are the same only in case all they children |
| 1007 | (subtree, so direct as well as indirect children) are the same. By default, |
| 1008 | containers are the same in case of the same schema node and lists are the same |
| 1009 | in case of equal keys (keyless lists do the full recursion comparison all the time). */ |
| 1010 | #define LYD_COMPARE_DEFAULTS 0x02 /* By default, implicit and explicit default nodes are considered to be equal. This flag |
| 1011 | changes this behavior and implicit (automatically created default node) and explicit |
| 1012 | (explicitly created node with the default value) default nodes are considered different. */ |
Michal Vasko | 60ea635 | 2020-06-29 13:39:39 +0200 | [diff] [blame] | 1013 | /** @} datacompareoptions */ |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 1014 | |
| 1015 | /** |
| 1016 | * @brief Compare 2 data nodes if they are equivalent. |
| 1017 | * |
| 1018 | * @param[in] node1 The first node to compare. |
| 1019 | * @param[in] node2 The second node to compare. |
Radek Krejci | c5ad965 | 2019-09-11 11:31:51 +0200 | [diff] [blame] | 1020 | * @param[in] options Various @ref datacompareoptions. |
Radek Krejci | 1f05b6a | 2019-07-18 16:15:06 +0200 | [diff] [blame] | 1021 | * @return LY_SUCCESS if the nodes are equivalent. |
| 1022 | * @return LY_ENOT if the nodes are not equivalent. |
| 1023 | */ |
| 1024 | LY_ERR lyd_compare(const struct lyd_node *node1, const struct lyd_node *node2, int options); |
| 1025 | |
| 1026 | /** |
Michal Vasko | 2172574 | 2020-06-29 11:49:25 +0200 | [diff] [blame] | 1027 | * @brief Compare 2 metadata. |
| 1028 | * |
| 1029 | * @param[in] meta1 First metadata. |
| 1030 | * @param[in] meta2 Second metadata. |
| 1031 | * @return LY_SUCCESS if the metadata are equivalent. |
| 1032 | * @return LY_ENOT if not. |
| 1033 | */ |
| 1034 | LY_ERR lyd_compare_meta(const struct lyd_meta *meta1, const struct lyd_meta *meta2); |
| 1035 | |
| 1036 | /** |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 1037 | * @defgroup dupoptions Data duplication options |
| 1038 | * @ingroup datatree |
| 1039 | * |
| 1040 | * Various options to change lyd_dup() behavior. |
| 1041 | * |
| 1042 | * Default behavior: |
| 1043 | * - only the specified node is duplicated without siblings, parents, or children. |
| 1044 | * - all the attributes of the duplicated nodes are also duplicated. |
| 1045 | * @{ |
| 1046 | */ |
| 1047 | |
| 1048 | #define LYD_DUP_RECURSIVE 0x01 /**< Duplicate not just the node but also all the children. Note that |
| 1049 | list's keys are always duplicated. */ |
Michal Vasko | a29a576 | 2020-06-23 13:28:49 +0200 | [diff] [blame] | 1050 | #define LYD_DUP_NO_META 0x02 /**< Do not duplicate metadata of any node. */ |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 1051 | #define LYD_DUP_WITH_PARENTS 0x04 /**< If a nested node is being duplicated, duplicate also all the parents. |
| 1052 | Keys are also duplicated for lists. Return value does not change! */ |
| 1053 | #define LYD_DUP_WITH_SIBLINGS 0x08 /**< Duplicate also all the sibling of the given node. */ |
Michal Vasko | f6df0a0 | 2020-06-16 13:08:34 +0200 | [diff] [blame] | 1054 | #define LYD_DUP_WITH_FLAGS 0x10 /**< Also copy any data node flags. That will cause the duplicated data to preserve |
| 1055 | its validation/default node state. */ |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 1056 | |
| 1057 | /** @} dupoptions */ |
| 1058 | |
| 1059 | /** |
| 1060 | * @brief Create a copy of the specified data tree \p node. Schema references are kept the same. |
| 1061 | * |
Radek Krejci | 22ebdba | 2019-07-25 13:59:43 +0200 | [diff] [blame] | 1062 | * @param[in] node Data tree node to be duplicated. |
| 1063 | * @param[in] parent Optional parent node where to connect the duplicated node(s). |
| 1064 | * If set in combination with LYD_DUP_WITH_PARENTS, the parents chain is duplicated until it comes to and connect with the @p parent |
| 1065 | * (if the parents chain does not match at some node the schema node of the provided @p parent, duplication fails). |
| 1066 | * @param[in] options Bitmask of options flags, see @ref dupoptions. |
| 1067 | * @return Created copy of the provided data \p node (the first of the duplicated siblings when LYD_DUP_WITH_SIBLINGS used). |
| 1068 | * Note that in case the parents chain is duplicated for the duplicated node(s) (when LYD_DUP_WITH_PARENTS used), the first duplicated node |
| 1069 | * is still returned, not a pointer to the duplicated parents. |
| 1070 | */ |
| 1071 | struct lyd_node *lyd_dup(const struct lyd_node *node, struct lyd_node_inner *parent, int options); |
| 1072 | |
| 1073 | /** |
Michal Vasko | 4490d31 | 2020-06-16 13:08:55 +0200 | [diff] [blame] | 1074 | * @defgroup mergeoptions Data merge options. |
| 1075 | * @ingroup datatree |
Radek Krejci | 576b23f | 2019-07-12 14:06:32 +0200 | [diff] [blame] | 1076 | * |
Michal Vasko | 4490d31 | 2020-06-16 13:08:55 +0200 | [diff] [blame] | 1077 | * Various options to change lyd_merge() behavior. |
| 1078 | * |
| 1079 | * Default behavior: |
| 1080 | * - source data tree is not modified in any way, |
| 1081 | * - source data tree is merged with any succeeding siblings, |
| 1082 | * - any default nodes from source replace explicit nodes in the target. |
| 1083 | * @{ |
| 1084 | */ |
| 1085 | |
| 1086 | #define LYD_MERGE_DESTRUCT 0x01 /**< Spend source data tree in the function, it cannot be used afterwards! */ |
| 1087 | #define LYD_MERGE_NOSIBLINGS 0x02 /**< Merge only the single source data tree, no siblings. */ |
| 1088 | #define LYD_MERGE_EXPLICIT 0x04 /**< Default nodes in the source tree are ignored if there are explicit nodes |
| 1089 | in the target tree. */ |
| 1090 | |
| 1091 | /** @} mergeoptions */ |
| 1092 | |
| 1093 | /** |
| 1094 | * @brief Merge the source data tree into the target data tree. Merge may not be complete until validation |
| 1095 | * is called on the resulting data tree (data from more cases may be present, default and non-default values). |
| 1096 | * |
| 1097 | * @param[in,out] target Target data tree to merge into, must be a top-level tree. |
| 1098 | * @param[in] source Source data tree to merge, must be a top-level tree. |
| 1099 | * @param[in] options Bitmask of option flags, see @ref mergeoptions. |
| 1100 | * @return LY_SUCCESS on success, |
| 1101 | * @return LY_ERR value on error. |
| 1102 | */ |
| 1103 | LY_ERR lyd_merge(struct lyd_node **target, const struct lyd_node *source, int options); |
| 1104 | |
| 1105 | /** |
Michal Vasko | e893ddd | 2020-06-23 13:35:20 +0200 | [diff] [blame] | 1106 | * @defgroup diffoptions Data diff options. |
| 1107 | * @ingroup datatree |
| 1108 | * |
| 1109 | * Various options to change lyd_diff() behavior. |
| 1110 | * |
| 1111 | * Default behavior: |
| 1112 | * - data trees are compared with all the siblings, |
| 1113 | * - any default nodes are treated as non-existent and ignored. |
| 1114 | * @{ |
| 1115 | */ |
| 1116 | |
| 1117 | #define LYD_DIFF_NOSIBLINGS 0x01 /**< Only the single subtree is compared, no siblings. */ |
| 1118 | #define LYD_DIFF_WITHDEFAULTS 0x02 /**< Default nodes in the trees are not ignored but treated similarly to explicit |
| 1119 | nodes. Also, leaves and leaf-lists are added into diff even in case only their |
| 1120 | default flag (state) was changed. */ |
| 1121 | |
| 1122 | /** @} diffoptions */ |
| 1123 | |
| 1124 | /** |
| 1125 | * @brief Learn the differences between 2 data trees. |
| 1126 | * |
| 1127 | * The resulting diff is represented as a data tree with specific metadata from the internal 'yang' |
| 1128 | * module. Most importantly, every node has an effective 'operation' metadata. If there is none |
| 1129 | * defined on the node, it inherits the operation from the nearest parent. Top-level nodes must |
| 1130 | * always have the 'operation' metadata defined. Additional metadata ('orig-default', 'value', |
| 1131 | * 'orig-value', 'key', 'orig-key') are used for storing more information about the value in the first |
| 1132 | * or the second tree. |
| 1133 | * |
| 1134 | * The diff tree is completely independent on the @p first and @p second trees, meaning all |
| 1135 | * the information about the change is stored in the diff and the trees are not needed. |
| 1136 | * |
| 1137 | * !! Caution !! |
| 1138 | * The diff tree should never be validated because it may easily not be valid! For example, |
| 1139 | * when data from one case branch are deleted and data from another branch created - data from both |
| 1140 | * branches are then stored in the diff tree simultaneously. |
| 1141 | * |
| 1142 | * @param[in] first First data tree. |
| 1143 | * @param[in] second Second data tree. |
| 1144 | * @param[in] options Bitmask of options flags, see @ref diffoptions. |
| 1145 | * @param[out] diff Generated diff. |
| 1146 | * @return LY_SUCCESS on success, |
| 1147 | * @return LY_ERR on error. |
| 1148 | */ |
| 1149 | LY_ERR lyd_diff(const struct lyd_node *first, const struct lyd_node *second, int options, struct lyd_node **diff); |
| 1150 | |
| 1151 | /** |
| 1152 | * @brief Callback for diff nodes. |
| 1153 | * |
| 1154 | * @param[in] diff_node Diff node. |
| 1155 | * @param[in] data_node Matching node in data. |
| 1156 | * @param[in] cb_data Arbitrary callback data. |
| 1157 | * @return LY_ERR value. |
| 1158 | */ |
| 1159 | typedef LY_ERR (*lyd_diff_cb)(const struct lyd_node *diff_node, struct lyd_node *data_node, void *cb_data); |
| 1160 | |
| 1161 | /** |
| 1162 | * @brief Apply a difference on a data tree but restrict the operation to one module. |
| 1163 | * |
| 1164 | * @param[in,out] data Data to apply the diff on. |
| 1165 | * @param[in] diff Diff to apply. |
| 1166 | * @param[in] mod Module, whose diff/data only to consider, NULL for all modules. |
| 1167 | * @param[in] diff_cb Optional diff callback that will be called for every changed node. |
| 1168 | * @param[in] cb_data Arbitrary callback data. |
| 1169 | * @return LY_SUCCESS on success, |
| 1170 | * @return LY_ERR on error. |
| 1171 | */ |
| 1172 | LY_ERR lyd_diff_apply_module(struct lyd_node **data, const struct lyd_node *diff, const struct lys_module *mod, |
| 1173 | lyd_diff_cb diff_cb, void *cb_data); |
| 1174 | |
| 1175 | /** |
| 1176 | * @brief Apply a difference on a data tree. |
| 1177 | * |
| 1178 | * @param[in,out] data Data to apply the diff on. |
| 1179 | * @param[in] diff Diff to apply. |
| 1180 | * @return LY_SUCCESS on success, |
| 1181 | * @return LY_ERR on error. |
| 1182 | */ |
| 1183 | LY_ERR lyd_diff_apply(struct lyd_node **data, const struct lyd_node *diff); |
| 1184 | |
| 1185 | /** |
Michal Vasko | 4490d31 | 2020-06-16 13:08:55 +0200 | [diff] [blame] | 1186 | * @brief Find the target in data of a compiled ly_path structure (instance-identifier). |
| 1187 | * |
| 1188 | * @param[in] path Compiled path structure. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 1189 | * @param[in] tree Data tree to be searched. |
Michal Vasko | 4490d31 | 2020-06-16 13:08:55 +0200 | [diff] [blame] | 1190 | * @return Found target node, |
| 1191 | * @return NULL if not found. |
Radek Krejci | 576b23f | 2019-07-12 14:06:32 +0200 | [diff] [blame] | 1192 | */ |
Michal Vasko | 004d315 | 2020-06-11 19:59:22 +0200 | [diff] [blame] | 1193 | const struct lyd_node_term *lyd_target(const struct ly_path *path, const struct lyd_node *tree); |
Radek Krejci | 084289f | 2019-07-09 17:35:30 +0200 | [diff] [blame] | 1194 | |
Michal Vasko | 5ec7cda | 2019-09-11 13:43:08 +0200 | [diff] [blame] | 1195 | /** |
| 1196 | * @brief Get string value of a term data \p node. |
| 1197 | * |
| 1198 | * @param[in] node Data tree node with the value. |
| 1199 | * @param[out] dynamic Whether the string value was dynmically allocated. |
| 1200 | * @return String value of @p node, if @p dynamic, needs to be freed. |
| 1201 | */ |
| 1202 | const char *lyd_value2str(const struct lyd_node_term *node, int *dynamic); |
| 1203 | |
| 1204 | /** |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 1205 | * @brief Get string value of a metadata \p meta. |
Michal Vasko | 5ec7cda | 2019-09-11 13:43:08 +0200 | [diff] [blame] | 1206 | * |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 1207 | * @param[in] meta Metadata with the value. |
Michal Vasko | 5ec7cda | 2019-09-11 13:43:08 +0200 | [diff] [blame] | 1208 | * @param[out] dynamic Whether the string value was dynmically allocated. |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 1209 | * @return String value of @p meta, if @p dynamic, needs to be freed. |
Michal Vasko | 5ec7cda | 2019-09-11 13:43:08 +0200 | [diff] [blame] | 1210 | */ |
Michal Vasko | 9f96a05 | 2020-03-10 09:41:45 +0100 | [diff] [blame] | 1211 | const char *lyd_meta2str(const struct lyd_meta *meta, int *dynamic); |
Michal Vasko | 5ec7cda | 2019-09-11 13:43:08 +0200 | [diff] [blame] | 1212 | |
| 1213 | /** |
| 1214 | * @brief Types of the different data paths. |
| 1215 | */ |
| 1216 | typedef enum { |
Michal Vasko | 1465471 | 2020-02-06 08:35:21 +0100 | [diff] [blame] | 1217 | LYD_PATH_LOG, /**< Descriptive path format used in log messages */ |
Michal Vasko | 5ec7cda | 2019-09-11 13:43:08 +0200 | [diff] [blame] | 1218 | } LYD_PATH_TYPE; |
| 1219 | |
| 1220 | /** |
| 1221 | * @brief Generate path of the given node in the requested format. |
| 1222 | * |
| 1223 | * @param[in] node Schema path of this node will be generated. |
| 1224 | * @param[in] pathtype Format of the path to generate. |
| 1225 | * @param[in,out] buffer Prepared buffer of the @p buflen length to store the generated path. |
| 1226 | * If NULL, memory for the complete path is allocated. |
| 1227 | * @param[in] buflen Size of the provided @p buffer. |
| 1228 | * @return NULL in case of memory allocation error, path of the node otherwise. |
| 1229 | * In case the @p buffer is NULL, the returned string is dynamically allocated and caller is responsible to free it. |
| 1230 | */ |
| 1231 | char *lyd_path(const struct lyd_node *node, LYD_PATH_TYPE pathtype, char *buffer, size_t buflen); |
| 1232 | |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1233 | /** |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1234 | * @brief Find the node, in the list, satisfying the given restrictions. |
| 1235 | * Does **not** use hashes - should not be used unless necessary for best performance. |
| 1236 | * |
| 1237 | * @param[in] first Starting sibling node for search, only succeeding ones are searched. |
| 1238 | * @param[in] module Module of the node to find. |
| 1239 | * @param[in] name Name of the node to find. |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 1240 | * @param[in] name_len Optional length of @p name in case it is not 0-terminated string. |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1241 | * @param[in] key_or_value Expected value depends on the type of @p name node: |
| 1242 | * LYS_CONTAINER: |
| 1243 | * LYS_ANYXML: |
| 1244 | * LYS_ANYDATA: |
| 1245 | * LYS_NOTIF: |
| 1246 | * LYS_RPC: |
| 1247 | * LYS_ACTION: |
| 1248 | * NULL should be always set, will be ignored. |
| 1249 | * LYS_LEAF: |
| 1250 | * LYS_LEAFLIST: |
Michal Vasko | 90932a9 | 2020-02-12 14:33:03 +0100 | [diff] [blame] | 1251 | * Optional restriction on the specific leaf(-list) value. |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1252 | * LYS_LIST: |
| 1253 | * Optional keys values of the matching list instances in the form of "[key1='val1'][key2='val2']...". |
Michal Vasko | 90932a9 | 2020-02-12 14:33:03 +0100 | [diff] [blame] | 1254 | * The keys do not have to be ordered and not all keys need to be specified. |
| 1255 | * |
| 1256 | * Note that any explicit values (leaf, leaf-list or list key values) will be canonized first |
| 1257 | * before comparison. But values that do not have a canonical value are expected to be in the |
| 1258 | * JSON format! |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 1259 | * @param[in] val_len Optional length of @p key_or_value in case it is not 0-terminated string. |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1260 | * @param[out] match Found data node. |
| 1261 | * @return LY_SUCCESS on success, @p match set. |
| 1262 | * @return LY_ENOTFOUND if not found, @p match set to NULL. |
| 1263 | * @return LY_ERR value if another error occurred. |
| 1264 | */ |
| 1265 | LY_ERR lyd_find_sibling_next(const struct lyd_node *first, const struct lys_module *module, const char *name, |
| 1266 | size_t name_len, const char *key_or_value, size_t val_len, struct lyd_node **match); |
| 1267 | |
| 1268 | /** |
| 1269 | * @brief Search in the given siblings (NOT recursively) for the first target instance. |
| 1270 | * Uses hashes - should be used whenever possible for best performance. |
| 1271 | * |
| 1272 | * @param[in] siblings Siblings to search in including preceding and succeeding nodes. |
| 1273 | * @param[in] target Target node to find. |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 1274 | * @param[out] match Can be NULL, otherwise the found data node. |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1275 | * @return LY_SUCCESS on success, @p match set. |
| 1276 | * @return LY_ENOTFOUND if not found, @p match set to NULL. |
| 1277 | * @return LY_ERR value if another error occurred. |
| 1278 | */ |
| 1279 | LY_ERR lyd_find_sibling_first(const struct lyd_node *siblings, const struct lyd_node *target, struct lyd_node **match); |
| 1280 | |
| 1281 | /** |
| 1282 | * @brief Search in the given siblings for all target instances. |
| 1283 | * Uses hashes - should be used whenever possible for best performance. |
| 1284 | * |
| 1285 | * @param[in] siblings Siblings to search in including preceding and succeeding nodes. |
| 1286 | * @param[in] target Target node to find. Key-less lists are compared based on |
| 1287 | * all its descendants (both direct and indirect). |
| 1288 | * @param[out] set Found nodes in a set in case of success. |
| 1289 | * @return LY_SUCCESS on success. |
| 1290 | * @return LY_ENOTFOUND if no matching siblings found. |
| 1291 | * @return LY_ERR value if another error occurred. |
| 1292 | */ |
| 1293 | LY_ERR lyd_find_sibling_set(const struct lyd_node *siblings, const struct lyd_node *target, struct ly_set **set); |
| 1294 | |
| 1295 | /** |
| 1296 | * @brief Search in the given siblings for the first schema instance. |
| 1297 | * Uses hashes - should be used whenever possible for best performance. |
| 1298 | * |
| 1299 | * @param[in] siblings Siblings to search in including preceding and succeeding nodes. |
| 1300 | * @param[in] schema Schema node of the data node to find. |
| 1301 | * @param[in] key_or_value Expected value depends on the type of \p schema: |
| 1302 | * LYS_CONTAINER: |
| 1303 | * LYS_LEAF: |
| 1304 | * LYS_ANYXML: |
| 1305 | * LYS_ANYDATA: |
| 1306 | * LYS_NOTIF: |
| 1307 | * LYS_RPC: |
| 1308 | * LYS_ACTION: |
| 1309 | * NULL should be always set, will be ignored. |
| 1310 | * LYS_LEAFLIST: |
| 1311 | * Searched instance value. |
| 1312 | * LYS_LIST: |
Michal Vasko | 90932a9 | 2020-02-12 14:33:03 +0100 | [diff] [blame] | 1313 | * Searched instance key values in the form of "[key1='val1'][key2='val2']...". |
| 1314 | * The keys do not have to be ordered but all of them must be set. |
| 1315 | * |
| 1316 | * Note that any explicit values (leaf-list or list key values) will be canonized first |
| 1317 | * before comparison. But values that do not have a canonical value are expected to be in the |
| 1318 | * JSON format! |
Michal Vasko | f03ed03 | 2020-03-04 13:31:44 +0100 | [diff] [blame] | 1319 | * @param[in] val_len Optional length of @p key_or_value in case it is not 0-terminated. |
Michal Vasko | 9b368d3 | 2020-02-14 13:53:31 +0100 | [diff] [blame] | 1320 | * @param[out] match Can be NULL, otherwise the found data node. |
Michal Vasko | e444f75 | 2020-02-10 12:20:06 +0100 | [diff] [blame] | 1321 | * @return LY_SUCCESS on success, @p match set. |
| 1322 | * @return LY_ENOTFOUND if not found, @p match set to NULL. |
| 1323 | * @return LY_EINVAL if @p schema is a key-less list. |
| 1324 | * @return LY_ERR value if another error occurred. |
| 1325 | */ |
| 1326 | LY_ERR lyd_find_sibling_val(const struct lyd_node *siblings, const struct lysc_node *schema, const char *key_or_value, |
| 1327 | size_t val_len, struct lyd_node **match); |
| 1328 | |
Michal Vasko | ccc0234 | 2020-05-21 10:09:21 +0200 | [diff] [blame] | 1329 | /** |
| 1330 | * @brief Search in the given data for instances of nodes matching the provided XPath. |
| 1331 | * |
Michal Vasko | 61ac2f6 | 2020-05-25 12:39:51 +0200 | [diff] [blame] | 1332 | * The expected format of the expression is JSON (::LYD_JSON) meaning the first node in every path |
| 1333 | * must have its module name as prefix or be the special `*` value for all the nodes. |
| 1334 | * |
Michal Vasko | 19a3060 | 2020-05-25 10:40:19 +0200 | [diff] [blame] | 1335 | * If a list instance is being selected with all its key values specified (but not necessarily ordered) |
| 1336 | * in the form `list[key1='val1'][key2='val2'][key3='val3']` or a leaf-list instance in the form |
| 1337 | * `leaf-list[.='val']`, these instances are found using hashes with constant (*O(1)*) complexity |
| 1338 | * (unless they are defined in top-level). Other predicates can still follow the aforementioned ones. |
| 1339 | * |
Michal Vasko | ccc0234 | 2020-05-21 10:09:21 +0200 | [diff] [blame] | 1340 | * @param[in] ctx_node XPath context node. |
| 1341 | * @param[in] xpath Data XPath expression filtering the matching nodes. ::LYD_JSON format is expected. |
| 1342 | * @param[out] set Set of found data nodes. In case the result is a number, a string, or a boolean, |
| 1343 | * the returned set is empty. |
| 1344 | * @return LY_SUCCESS on success, @p set is returned. |
| 1345 | * @return LY_ERR value if an error occurred. |
| 1346 | */ |
| 1347 | LY_ERR lyd_find_xpath(const struct lyd_node *ctx_node, const char *xpath, struct ly_set **set); |
| 1348 | |
Radek Krejci | e7b9509 | 2019-05-15 11:03:07 +0200 | [diff] [blame] | 1349 | #ifdef __cplusplus |
| 1350 | } |
| 1351 | #endif |
| 1352 | |
| 1353 | #endif /* LY_TREE_DATA_H_ */ |