blob: 02175d4d518008fa8a421efef6c8a9870b66ca1f [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.
61 * - ::lyd_parse_rpc() is used for parsing RPCs/Actions, optionally including the RPC envelopes known from the NETCONF
62 * protocol.
63 * - ::lyd_parse_reply() processes reply to a previous RPC/Action, which must be provided.
64 * - ::lyd_parse_notif() is able to process complete Notification message.
65 *
66 * Further information regarding the processing input instance data can be found on the following pages.
67 * - @subpage howtoDataValidation
68 * - @subpage howtoDataWD
69 *
70 * Functions List
71 * --------------
72 * - ::lyd_parse_data()
73 * - ::lyd_parse_data_mem()
74 * - ::lyd_parse_data_fd()
75 * - ::lyd_parse_data_path()
76 * - ::lyd_parse_rpc()
77 * - ::lyd_parse_reply()
78 * - ::lyd_parse_notif()
79 */
80
81/**
82 * @page howtoDataValidation Validating Data
83 *
84 * Data validation is performed implicitly to the input data processed by the [parser](@ref howtoDataParsers) and
85 * on demand via the lyd_validate_*() functions. The explicit validation process is supposed to be used when a (complex or
86 * simple) change is done on the data tree (via [data manipulation](@ref howtoDataManipulation) functions) and the data
87 * tree is expected to be valid (it doesn't make sense to validate modified result of filtered \<get\> operation).
88 *
89 * Similarly to the [data parser](@ref howtoDataParsers), there are individual functions to validate standard data tree
90 * (::lyd_validate_all()) and RPC, Action and Notification (::lyd_validate_op()). For the standard data trees, it is possible
91 * to modify the validation process by @ref datavalidationoptions. This way the state data can be prohibited
92 * (::LYD_VALIDATE_NO_STATE) and checking for mandatory nodes can be limited to the YANG modules with already present data
93 * instances (::LYD_VALIDATE_PRESENT). Validation of the standard data tree can be also limited with ::lyd_validate_module()
94 * function, which scopes only to a specified single YANG module.
95 *
96 * Since the operation data trees (RPCs, Actions or Notifications) can reference (leafref, instance-identifier, when/must
97 * expressions) data from a datastore tree, ::lyd_validate_op() may require additional data tree to be provided. This is a
98 * difference in contrast to the parsing process, when the data are loaded from an external source and invalid reference
99 * outside the operation tree is acceptable.
100 *
101 * Functions List
102 * --------------
103 * - ::lyd_validate_all()
104 * - ::lyd_validate_module()
105 * - ::lyd_validate_op()
106 */
107
108/**
Radek Krejci7931b192020-06-25 17:05:03 +0200109 * @addtogroup datatree
110 * @{
111 */
112
113/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200114 * @ingroup datatree
Radek Krejci7931b192020-06-25 17:05:03 +0200115 * @defgroup dataparseroptions Data parser options
116 *
117 * Various options to change the data tree parsers behavior.
118 *
119 * Default parser behavior:
120 * - complete input file is always parsed. In case of XML, even not well-formed XML document (multiple top-level
121 * elements) is parsed in its entirety,
122 * - parser silently ignores data without matching schema node definition,
123 * - list instances are checked whether they have all the keys, error is raised if not.
124 *
125 * Default parser validation behavior:
126 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
127 * and performs data validation according to all YANG rules, specifics follow,
128 * - list instances are expected to have all the keys (it is not checked),
129 * - instantiated (status) obsolete data print a warning,
130 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
131 * all the keys, leaf(-lists) correct values),
132 * - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised,
133 * - if-feature statements are evaluated,
134 * - invalid multiple data instances/data from several cases cause a validation error,
Michal Vaskoa6669ba2020-08-06 16:14:26 +0200135 * - implicit nodes (NP containers and default values) are added.
Radek Krejci7931b192020-06-25 17:05:03 +0200136 * @{
137 */
138/* note: keep the lower 16bits free for use by LYD_VALIDATE_ flags. They are not supposed to be combined together,
139 * but since they are used (as a separate parameter) together in some functions, we want to keep them in a separated
140 * range to be able detect that the caller put wrong flags into the parser/validate options parameter. */
141#define LYD_PARSE_ONLY 0x010000 /**< Data will be only parsed and no validation will be performed. When statements
142 are kept unevaluated, union types may not be fully resolved, if-feature
143 statements are not checked, and default values are not added (only the ones
144 parsed are present). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100145#define LYD_PARSE_STRICT 0x020000 /**< Instead of silently ignoring data without schema definition raise an error.
Radek Krejci8678fa42020-08-18 16:07:28 +0200146 Do not combine with #LYD_PARSE_OPAQ (except for ::LYD_LYB). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100147#define LYD_PARSE_OPAQ 0x040000 /**< Instead of silently ignoring data without definition, parse them into
Radek Krejci8678fa42020-08-18 16:07:28 +0200148 an opaq node. Do not combine with #LYD_PARSE_STRICT (except for ::LYD_LYB). */
Michal Vasko0f3377d2020-11-09 20:56:11 +0100149#define LYD_PARSE_NO_STATE 0x080000 /**< Forbid state data in the parsed data. */
Radek Krejci7931b192020-06-25 17:05:03 +0200150
Michal Vasko0f3377d2020-11-09 20:56:11 +0100151#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 +0200152 revision to be loaded even with a module with the same name but newer
153 revision. */
Michal Vaskoafac7822020-10-20 14:22:26 +0200154
155#define LYD_PARSE_OPTS_MASK 0xFFFF0000 /**< Mask for all the LYD_PARSE_ options. */
156
Radek Krejci7931b192020-06-25 17:05:03 +0200157/** @} dataparseroptions */
158
Radek Krejci7931b192020-06-25 17:05:03 +0200159/**
Radek Krejci7931b192020-06-25 17:05:03 +0200160 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200161 * @defgroup datavalidationoptions Data validation options
Radek Krejci7931b192020-06-25 17:05:03 +0200162 *
163 * Various options to change data validation behaviour, both for the parser and separate validation.
164 *
165 * Default separate validation behavior:
166 * - the provided data are expected to provide complete datastore content (both the configuration and state data)
167 * and performs data validation according to all YANG rules, specifics follow,
168 * - instantiated (status) obsolete data print a warning,
169 * - all types are fully resolved (leafref/instance-identifier targets, unions) and must be valid (lists have
170 * all the keys, leaf(-lists) correct values),
171 * - when statements on existing nodes are evaluated. Depending on the previous when state (from previous validation
172 * or parsing), the node is silently auto-deleted if the state changed from true to false, otherwise a validation error
173 * is raised if it evaluates to false,
174 * - if-feature statements are evaluated,
175 * - data from several cases behave based on their previous state (from previous validation or parsing). If there existed
176 * already a case and another one was added, the previous one is silently auto-deleted. Otherwise (if data from 2 or
177 * more cases were created) a validation error is raised,
178 * - default values are added.
179 *
180 * @{
181 */
Michal Vaskoafac7822020-10-20 14:22:26 +0200182#define LYD_VALIDATE_NO_STATE 0x0001 /**< Consider state data not allowed and raise an error if they are found. */
183#define LYD_VALIDATE_PRESENT 0x0002 /**< Validate only modules whose data actually exist. */
184
185#define LYD_VALIDATE_OPTS_MASK 0x0000FFFF /**< Mask for all the LYD_VALIDATE_* options. */
Radek Krejci7931b192020-06-25 17:05:03 +0200186
187/** @} datavalidationoptions */
188
189/**
Radek Krejci7931b192020-06-25 17:05:03 +0200190 * @ingroup datatree
Radek Krejci8678fa42020-08-18 16:07:28 +0200191 * @defgroup datavalidateop Operation to validate
Radek Krejci7931b192020-06-25 17:05:03 +0200192 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200193 * Operation provided to ::lyd_validate_op() to validate.
194 *
195 * The operation cannot be determined automatically since RPC/action and a reply to it share the common top level node
196 * referencing the RPC/action schema node and may not have any input/output children to use for distinction.
Radek Krejci576f8fa2020-10-26 21:23:58 +0100197 *
198 * @{
Radek Krejci7931b192020-06-25 17:05:03 +0200199 */
200typedef enum {
201 LYD_VALIDATE_OP_RPC = 1, /**< Validate RPC/action request (input parameters). */
202 LYD_VALIDATE_OP_REPLY, /**< Validate RPC/action reply (output parameters). */
203 LYD_VALIDATE_OP_NOTIF /**< Validate Notification operation. */
204} LYD_VALIDATE_OP;
205
206/** @} datavalidateop */
207
208/**
209 * @brief Parse (and validate) data from the input handler as a YANG data tree.
210 *
211 * @param[in] ctx Context to connect with the tree being built here.
212 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
213 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
214 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
215 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
216 * @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.
Radek Krejci8678fa42020-08-18 16:07:28 +0200217 * The returned data are expected to be freed using ::lyd_free_all().
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(const struct ly_ctx *ctx, struct ly_in *in, 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 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200227 * Wrapper around ::lyd_parse_data() hiding work with the input handler.
Radek Krejci7931b192020-06-25 17:05:03 +0200228 *
229 * @param[in] ctx Context to connect with the tree being built here.
230 * @param[in] data The input data in the specified @p format to parse (and validate).
231 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
232 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
233 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
234 * @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.
Radek Krejci8678fa42020-08-18 16:07:28 +0200235 * The returned data are expected to be freed using ::lyd_free_all().
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 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200239LY_ERR lyd_parse_data_mem(const struct ly_ctx *ctx, const char *data, 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 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200245 * Wrapper around ::lyd_parse_data() hiding work with the input handler.
Radek Krejci7931b192020-06-25 17:05:03 +0200246 *
247 * @param[in] ctx Context to connect with the tree being built here.
248 * @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).
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.
252 * @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.
Radek Krejci8678fa42020-08-18 16:07:28 +0200253 * The returned data are expected to be freed using ::lyd_free_all().
Radek Krejci7931b192020-06-25 17:05:03 +0200254 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200255 * @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 +0200256 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200257LY_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 +0200258 struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200259
260/**
261 * @brief Parse (and validate) input data as a YANG data tree.
262 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200263 * Wrapper around ::lyd_parse_data() hiding work with the input handler.
Radek Krejci7931b192020-06-25 17:05:03 +0200264 *
265 * @param[in] ctx Context to connect with the tree being built here.
266 * @param[in] path Path to the file with the input data in the specified @p format to parse (and validate).
267 * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
268 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
269 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
270 * @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.
Radek Krejci8678fa42020-08-18 16:07:28 +0200271 * The returned data are expected to be freed using ::lyd_free_all().
Radek Krejci7931b192020-06-25 17:05:03 +0200272 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200273 * @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 +0200274 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200275LY_ERR lyd_parse_data_path(const struct ly_ctx *ctx, const char *path, LYD_FORMAT format, uint32_t parse_options,
276 uint32_t validate_options, struct lyd_node **tree);
Radek Krejci7931b192020-06-25 17:05:03 +0200277
278/**
279 * @brief Parse (and validate) data from the input handler as a YANG RPC/action invocation.
280 *
281 * 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
Michal Vaskoafac7822020-10-20 14:22:26 +0200282 * data node (lyd_node_opaq) is created and all its XML attributes are parsed and inserted into the node. As a content of the envelope, an RPC data or
Radek Krejci7931b192020-06-25 17:05:03 +0200283 * \<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
284 * the \<rpc\> envelope. Inside the \<action\> envelope, only an action data are expected.
285 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200286 * Similarly, in the case of LYD_JSON @p format, the same envelopes in form of JSON objects are accepted. Nothing
287 * corresponding to the XML attributes is accepted in this case.
288 *
Radek Krejci7931b192020-06-25 17:05:03 +0200289 * @param[in] ctx Context to connect with the tree being built here.
290 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
291 * @param[in] format Format of the input data to be parsed.
Radek Krejci8678fa42020-08-18 16:07:28 +0200292 * @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().
Radek Krejci7931b192020-06-25 17:05:03 +0200293 * In contrast to YANG data tree, result of parsing RPC/action cannot be NULL until an error occurs.
294 * @param[out] op Optional pointer to the actual operation node inside the full action @p tree, useful only for action.
295 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200296 * @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 +0200297 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200298LY_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 +0200299 struct lyd_node **op);
Radek Krejci7931b192020-06-25 17:05:03 +0200300
301/**
302 * @brief Parse (and validate) data from the input handler as a YANG RPC/action reply.
303 *
304 * 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
305 * data node (lyd_node_opaq) is created and all its XML attributes are parsed and inserted into the node.
306 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200307 * Similarly, in the case of LYD_JSON @p format, the same envelopes in form of JSON objects are accepted. Nothing
308 * corresponding to the XML attributes is processed in this case.
309 *
Radek Krejci7931b192020-06-25 17:05:03 +0200310 * The reply data are strictly expected to be related to the provided RPC/action @p request.
311 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200312 * @param[in] request The RPC/action tree (result of ::lyd_parse_rpc()) of the request for the reply being parsed.
Radek Krejci7931b192020-06-25 17:05:03 +0200313 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
314 * @param[in] format Format of the input data to be parsed.
Radek Krejci8678fa42020-08-18 16:07:28 +0200315 * @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().
Radek Krejci7931b192020-06-25 17:05:03 +0200316 * 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 +0200317 * 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.
318 * @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
319 * and @p tree output variables must be provided.
Radek Krejci7931b192020-06-25 17:05:03 +0200320 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200321 * @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 +0200322 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200323LY_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 +0200324 struct lyd_node **op);
Radek Krejci7931b192020-06-25 17:05:03 +0200325
326/**
327 * @brief Parse XML string as YANG notification.
328 *
329 * In case o LYD_XML @p format, the \<notification\> envelope element in combination with the child \<eventTime\> element are accepted if present. They are
330 * [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.
331 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200332 * Similarly, in the case of LYD_JSON @p format, the same envelopes in form of JSON objects are accepted. Nothing
333 * corresponding to the XML attributes is accepted in this case.
334 *
Radek Krejci7931b192020-06-25 17:05:03 +0200335 * @param[in] ctx Context to connect with the tree being built here.
336 * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
337 * @param[in] format Format of the input data to be parsed.
Radek Krejci8678fa42020-08-18 16:07:28 +0200338 * @param[out] tree Resulting full Notification tree built from the input data. The returned data are expected to be freed using ::lyd_free_all().
Radek Krejci7931b192020-06-25 17:05:03 +0200339 * In contrast to YANG data tree, result of parsing Notification cannot be NULL until an error occurs.
340 * @param[out] ntf Optional pointer to the actual notification node inside the full Notification @p tree, useful for nested notifications.
341 * @return LY_SUCCESS in case of successful parsing (and validation).
Michal Vasko6d497662020-07-08 10:42:57 +0200342 * @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 +0200343 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200344LY_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 +0200345 struct lyd_node **ntf);
Radek Krejci7931b192020-06-25 17:05:03 +0200346
347/**
348 * @brief Fully validate a data tree.
349 *
350 * @param[in,out] tree Data tree to recursively validate. May be changed by validation.
351 * @param[in] ctx libyang context. Can be NULL if @p tree is set.
352 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200353 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200354 * @return LY_SUCCESS on success.
355 * @return LY_ERR error on error.
356 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200357LY_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 +0200358
359/**
Michal Vasko26e80012020-07-08 10:55:46 +0200360 * @brief Fully validate a data tree of a module.
Radek Krejci7931b192020-06-25 17:05:03 +0200361 *
362 * @param[in,out] tree Data tree to recursively validate. May be changed by validation.
Michal Vasko26e80012020-07-08 10:55:46 +0200363 * @param[in] module Module whose data (and schema restrictions) to validate.
Radek Krejci7931b192020-06-25 17:05:03 +0200364 * @param[in] val_opts Validation options (@ref datavalidationoptions).
Michal Vasko8104fd42020-07-13 11:09:51 +0200365 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200366 * @return LY_SUCCESS on success.
367 * @return LY_ERR error on error.
368 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200369LY_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 +0200370
371/**
372 * @brief Validate an RPC/action, notification, or RPC/action reply.
373 *
374 * @param[in,out] op_tree Operation tree with any parents. It can point to the operation itself or any of
375 * its parents, only the operation subtree is actually validated.
376 * @param[in] tree Tree to be used for validating references from the operation subtree.
377 * @param[in] op Operation to validate (@ref datavalidateop), the given @p op_tree must correspond to this value. Note that
378 * 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 +0200379 * 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 +0200380 * to get know what is here given for validation and if it is really valid.
Michal Vasko8104fd42020-07-13 11:09:51 +0200381 * @param[out] diff Optional diff with any changes made by the validation.
Radek Krejci7931b192020-06-25 17:05:03 +0200382 * @return LY_SUCCESS on success.
383 * @return LY_ERR error on error.
384 */
Michal Vasko8104fd42020-07-13 11:09:51 +0200385LY_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 +0200386
387/** @} datatree */
388
389#ifdef __cplusplus
390}
391#endif
392
393#endif /* LY_PARSER_DATA_H_ */