blob: fbb9a487f394805d10fa1bb5dde52c6b4204f34d [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/**
Radek Krejci8678fa42020-08-18 16:07:28 +020027 * @page howtoDataParsers Parsing Data
28 *
29 * Data parser allows to read instances from a specific format. libyang supports the following data formats:
30 *
31 * - XML
32 *
33 * Original data format used in NETCONF protocol. XML mapping is part of the YANG specification
34 * ([RFC 6020](http://tools.ietf.org/html/rfc6020)).
35 *
36 * - JSON
37 *
38 * The alternative data format available in RESTCONF protocol. Specification of JSON encoding of data modeled by YANG
39 * can be found in [RFC 7951](http://tools.ietf.org/html/rfc7951). The specification does not cover RPCs, actions and
40 * Notifications, so the representation of these data trees is proprietary and corresponds to the representation of these
41 * trees in XML.
42 *
43 * While the parsers themselves process the input data only syntactically, all the parser functions actually incorporate
44 * the [common validator](@ref howtoDataValidation) checking the input data semantically. Therefore, the parser functions
45 * accepts two groups of options - @ref dataparseroptions and @ref datavalidationoptions.
46 *
47 * In contrast to the schema parser, data parser also accepts empty input data if such an empty data tree is valid
48 * according to the schemas in the libyang context (i.e. there are no top level mandatory nodes).
49 *
50 * There are individual functions to process different types of the data instances trees:
51 * - ::lyd_parse_data() is intended for standard configuration data trees. According to the given
52 * [parser options](@ref dataparseroptions), the caller can further specify which kind of data tree is expected:
53 * - *complete :running datastore*: this is the default case, possibly with the use of (some of) the
54 * ::LYD_PARSE_STRICT, ::LYD_PARSE_OPAQ or ::LYD_VALIDATE_PRESENT options.
55 * - *complete configuration-only datastore* (such as :startup): in this case it is necessary to except all state data
56 * using ::LYD_PARSE_NO_STATE option.
57 * - *incomplete datastore*: there are situation when the data tree is incomplete or invalid by specification. For
58 * example the *:operational* datastore is not necessarily valid and results of the NETCONF's \<get\> or \<get-config\>
59 * oprations used with filters will be incomplete (and thus invalid). This can be allowed using ::LYD_PARSE_ONLY,
60 * the ::LYD_PARSE_NO_STATE should be used for the data returned by \<get-config\> operation.
Radek Krejcif16e2542021-02-17 15:39:23 +010061 * - ::lyd_parse_ext_data() is used for parsing configuration data trees defined inside extension instances, such as
62 * instances of yang-data extension specified in [RFC 8040](http://tools.ietf.org/html/rfc8040).
Michal Vaskoe0665742021-02-11 11:08:44 +010063 * - ::lyd_parse_op() is used for parsing RPCs/actions, replies, and notifications. Even NETCONF rpc, rpc-reply, and
Radek Krejcif16e2542021-02-17 15:39:23 +010064 * notification messages are supported.
65 * - ::lyd_parse_ext_op() is used for parsing RPCs/actions, replies, and notifications defined inside extension instances.
Radek Krejci8678fa42020-08-18 16:07:28 +020066 *
67 * Further information regarding the processing input instance data can be found on the following pages.
68 * - @subpage howtoDataValidation
69 * - @subpage howtoDataWD
70 *
71 * Functions List
72 * --------------
73 * - ::lyd_parse_data()
74 * - ::lyd_parse_data_mem()
75 * - ::lyd_parse_data_fd()
76 * - ::lyd_parse_data_path()
Radek Krejcif16e2542021-02-17 15:39:23 +010077 * - ::lyd_parse_ext_data()
Michal Vaskoe0665742021-02-11 11:08:44 +010078 * - ::lyd_parse_op()
Radek Krejcif16e2542021-02-17 15:39:23 +010079 * - ::lyd_parse_ext_op()
Radek Krejci8678fa42020-08-18 16:07:28 +020080 */
81
82/**
83 * @page howtoDataValidation Validating Data
84 *
85 * Data validation is performed implicitly to the input data processed by the [parser](@ref howtoDataParsers) and
86 * on demand via the lyd_validate_*() functions. The explicit validation process is supposed to be used when a (complex or
87 * simple) change is done on the data tree (via [data manipulation](@ref howtoDataManipulation) functions) and the data
88 * tree is expected to be valid (it doesn't make sense to validate modified result of filtered \<get\> operation).
89 *
90 * Similarly to the [data parser](@ref howtoDataParsers), there are individual functions to validate standard data tree
91 * (::lyd_validate_all()) and RPC, Action and Notification (::lyd_validate_op()). For the standard data trees, it is possible
92 * to modify the validation process by @ref datavalidationoptions. This way the state data can be prohibited
93 * (::LYD_VALIDATE_NO_STATE) and checking for mandatory nodes can be limited to the YANG modules with already present data
94 * instances (::LYD_VALIDATE_PRESENT). Validation of the standard data tree can be also limited with ::lyd_validate_module()
95 * function, which scopes only to a specified single YANG module.
96 *
97 * Since the operation data trees (RPCs, Actions or Notifications) can reference (leafref, instance-identifier, when/must
98 * expressions) data from a datastore tree, ::lyd_validate_op() may require additional data tree to be provided. This is a
99 * difference in contrast to the parsing process, when the data are loaded from an external source and invalid reference
100 * outside the operation tree is acceptable.
101 *
102 * Functions List
103 * --------------
104 * - ::lyd_validate_all()
105 * - ::lyd_validate_module()
106 * - ::lyd_validate_op()
107 */
108
109/**
Radek Krejci7931b192020-06-25 17:05:03 +0200110 * @addtogroup datatree
111 * @{
112 */
113
114/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200115 * @ingroup datatree
Radek Krejci7931b192020-06-25 17:05:03 +0200116 * @defgroup dataparseroptions Data parser options
117 *
118 * Various options to change the data tree parsers behavior.
119 *
120 * Default parser behavior:
121 * - complete input file is always parsed. In case of XML, even not well-formed XML document (multiple top-level
122 * elements) is parsed in its entirety,
123 * - parser silently ignores data without matching schema node definition,
124 * - list instances are checked whether they have all the keys, error is raised if not.
125 *
126 * Default parser validation behavior:
127 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
128 * and performs data validation according to all YANG rules, specifics follow,
129 * - list instances are expected to have all the keys (it is not checked),
130 * - instantiated (status) obsolete data print a warning,
131 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
132 * all the keys, leaf(-lists) correct values),
133 * - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised,
134 * - if-feature statements are evaluated,
135 * - invalid multiple data instances/data from several cases cause a validation error,
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200136 * - implicit nodes (NP containers and default values) are added.
Radek Krejci7931b192020-06-25 17:05:03 +0200137 * @{
138 */
139/* note: keep the lower 16bits free for use by LYD_VALIDATE_ flags. They are not supposed to be combined together,
140 * but since they are used (as a separate parameter) together in some functions, we want to keep them in a separated
141 * range to be able detect that the caller put wrong flags into the parser/validate options parameter. */
142#define LYD_PARSE_ONLY 0x010000 /**< Data will be only parsed and no validation will be performed. When statements
143 are kept unevaluated, union types may not be fully resolved, if-feature
144 statements are not checked, and default values are not added (only the ones
145 parsed are present). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100146#define LYD_PARSE_STRICT 0x020000 /**< Instead of silently ignoring data without schema definition raise an error.
Michal Vasko369f7a62021-02-01 08:59:36 +0100147 Do not combine with ::LYD_PARSE_OPAQ (except for ::LYD_LYB). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100148#define LYD_PARSE_OPAQ 0x040000 /**< Instead of silently ignoring data without definition, parse them into
Michal Vasko369f7a62021-02-01 08:59:36 +0100149 an opaq node. Do not combine with ::LYD_PARSE_STRICT (except for ::LYD_LYB). */
150#define LYD_PARSE_NO_STATE 0x080000 /**< Forbid state data in the parsed data. Usually used with ::LYD_VALIDATE_NO_STATE. */
Radek Krejci7931b192020-06-25 17:05:03 +0200151
Michal Vasko0f3377d2020-11-09 20:56:11 +0100152#define LYD_PARSE_LYB_MOD_UPDATE 0x100000 /**< Only for LYB format, allow parsing data printed using a specific module
Radek Krejci7931b192020-06-25 17:05:03 +0200153 revision to be loaded even with a module with the same name but newer
154 revision. */
Michal Vaskoafac7822020-10-20 14:22:26 +0200155
156#define LYD_PARSE_OPTS_MASK 0xFFFF0000 /**< Mask for all the LYD_PARSE_ options. */
157
Radek Krejci7931b192020-06-25 17:05:03 +0200158/** @} dataparseroptions */
159
Radek Krejci7931b192020-06-25 17:05:03 +0200160/**
Radek Krejci7931b192020-06-25 17:05:03 +0200161 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200162 * @defgroup datavalidationoptions Data validation options
Radek Krejci7931b192020-06-25 17:05:03 +0200163 *
164 * Various options to change data validation behaviour, both for the parser and separate validation.
165 *
166 * Default separate validation behavior:
167 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
168 * and performs data validation according to all YANG rules, specifics follow,
169 * - instantiated (status) obsolete data print a warning,
170 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
171 * all the keys, leaf(-lists) correct values),
172 * - when statements on existing nodes are evaluated. Depending on the previous when state (from previous validation
173 * or parsing), the node is silently auto-deleted if the state changed from true to false, otherwise a validation error
174 * is raised if it evaluates to false,
175 * - if-feature statements are evaluated,
176 * - data from several cases behave based on their previous state (from previous validation or parsing). If there existed
177 * already a case and another one was added, the previous one is silently auto-deleted. Otherwise (if data from 2 or
178 * more cases were created) a validation error is raised,
179 * - default values are added.
180 *
181 * @{
182 */
Michal Vasko369f7a62021-02-01 08:59:36 +0100183#define LYD_VALIDATE_NO_STATE 0x0001 /**< Consider state data not allowed and raise an error if they are found.
184 Also, no implicit state data are added. */
Michal Vaskoafac7822020-10-20 14:22:26 +0200185#define LYD_VALIDATE_PRESENT 0x0002 /**< Validate only modules whose data actually exist. */
186
187#define LYD_VALIDATE_OPTS_MASK 0x0000FFFF /**< Mask for all the LYD_VALIDATE_* options. */
Radek Krejci7931b192020-06-25 17:05:03 +0200188
189/** @} datavalidationoptions */
190
191/**
Radek Krejci7931b192020-06-25 17:05:03 +0200192 * @brief Parse (and validate) data from the input handler as a YANG data tree.
193 *
194 * @param[in] ctx Context to connect with the tree being built here.
Michal Vaskoe0665742021-02-11 11:08:44 +0100195 * @param[in] parent Optional parent to connect the parsed nodes to.
Radek Krejci7931b192020-06-25 17:05:03 +0200196 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
197 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
198 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
199 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100200 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree. If @p parent is set, set to NULL.
Radek Krejci7931b192020-06-25 17:05:03 +0200201 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200202 * @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 +0200203 */
Michal Vaskoe0665742021-02-11 11:08:44 +0100204LY_ERR lyd_parse_data(const struct ly_ctx *ctx, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
205 uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200206
207/**
208 * @brief Parse (and validate) input data as a YANG data tree.
209 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100210 * Wrapper around ::lyd_parse_data() hiding work with the input handler and some obscure options.
Radek Krejci7931b192020-06-25 17:05:03 +0200211 *
212 * @param[in] ctx Context to connect with the tree being built here.
213 * @param[in] data The input data in the specified @p format to parse (and validate).
214 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
215 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
216 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100217 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree
Radek Krejci7931b192020-06-25 17:05:03 +0200218 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200219 * @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 +0200220 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200221LY_ERR lyd_parse_data_mem(const struct ly_ctx *ctx, const char *data, LYD_FORMAT format, uint32_t parse_options,
222 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200223
224/**
225 * @brief Parse (and validate) input data as a YANG data tree.
226 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100227 * Wrapper around ::lyd_parse_data() hiding work with the input handler and some obscure options.
Radek Krejci7931b192020-06-25 17:05:03 +0200228 *
229 * @param[in] ctx Context to connect with the tree being built here.
Michal Vaskoe0665742021-02-11 11:08:44 +0100230 * @param[in] fd File descriptor of a regular file (e.g. sockets are not supported) containing the input data in the
231 * specified @p format to parse.
Radek Krejci7931b192020-06-25 17:05:03 +0200232 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
233 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
234 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100235 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree
Radek Krejci7931b192020-06-25 17:05:03 +0200236 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200237 * @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 +0200238 */
Michal Vaskoe0665742021-02-11 11:08:44 +0100239LY_ERR lyd_parse_data_fd(const struct ly_ctx *ctx, int fd, LYD_FORMAT format, uint32_t parse_options,
240 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200241
242/**
243 * @brief Parse (and validate) input data as a YANG data tree.
244 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100245 * Wrapper around ::lyd_parse_data() hiding work with the input handler and some obscure options.
Radek Krejci7931b192020-06-25 17:05:03 +0200246 *
247 * @param[in] ctx Context to connect with the tree being built here.
248 * @param[in] path Path to the file with the input data in the specified @p format to parse (and validate).
249 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
250 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
251 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
Michal Vaskoe0665742021-02-11 11:08:44 +0100252 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree
Radek Krejci7931b192020-06-25 17:05:03 +0200253 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200254 * @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 +0200255 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200256LY_ERR lyd_parse_data_path(const struct ly_ctx *ctx, const char *path, LYD_FORMAT format, uint32_t parse_options,
257 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200258
259/**
Radek Krejci75104122021-04-01 15:37:45 +0200260 * @brief Parse (and validate) data from the input handler as an extension data tree following the schema tree of the given
Radek Krejcif16e2542021-02-17 15:39:23 +0100261 * extension instance.
262 *
263 * Note that the data being parsed are limited only to the schema tree specified by the given extension, it does not allow
264 * to mix them with the standard data from any module.
265 *
Radek Krejci75104122021-04-01 15:37:45 +0200266 * Directly applicable to data defined as [yang-data](@ref howtoDataYangdata).
267 *
Radek Krejcif16e2542021-02-17 15:39:23 +0100268 * @param[in] ext Extension instance providing the specific schema tree to match with the data being parsed.
269 * @param[in] parent Optional parent to connect the parsed nodes to.
270 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
271 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
272 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
273 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
274 * @param[out] tree Full parsed data tree, note that NULL can be a valid tree. If @p parent is set, set to NULL.
275 * @return LY_SUCCESS in case of successful parsing (and validation).
276 * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
277 */
278LY_ERR lyd_parse_ext_data(const struct lysc_ext_instance *ext, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
279 uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree);
280
281/**
Michal Vaskoe0665742021-02-11 11:08:44 +0100282 * @ingroup datatree
283 * @defgroup datatype Data operation type
Radek Krejci7931b192020-06-25 17:05:03 +0200284 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100285 * Operation provided to ::lyd_validate_op() to validate.
286 *
287 * The operation cannot be determined automatically since RPC/action and a reply to it share the common top level node
288 * referencing the RPC/action schema node and may not have any input/output children to use for distinction.
289 *
290 * @{
Radek Krejci7931b192020-06-25 17:05:03 +0200291 */
Michal Vaskoe0665742021-02-11 11:08:44 +0100292enum lyd_type {
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100293 LYD_TYPE_DATA_YANG = 0, /* generic YANG instance data */
294 LYD_TYPE_RPC_YANG, /* instance of a YANG RPC/action request with only "input" data children,
295 including all parents in case of an action */
296 LYD_TYPE_NOTIF_YANG, /* instance of a YANG notification , including all parents in case of a nested one */
297 LYD_TYPE_REPLY_YANG, /* instance of a YANG RPC/action reply with only "output" data children,
298 including all parents in case of an action */
299
300 LYD_TYPE_RPC_NETCONF, /* complete NETCONF RPC invocation as defined for
301 [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
302 [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
303 LYD_TYPE_NOTIF_NETCONF, /* complete NETCONF notification message as defined for
304 [notification](https://tools.ietf.org/html/rfc7950#section-7.16.2) */
305 LYD_TYPE_REPLY_NETCONF /* complete NETCONF RPC reply as defined for
306 [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
307 [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
Michal Vaskoe0665742021-02-11 11:08:44 +0100308};
309/** @} datatype */
Radek Krejci7931b192020-06-25 17:05:03 +0200310
311/**
Michal Vaskoe0665742021-02-11 11:08:44 +0100312 * @brief Parse YANG data into an operation data tree.
Radek Krejci7931b192020-06-25 17:05:03 +0200313 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100314 * At least one of @p parent, @p tree, or @p op must always be set.
Radek Krejci7931b192020-06-25 17:05:03 +0200315 *
Michal Vaskoe0665742021-02-11 11:08:44 +0100316 * Specific @p data_type values have different parameter meaning as follows:
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100317 * - ::LYD_TYPE_RPC_NETCONF:
Michal Vaskoe0665742021-02-11 11:08:44 +0100318 * - @p parent - must be NULL, the whole RPC is expected;
319 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
320 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
Michal Vasko299d5d12021-02-16 16:36:37 +0100321 * a separate opaque data tree, even if the function fails, this may be returned;
Michal Vaskoe0665742021-02-11 11:08:44 +0100322 * - @p op - must be provided, the RPC/action data tree itself will be returned here, pointing to the operation;
323 *
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100324 * - ::LYD_TYPE_NOTIF_NETCONF:
325 * - @p parent - must be NULL, the whole notification is expected;
326 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
327 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
Michal Vaskof4da8892021-02-19 09:15:18 +0100328 * a separate opaque data tree, even if the function fails, this may be returned;
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100329 * - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation;
330 *
331 * - ::LYD_TYPE_REPLY_NETCONF:
Michal Vaskoe0665742021-02-11 11:08:44 +0100332 * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
333 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
334 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
Michal Vaskof4da8892021-02-19 09:15:18 +0100335 * a separate opaque data tree, even if the function fails, this may be returned;
Michal Vasko1e4c68e2021-02-18 15:03:01 +0100336 * - @p op - must be NULL, the reply is appended to the RPC;
337 * Note that there are 3 kinds of NETCONF replies - ok, error, and data. Only data reply appends any nodes to the RPC.
Michal Vaskoe0665742021-02-11 11:08:44 +0100338 *
339 * @param[in] ctx libyang context.
340 * @param[in] parent Optional parent to connect the parsed nodes to.
341 * @param[in] in Input handle to read the input from.
342 * @param[in] format Expected format of the data in @p in.
343 * @param[in] data_type Expected operation to parse (@ref datatype).
344 * @param[out] tree Optional full parsed data tree. If @p parent is set, set to NULL.
345 * @param[out] op Optional parsed operation node.
346 * @return LY_ERR value.
Michal Vaskob7dba862021-02-18 16:10:02 +0100347 * @return LY_ENOT if @p data_type is a NETCONF message and the root XML element is not the expected one.
Radek Krejci7931b192020-06-25 17:05:03 +0200348 */
Michal Vaskoe0665742021-02-11 11:08:44 +0100349LY_ERR lyd_parse_op(const struct ly_ctx *ctx, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
350 enum lyd_type data_type, struct lyd_node **tree, struct lyd_node **op);
Radek Krejci7931b192020-06-25 17:05:03 +0200351
352/**
Radek Krejci75104122021-04-01 15:37:45 +0200353 * @brief Parse extension data into an operation data tree following only the specification from the given extension instance.
354 *
355 * Directly applicable to data defined as [yang-data](@ref howtoDataYangdata).
Radek Krejcif16e2542021-02-17 15:39:23 +0100356 *
357 * At least one of @p parent, @p tree, or @p op must always be set.
358 *
359 * Specific @p data_type values have different parameter meaning as follows:
360 * - ::LYD_TYPE_RPC_NETCONF:
361 * - @p parent - must be NULL, the whole RPC is expected;
362 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
363 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
364 * a separate opaque data tree, even if the function fails, this may be returned;
365 * - @p op - must be provided, the RPC/action data tree itself will be returned here, pointing to the operation;
366 *
367 * - ::LYD_TYPE_NOTIF_NETCONF:
368 * - @p parent - must be NULL, the whole notification is expected;
369 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
370 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
371 * a separate opaque data tree, even if the function fails, this may be returned;
372 * - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation;
373 *
374 * - ::LYD_TYPE_REPLY_NETCONF:
375 * - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
376 * - @p format - must be ::LYD_XML, NETCONF supports only this format;
377 * - @p tree - must be provided, all the NETCONF-specific XML envelopes will be returned here as
378 * a separate opaque data tree, even if the function fails, this may be returned;
379 * - @p op - must be NULL, the reply is appended to the RPC;
380 * Note that there are 3 kinds of NETCONF replies - ok, error, and data. Only data reply appends any nodes to the RPC.
381 *
382 * @param[in] ext Extension instance providing the specific schema tree to match with the data being parsed.
383 * @param[in] parent Optional parent to connect the parsed nodes to.
384 * @param[in] in Input handle to read the input from.
385 * @param[in] format Expected format of the data in @p in.
386 * @param[in] data_type Expected operation to parse (@ref datatype).
387 * @param[out] tree Optional full parsed data tree. If @p parent is set, set to NULL.
388 * @param[out] op Optional parsed operation node.
389 * @return LY_ERR value.
390 * @return LY_ENOT if @p data_type is a NETCONF message and the root XML element is not the expected one.
391 */
392LY_ERR lyd_parse_ext_op(const struct lysc_ext_instance *ext, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
393 enum lyd_type data_type, struct lyd_node **tree, struct lyd_node **op);
394
395/**
Radek Krejci7931b192020-06-25 17:05:03 +0200396 * @brief Fully validate a data tree.
397 *
398 * @param[in,out] tree Data tree to recursively validate. May be changed by validation.
399 * @param[in] ctx libyang context. Can be NULL if @p tree is set.
400 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200401 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200402 * @return LY_SUCCESS on success.
403 * @return LY_ERR error on error.
404 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200405LY_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 +0200406
407/**
Michal Vasko26e80012020-07-08 10:55:46 +0200408 * @brief Fully validate a data tree of a module.
Radek Krejci7931b192020-06-25 17:05:03 +0200409 *
410 * @param[in,out] tree Data tree to recursively validate. May be changed by validation.
Michal Vasko26e80012020-07-08 10:55:46 +0200411 * @param[in] module Module whose data (and schema restrictions) to validate.
Radek Krejci7931b192020-06-25 17:05:03 +0200412 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200413 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200414 * @return LY_SUCCESS on success.
415 * @return LY_ERR error on error.
416 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200417LY_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 +0200418
419/**
Michal Vaskoe0665742021-02-11 11:08:44 +0100420 * @brief Validate an RPC/action request, reply, or notification.
Radek Krejci7931b192020-06-25 17:05:03 +0200421 *
422 * @param[in,out] op_tree Operation tree with any parents. It can point to the operation itself or any of
423 * its parents, only the operation subtree is actually validated.
Michal Vaskoe0665742021-02-11 11:08:44 +0100424 * @param[in] dep_tree Tree to be used for validating references from the operation subtree.
425 * @param[in] data_type Operation type to validate (only YANG operations are accepted, @ref datatype).
Michal Vasko8104fd42020-07-13 11:09:51 +0200426 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200427 * @return LY_SUCCESS on success.
428 * @return LY_ERR error on error.
429 */
Michal Vaskoe0665742021-02-11 11:08:44 +0100430LY_ERR lyd_validate_op(struct lyd_node *op_tree, const struct lyd_node *dep_tree, enum lyd_type data_type,
431 struct lyd_node **diff);
Radek Krejci7931b192020-06-25 17:05:03 +0200432
433/** @} datatree */
434
435#ifdef __cplusplus
436}
437#endif
438
439#endif /* LY_PARSER_DATA_H_ */