blob: 4b16efc6fea758acb3ec30cfbcb136ec24ffd54b [file] [log] [blame]
Radek Krejci7931b192020-06-25 17:05:03 +02001/**
2 * @file parser_data.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Data parsers for libyang
5 *
6 * Copyright (c) 2015-2020 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_PARSER_DATA_H_
16#define LY_PARSER_DATA_H_
17
18#include "tree_data.h"
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24struct ly_in;
25
26/**
27 * @addtogroup datatree
28 * @{
29 */
30
31/**
32 * @defgroup dataparseroptions Data parser options
33 *
34 * Various options to change the data tree parsers behavior.
35 *
36 * Default parser behavior:
37 * - complete input file is always parsed. In case of XML, even not well-formed XML document (multiple top-level
38 * elements) is parsed in its entirety,
39 * - parser silently ignores data without matching schema node definition,
40 * - list instances are checked whether they have all the keys, error is raised if not.
41 *
42 * Default parser validation behavior:
43 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
44 * and performs data validation according to all YANG rules, specifics follow,
45 * - list instances are expected to have all the keys (it is not checked),
46 * - instantiated (status) obsolete data print a warning,
47 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
48 * all the keys, leaf(-lists) correct values),
49 * - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised,
50 * - if-feature statements are evaluated,
51 * - invalid multiple data instances/data from several cases cause a validation error,
Michal Vaskoa6669ba2020-08-06 16:14:26 +020052 * - implicit nodes (NP containers and default values) are added.
Radek Krejci7931b192020-06-25 17:05:03 +020053 * @{
54 */
55/* note: keep the lower 16bits free for use by LYD_VALIDATE_ flags. They are not supposed to be combined together,
56 * but since they are used (as a separate parameter) together in some functions, we want to keep them in a separated
57 * range to be able detect that the caller put wrong flags into the parser/validate options parameter. */
58#define LYD_PARSE_ONLY 0x010000 /**< Data will be only parsed and no validation will be performed. When statements
59 are kept unevaluated, union types may not be fully resolved, if-feature
60 statements are not checked, and default values are not added (only the ones
61 parsed are present). */
62#define LYD_PARSE_TRUSTED 0x020000 /**< Data are considered trusted so they will be parsed as validated. If the parsed
63 data are not valid, using this flag may lead to some unexpected behavior!
64 This flag can be used only with #LYD_OPT_PARSE_ONLY. */
65#define LYD_PARSE_STRICT 0x040000 /**< Instead of silently ignoring data without schema definition raise an error.
Michal Vasko4afb24e2020-07-15 14:37:26 +020066 Do not combine with #LYD_OPT_OPAQ (except for ::LYD_LYB). */
Radek Krejci7931b192020-06-25 17:05:03 +020067#define LYD_PARSE_OPAQ 0x080000 /**< Instead of silently ignoring data without definition, parse them into
Michal Vasko4afb24e2020-07-15 14:37:26 +020068 an opaq node. Do not combine with #LYD_OPT_STRICT (except for ::LYD_LYB). */
Radek Krejci7931b192020-06-25 17:05:03 +020069#define LYD_PARSE_NO_STATE 0x100000 /**< Forbid state data in the parsed data. */
70
71#define LYD_PARSE_LYB_MOD_UPDATE 0x200000 /**< Only for LYB format, allow parsing data printed using a specific module
72 revision to be loaded even with a module with the same name but newer
73 revision. */
74/** @} dataparseroptions */
75
Radek Krejci7931b192020-06-25 17:05:03 +020076/**
77 * @defgroup datavalidationoptions Data validation options
78 * @ingroup datatree
79 *
80 * Various options to change data validation behaviour, both for the parser and separate validation.
81 *
82 * Default separate validation behavior:
83 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
84 * and performs data validation according to all YANG rules, specifics follow,
85 * - instantiated (status) obsolete data print a warning,
86 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
87 * all the keys, leaf(-lists) correct values),
88 * - when statements on existing nodes are evaluated. Depending on the previous when state (from previous validation
89 * or parsing), the node is silently auto-deleted if the state changed from true to false, otherwise a validation error
90 * is raised if it evaluates to false,
91 * - if-feature statements are evaluated,
92 * - data from several cases behave based on their previous state (from previous validation or parsing). If there existed
93 * already a case and another one was added, the previous one is silently auto-deleted. Otherwise (if data from 2 or
94 * more cases were created) a validation error is raised,
95 * - default values are added.
96 *
97 * @{
98 */
99#define LYD_VALIDATE_NO_STATE 0x0001 /**< Consider state data not allowed and raise an error if they are found. */
100#define LYD_VALIDATE_PRESENT 0x0002 /**< Validate only modules whose data actually exist. */
Radek Krejci7931b192020-06-25 17:05:03 +0200101
102/** @} datavalidationoptions */
103
104/**
105 * @defgroup datavalidateop Operation to validate
106 * @ingroup datatree
107 *
108 * Operation provided to lyd_validate_op() to validate. The operation cannot be determined automatically since RPC/action and a reply to it
109 * share the common top level node referencing the RPC/action schema node and may not have any input/output children to use for distinction.
110 */
111typedef enum {
112 LYD_VALIDATE_OP_RPC = 1, /**< Validate RPC/action request (input parameters). */
113 LYD_VALIDATE_OP_REPLY, /**< Validate RPC/action reply (output parameters). */
114 LYD_VALIDATE_OP_NOTIF /**< Validate Notification operation. */
115} LYD_VALIDATE_OP;
116
117/** @} datavalidateop */
118
119/**
120 * @brief Parse (and validate) data from the input handler as a YANG data tree.
121 *
122 * @param[in] ctx Context to connect with the tree being built here.
123 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
124 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
125 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
126 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
127 * @param[out] tree Resulting data tree built from the input data. Note that NULL can be a valid result as a representation of an empty YANG data tree.
128 * The returned data are expected to be freed using lyd_free_all().
129 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200130 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200131 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200132LY_ERR lyd_parse_data(const struct ly_ctx *ctx, struct ly_in *in, LYD_FORMAT format, uint32_t parse_options,
133 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200134
135/**
136 * @brief Parse (and validate) input data as a YANG data tree.
137 *
138 * Wrapper around lyd_parse_data() hiding work with the input handler.
139 *
140 * @param[in] ctx Context to connect with the tree being built here.
141 * @param[in] data The input data in the specified @p format to parse (and validate).
142 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
143 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
144 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
145 * @param[out] tree Resulting data tree built from the input data. Note that NULL can be a valid result as a representation of an empty YANG data tree.
146 * The returned data are expected to be freed using lyd_free_all().
147 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200148 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200149 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200150LY_ERR lyd_parse_data_mem(const struct ly_ctx *ctx, const char *data, LYD_FORMAT format, uint32_t parse_options,
151 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200152
153/**
154 * @brief Parse (and validate) input data as a YANG data tree.
155 *
156 * Wrapper around lyd_parse_data() hiding work with the input handler.
157 *
158 * @param[in] ctx Context to connect with the tree being built here.
159 * @param[in] fd File descriptor of a regular file (e.g. sockets are not supported) containing the input data in the specified @p format to parse (and validate).
160 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
161 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
162 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
163 * @param[out] tree Resulting data tree built from the input data. Note that NULL can be a valid result as a representation of an empty YANG data tree.
164 * The returned data are expected to be freed using lyd_free_all().
165 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200166 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200167 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200168LY_ERR lyd_parse_data_fd(const struct ly_ctx *ctx, int fd, LYD_FORMAT format, uint32_t parse_options, uint32_t validate_options,
Radek Krejci0f969882020-08-21 16:56:47 +0200169 struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200170
171/**
172 * @brief Parse (and validate) input data as a YANG data tree.
173 *
174 * Wrapper around lyd_parse_data() hiding work with the input handler.
175 *
176 * @param[in] ctx Context to connect with the tree being built here.
177 * @param[in] path Path to the file with the input data in the specified @p format to parse (and validate).
178 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
179 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
180 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
181 * @param[out] tree Resulting data tree built from the input data. Note that NULL can be a valid result as a representation of an empty YANG data tree.
182 * The returned data are expected to be freed using lyd_free_all().
183 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200184 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200185 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200186LY_ERR lyd_parse_data_path(const struct ly_ctx *ctx, const char *path, LYD_FORMAT format, uint32_t parse_options,
187 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200188
189/**
190 * @brief Parse (and validate) data from the input handler as a YANG RPC/action invocation.
191 *
192 * In case o LYD_XML @p format, the \<rpc\> envelope element is accepted if present. It is [checked](https://tools.ietf.org/html/rfc6241#section-4.1), an opaq
193 * data node (lyd_node_opaq) is created and all its XML attributes are parsed and inserted into the node. As a content of the enveloper, an RPC data or
194 * \<action\> envelope element is expected. The \<action\> envelope element is also [checked](https://tools.ietf.org/html/rfc7950#section-7.15.2) and parsed as
195 * the \<rpc\> envelope. Inside the \<action\> envelope, only an action data are expected.
196 *
197 * @param[in] ctx Context to connect with the tree being built here.
198 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
199 * @param[in] format Format of the input data to be parsed.
200 * @param[out] tree Resulting full RPC/action tree built from the input data. The returned data are expected to be freed using lyd_free_all().
201 * In contrast to YANG data tree, result of parsing RPC/action cannot be NULL until an error occurs.
202 * @param[out] op Optional pointer to the actual operation node inside the full action @p tree, useful only for action.
203 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200204 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200205 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200206LY_ERR lyd_parse_rpc(const struct ly_ctx *ctx, struct ly_in *in, LYD_FORMAT format, struct lyd_node **tree,
Radek Krejci0f969882020-08-21 16:56:47 +0200207 struct lyd_node **op);
Radek Krejci7931b192020-06-25 17:05:03 +0200208
209/**
210 * @brief Parse (and validate) data from the input handler as a YANG RPC/action reply.
211 *
212 * In case o LYD_XML @p format, the \<rpc-reply\> envelope element is accepted if present. It is [checked](https://tools.ietf.org/html/rfc6241#section-4.2), an opaq
213 * data node (lyd_node_opaq) is created and all its XML attributes are parsed and inserted into the node.
214 *
215 * The reply data are strictly expected to be related to the provided RPC/action @p request.
216 *
217 * @param[in] request The RPC/action tree (result of lyd_parse_rpc()) of the request for the reply being parsed.
218 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
219 * @param[in] format Format of the input data to be parsed.
220 * @param[out] tree Resulting full RPC/action reply tree built from the input data. The returned data are expected to be freed using lyd_free_all().
221 * The reply tree always includes duplicated operation node (and its parents) of the @p request, so in contrast to YANG data tree,
Radek Krejci1798aae2020-07-14 13:26:06 +0200222 * the result of parsing RPC/action reply cannot be NULL until an error occurs. At least one of the @p tree and @p op output variables must be provided.
223 * @param[out] op Pointer to the actual operation node inside the full action reply @p tree, useful only for action. At least one of the @p op
224 * and @p tree output variables must be provided.
Radek Krejci7931b192020-06-25 17:05:03 +0200225 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200226 * @return LY_ERR value in case of error. Additional error information can be obtained from the request's context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200227 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200228LY_ERR lyd_parse_reply(const struct lyd_node *request, struct ly_in *in, LYD_FORMAT format, struct lyd_node **tree,
Radek Krejci0f969882020-08-21 16:56:47 +0200229 struct lyd_node **op);
Radek Krejci7931b192020-06-25 17:05:03 +0200230
231/**
232 * @brief Parse XML string as YANG notification.
233 *
234 * In case o LYD_XML @p format, the \<notification\> envelope element in combination with the child \<eventTime\> element are accepted if present. They are
235 * [checked](https://tools.ietf.org/html/rfc5277#page-25), opaq data nodes (lyd_node_opaq) are created and all their XML attributes are parsed and inserted into the nodes.
236 *
237 * @param[in] ctx Context to connect with the tree being built here.
238 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
239 * @param[in] format Format of the input data to be parsed.
240 * @param[out] tree Resulting full Notification tree built from the input data. The returned data are expected to be freed using lyd_free_all().
241 * In contrast to YANG data tree, result of parsing Notification cannot be NULL until an error occurs.
242 * @param[out] ntf Optional pointer to the actual notification node inside the full Notification @p tree, useful for nested notifications.
243 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200244 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
Radek Krejci7931b192020-06-25 17:05:03 +0200245 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200246LY_ERR lyd_parse_notif(const struct ly_ctx *ctx, struct ly_in *in, LYD_FORMAT format, struct lyd_node **tree,
Radek Krejci0f969882020-08-21 16:56:47 +0200247 struct lyd_node **ntf);
Radek Krejci7931b192020-06-25 17:05:03 +0200248
249/**
250 * @brief Fully validate a data tree.
251 *
252 * @param[in,out] tree Data tree to recursively validate. May be changed by validation.
253 * @param[in] ctx libyang context. Can be NULL if @p tree is set.
254 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200255 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200256 * @return LY_SUCCESS on success.
257 * @return LY_ERR error on error.
258 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200259LY_ERR lyd_validate_all(struct lyd_node **tree, const struct ly_ctx *ctx, uint32_t val_opts, struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200260
261/**
Michal Vasko26e80012020-07-08 10:55:46 +0200262 * @brief Fully validate a data tree of a module.
Radek Krejci7931b192020-06-25 17:05:03 +0200263 *
264 * @param[in,out] tree Data tree to recursively validate. May be changed by validation.
Michal Vasko26e80012020-07-08 10:55:46 +0200265 * @param[in] module Module whose data (and schema restrictions) to validate.
Radek Krejci7931b192020-06-25 17:05:03 +0200266 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200267 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200268 * @return LY_SUCCESS on success.
269 * @return LY_ERR error on error.
270 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200271LY_ERR lyd_validate_module(struct lyd_node **tree, const struct lys_module *module, uint32_t val_opts, struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200272
273/**
274 * @brief Validate an RPC/action, notification, or RPC/action reply.
275 *
276 * @param[in,out] op_tree Operation tree with any parents. It can point to the operation itself or any of
277 * its parents, only the operation subtree is actually validated.
278 * @param[in] tree Tree to be used for validating references from the operation subtree.
279 * @param[in] op Operation to validate (@ref datavalidateop), the given @p op_tree must correspond to this value. Note that
280 * it isn't possible to detect the operation simply from the @p op_tree since RPC/action and their reply share the same
Michal Vasko8104fd42020-07-13 11:09:51 +0200281 * RPC/action data node and in case one of the input and output do not define any data node children, it is not possible
Radek Krejci7931b192020-06-25 17:05:03 +0200282 * to get know what is here given for validation and if it is really valid.
Michal Vasko8104fd42020-07-13 11:09:51 +0200283 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200284 * @return LY_SUCCESS on success.
285 * @return LY_ERR error on error.
286 */
Michal Vasko8104fd42020-07-13 11:09:51 +0200287LY_ERR lyd_validate_op(struct lyd_node *op_tree, const struct lyd_node *tree, LYD_VALIDATE_OP op, struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200288
289/** @} datatree */
290
291#ifdef __cplusplus
292}
293#endif
294
295#endif /* LY_PARSER_DATA_H_ */