blob: 500068a4b6b7ff7f2c6d2faf39a7d8fa37cc9a40 [file] [log] [blame]
Radek Krejcif0e1ba52020-05-22 15:14:35 +02001/**
2 * @file parser_internal.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Internal structures and functions for libyang parsers
5 *
6 * Copyright (c) 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_INTERNAL_H_
16#define LY_PARSER_INTERNAL_H_
17
Michal Vaskoc8a230d2020-08-14 12:17:10 +020018#include "plugins_types.h"
Radek Krejcif0e1ba52020-05-22 15:14:35 +020019#include "tree_schema_internal.h"
20
Radek Krejci1798aae2020-07-14 13:26:06 +020021struct lyd_ctx;
Michal Vaskoafac7822020-10-20 14:22:26 +020022struct ly_in;
Michal Vaskoc8a230d2020-08-14 12:17:10 +020023
Radek Krejci1798aae2020-07-14 13:26:06 +020024/**
25 * @brief Callback for lyd_ctx to free the structure
26 *
27 * @param[in] ctx Data parser context to free.
28 */
29typedef void (*lyd_ctx_free_clb)(struct lyd_ctx *ctx);
30
31/**
32 * @brief Internal (common) context for YANG data parsers.
33 */
34struct lyd_ctx {
35 uint32_t parse_options; /**< various @ref dataparseroptions. */
36 uint32_t validate_options; /**< various @ref datavalidationoptions. */
37 uint32_t int_opts; /**< internal data parser options */
38 uint32_t path_len; /**< used bytes in the path buffer */
39#define LYD_PARSER_BUFSIZE 4078
40 char path[LYD_PARSER_BUFSIZE]; /**< buffer for the generated path */
41 struct ly_set unres_node_type; /**< set of nodes validated with LY_EINCOMPLETE result */
42 struct ly_set unres_meta_type; /**< set of metadata validated with LY_EINCOMPLETE result */
43 struct ly_set when_check; /**< set of nodes with "when" conditions */
44 struct lyd_node *op_node; /**< if an RPC/action/notification is being parsed, store the pointer to it */
45
46 /* callbacks */
Radek Krejci0bff0b12020-08-15 18:37:50 +020047 lyd_ctx_free_clb free; /**< destructor */
Radek Krejci1798aae2020-07-14 13:26:06 +020048
49 struct {
Radek Krejci0bff0b12020-08-15 18:37:50 +020050 const struct ly_ctx *ctx; /**< libyang context */
51 uint64_t line; /**< current line */
52 struct ly_in *in; /**< input structure */
53 } *data_ctx; /**< generic pointer supposed to map to and access (common part of) XML/JSON/... parser contexts */
Radek Krejci1798aae2020-07-14 13:26:06 +020054};
55
Radek Krejci7931b192020-06-25 17:05:03 +020056/**
Radek Krejci1798aae2020-07-14 13:26:06 +020057 * @brief Common part of the lyd_ctx_free_t callbacks.
58 */
59void lyd_ctx_free(struct lyd_ctx *);
60
61/**
Radek Krejcif0e1ba52020-05-22 15:14:35 +020062 * @brief Parse submodule from YANG data.
63 * @param[in,out] ctx Parser context.
64 * @param[in] ly_ctx Context of YANG schemas.
65 * @param[in] main_ctx Parser context of main module.
Michal Vasko63f3d842020-07-08 10:10:14 +020066 * @param[in] in Input structure.
Radek Krejcif0e1ba52020-05-22 15:14:35 +020067 * @param[out] submod Pointer to the parsed submodule structure.
68 * @return LY_ERR value - LY_SUCCESS, LY_EINVAL or LY_EVALID.
69 */
70LY_ERR yang_parse_submodule(struct lys_yang_parser_ctx **context, struct ly_ctx *ly_ctx, struct lys_parser_ctx *main_ctx,
Radek Krejci0f969882020-08-21 16:56:47 +020071 struct ly_in *in, struct lysp_submodule **submod);
Radek Krejcif0e1ba52020-05-22 15:14:35 +020072
73/**
74 * @brief Parse module from YANG data.
75 * @param[in] ctx Parser context.
Michal Vasko63f3d842020-07-08 10:10:14 +020076 * @param[in] in Input structure.
77 * @param[in,out] mod Prepared module structure where the parsed information, including the parsed
Radek Krejcif0e1ba52020-05-22 15:14:35 +020078 * module structure, will be filled in.
79 * @return LY_ERR value - LY_SUCCESS, LY_EINVAL or LY_EVALID.
80 */
Michal Vasko63f3d842020-07-08 10:10:14 +020081LY_ERR yang_parse_module(struct lys_yang_parser_ctx **context, struct ly_in *in, struct lys_module *mod);
Radek Krejcif0e1ba52020-05-22 15:14:35 +020082
83/**
84 * @brief Parse module from YIN data.
85 *
86 * @param[in,out] yin_ctx Context created during parsing, is used to finalize lysp_model after it's completly parsed.
Michal Vasko63f3d842020-07-08 10:10:14 +020087 * @param[in] in Input structure.
Radek Krejcif0e1ba52020-05-22 15:14:35 +020088 * @param[in,out] mod Prepared module structure where the parsed information, including the parsed
89 * module structure, will be filled in.
90 *
91 * @return LY_ERR values.
92 */
Michal Vasko63f3d842020-07-08 10:10:14 +020093LY_ERR yin_parse_module(struct lys_yin_parser_ctx **yin_ctx, struct ly_in *in, struct lys_module *mod);
Radek Krejcif0e1ba52020-05-22 15:14:35 +020094
95/**
96 * @brief Parse submodule from YIN data.
97 *
98 * @param[in,out] yin_ctx Context created during parsing, is used to finalize lysp_model after it's completly parsed.
99 * @param[in] ctx Libyang context.
100 * @param[in] main_ctx Parser context of main module.
Michal Vasko63f3d842020-07-08 10:10:14 +0200101 * @param[in] in Input structure.
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200102 * @param[in,out] submod Submodule structure where the parsed information, will be filled in.
103 * @return LY_ERR values.
104 */
105LY_ERR yin_parse_submodule(struct lys_yin_parser_ctx **yin_ctx, struct ly_ctx *ctx, struct lys_parser_ctx *main_ctx,
Radek Krejci0f969882020-08-21 16:56:47 +0200106 struct ly_in *in, struct lysp_submodule **submod);
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200107
Radek Krejci1798aae2020-07-14 13:26:06 +0200108/**
Michal Vaskoafac7822020-10-20 14:22:26 +0200109 * @brief Parse XML string as YANG data tree.
110 *
111 * @param[in] ctx libyang context
112 * @param[in] in Input structure.
113 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
114 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
115 * @param[out] tree_p Parsed data tree. Note that NULL can be a valid result.
116 * @param[out] lydctx_p Data parser context to finish validation.
117 * @return LY_ERR value.
118 */
119LY_ERR lyd_parse_xml_data(const struct ly_ctx *ctx, struct ly_in *in, uint32_t parse_options, uint32_t validate_options,
120 struct lyd_node **tree_p, struct lyd_ctx **lydctx_p);
121
122/**
123 * @brief Parse XML string as YANG RPC/action invocation.
124 *
125 * Optional \<rpc\> envelope element is accepted if present. It is [checked](https://tools.ietf.org/html/rfc6241#section-4.1) and all
126 * its XML attributes are parsed. As a content of the envelope, an RPC data or \<action\> envelope element is expected. The \<action\> envelope element is
127 * also [checked](https://tools.ietf.org/html/rfc7950#section-7.15.2) and then an action data is expected as a content of this envelope.
128 *
129 * @param[in] ctx libyang context.
130 * @param[in] in Input structure.
131 * @param[out] tree_p Parsed full RPC/action tree.
132 * @param[out] op_p Optional pointer to the actual operation. Useful mainly for action.
133 * @return LY_ERR value.
134 */
135LY_ERR lyd_parse_xml_rpc(const struct ly_ctx *ctx, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **op_p);
136
137/**
138 * @brief Parse XML string as YANG notification.
139 *
140 * Optional \<notification\> envelope element, if present, is [checked](https://tools.ietf.org/html/rfc5277#page-25)
141 * and parsed. Specifically, its namespace and the child \<eventTime\> element and its value.
142 *
143 * @param[in] ctx libyang context.
144 * @param[in] in Input structure.
145 * @param[out] tree_p Parsed full notification tree.
146 * @param[out] op_p Optional pointer to the actual notification. Useful mainly for nested notifications.
147 * @return LY_ERR value.
148 */
149LY_ERR lyd_parse_xml_notif(const struct ly_ctx *ctx, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **ntf_p);
150
151/**
152 * @brief Parse XML string as YANG RPC/action reply.
153 *
154 * Optional \<rpc-reply\> envelope element, if present, is [checked](https://tools.ietf.org/html/rfc6241#section-4.2)
155 * and all its XML attributes parsed.
156 *
157 * @param[in] request Data tree of the RPC/action request.
158 * @param[in] in Input structure.
159 * @param[out] tree_p Parsed full reply tree. It always includes duplicated operation and parents of the @p request.
160 * @param[out] op_p Optional pointer to the reply operation. Useful mainly for action.
161 * @return LY_ERR value.
162 */
163LY_ERR lyd_parse_xml_reply(const struct lyd_node *request, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **op_p);
164
165/**
166 * @brief Parse JSON string as YANG data tree.
167 *
168 * @param[in] ctx libyang context
169 * @param[in] in Input structure.
170 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
171 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
172 * @param[out] tree_p Parsed data tree. Note that NULL can be a valid result.
173 * @param[out] lydctx_p Data parser context to finish validation.
174 * @return LY_ERR value.
175 */
176LY_ERR lyd_parse_json_data(const struct ly_ctx *ctx, struct ly_in *in, uint32_t parse_options, uint32_t validate_options,
177 struct lyd_node **tree_p, struct lyd_ctx **lydctx_p);
178
179/**
180 * @brief Parse JSON string as YANG notification.
181 *
182 * Optional top-level "notification" envelope object, if present, is [checked](https://tools.ietf.org/html/rfc5277#page-25)
183 * and parsed. Specifically the child "eventTime" member and its value.
184 *
185 * @param[in] ctx libyang context.
186 * @param[in] in Input structure.
187 * @param[out] tree_p Parsed full notification tree.
188 * @param[out] ntf_p Optional pointer to the actual notification. Useful mainly for nested notifications.
189 * @return LY_ERR value.
190 */
191LY_ERR lyd_parse_json_notif(const struct ly_ctx *ctx, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **ntf_p);
192
193/**
194 * @brief Parse JSON string as YANG RPC/action invocation.
195 *
196 * Optional top-level "rpc" envelope object, if present is is [checked](https://tools.ietf.org/html/rfc6241#section-4.1) and the parser
197 * goes inside for the content, which is an RPC data or "action" envelope objects. The "action" envelope object is
198 * also [checked](https://tools.ietf.org/html/rfc7950#section-7.15.2) and then an action data is expected as a content of this envelope.
199 *
200 * @param[in] ctx libyang context.
201 * @param[in] in Input structure.
202 * @param[out] tree_p Parsed full RPC/action tree.
203 * @param[out] op_p Optional pointer to the actual operation. Useful mainly for action.
204 * @return LY_ERR value.
205 */
206LY_ERR lyd_parse_json_rpc(const struct ly_ctx *ctx, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **op_p);
207
208/**
209 * @brief Parse JSON string as YANG RPC/action reply.
210 *
211 * Optional "rpc-reply" envelope object, if present, is [checked](https://tools.ietf.org/html/rfc6241#section-4.2).
212 *
213 * @param[in] request Data tree of the RPC/action request.
214 * @param[in] in Input structure.
215 * @param[out] tree_p Parsed full reply tree. It always includes duplicated operation and parents of the @p request.
216 * @param[out] op_p Optional pointer to the reply operation. Useful mainly for action.
217 * @return LY_ERR value.
218 */
219LY_ERR lyd_parse_json_reply(const struct lyd_node *request, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **op_p);
220
221/**
222 * @brief Parse binary data as YANG data tree.
223 *
224 * @param[in] ctx libyang context
225 * @param[in] in Input structure.
226 * @param[in] parse_options Options for parser, see @ref dataparseroptions.
227 * @param[in] validate_options Options for the validation phase, see @ref datavalidationoptions.
228 * @param[out] tree_p Parsed data tree. Note that NULL can be a valid result.
229 * @param[out] lydctx_p Data parser context to finish validation.
230 * @return LY_ERR value.
231 */
232LY_ERR lyd_parse_lyb_data(const struct ly_ctx *ctx, struct ly_in *in, uint32_t parse_options, uint32_t validate_options,
233 struct lyd_node **tree_p, struct lyd_ctx **lydctx_p);
234
235/**
236 * @brief Parse binary data as YANG RPC/action invocation.
237 *
238 * @param[in] ctx libyang context.
239 * @param[in] in Input structure.
240 * @param[out] tree_p Parsed full RPC/action tree.
241 * @param[out] op_p Optional pointer to the actual operation. Useful mainly for action.
242 * @return LY_ERR value.
243 */
244LY_ERR lyd_parse_lyb_rpc(const struct ly_ctx *ctx, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **op_p);
245
246/**
247 * @brief Parse binary data as YANG notification.
248 *
249 * @param[in] ctx libyang context.
250 * @param[in] in Input structure.
251 * @param[out] tree_p Parsed full notification tree.
252 * @param[out] ntf_p Optional pointer to the actual notification. Useful mainly for nested notifications.
253 * @return LY_ERR value.
254 */
255LY_ERR lyd_parse_lyb_notif(const struct ly_ctx *ctx, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **ntf_p);
256
257/**
258 * @brief Parse binary data as YANG RPC/action reply.
259 *
260 * @param[in] request Data tree of the RPC/action request.
261 * @param[in] in Input structure.
262 * @param[out] tree_p Parsed full reply tree. It always includes duplicated operation and parents of the @p request.
263 * @param[out] op_p Optional pointer to the reply operation. Useful mainly for action.
264 * @return LY_ERR value.
265 */
266LY_ERR lyd_parse_lyb_reply(const struct lyd_node *request, struct ly_in *in, struct lyd_node **tree_p, struct lyd_node **op_p);
267
268/**
Radek Krejci1798aae2020-07-14 13:26:06 +0200269 * @brief Check that a data node representing the @p snode is suitable based on options.
270 *
271 * @param[in] lydctx Common data parsers context.
272 * @param[in] snode Schema node to check.
273 * @return LY_SUCCESS or LY_EVALID
274 */
275LY_ERR lyd_parser_check_schema(struct lyd_ctx *lydctx, const struct lysc_node *snode);
276
277/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200278 * @brief Wrapper around ::lyd_create_term() for data parsers.
Radek Krejci1798aae2020-07-14 13:26:06 +0200279 *
280 * @param[in] lydctx Data parser context.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200281 * @param[in] hints Data parser's hint for the value's type.
Radek Krejci1798aae2020-07-14 13:26:06 +0200282 */
283LY_ERR lyd_parser_create_term(struct lyd_ctx *lydctx, const struct lysc_node *schema, const char *value, size_t value_len,
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200284 ly_bool *dynamic, LY_PREFIX_FORMAT format, void *prefix_data, uint32_t hints, struct lyd_node **node);
Radek Krejci1798aae2020-07-14 13:26:06 +0200285
286/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200287 * @brief Wrapper around ::lyd_create_meta() for data parsers.
Radek Krejci1798aae2020-07-14 13:26:06 +0200288 *
289 * @param[in] lydctx Data parser context.
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200290 * @param[in] hints [Value hint](@ref lydvalhints) from the parser regarding the value type.
Radek Krejci1798aae2020-07-14 13:26:06 +0200291 */
Michal Vaskoc8a230d2020-08-14 12:17:10 +0200292LY_ERR lyd_parser_create_meta(struct lyd_ctx *lydctx, struct lyd_node *parent, struct lyd_meta **meta,
Radek Krejci0f969882020-08-21 16:56:47 +0200293 const struct lys_module *mod, const char *name, size_t name_len, const char *value,
Michal Vaskofeca4fb2020-10-05 08:58:40 +0200294 size_t value_len, ly_bool *dynamic, LY_PREFIX_FORMAT format, void *prefix_data, uint32_t hints);
Radek Krejci1798aae2020-07-14 13:26:06 +0200295
Radek Krejcif0e1ba52020-05-22 15:14:35 +0200296#endif /* LY_PARSER_INTERNAL_H_ */