blob: 747aa51a80c28dc8b4d36290a2ce1884868bebb3 [file] [log] [blame]
Radek Krejcid7e8a622018-10-29 15:54:55 +01001/**
Radek Krejci0935f412019-08-20 16:15:18 +02002 * @file plugins_exts.h
Radek Krejcid7e8a622018-10-29 15:54:55 +01003 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief libyang support for YANG extensions implementation.
5 *
Radek Krejci0935f412019-08-20 16:15:18 +02006 * Copyright (c) 2015 - 2019 CESNET, z.s.p.o.
Radek Krejcid7e8a622018-10-29 15:54:55 +01007 *
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
Radek Krejci0935f412019-08-20 16:15:18 +020015#ifndef LY_PLUGINS_EXTS_H_
16#define LY_PLUGINS_EXTS_H_
Radek Krejcid7e8a622018-10-29 15:54:55 +010017
Radek Krejci535ea9f2020-05-29 16:01:05 +020018#include "log.h"
Radek Krejci3e6632f2021-03-22 22:08:21 +010019#include "plugins.h"
tadeas-vintrlik2aa36b42021-11-03 13:07:34 +010020#include "tree_data.h"
Radek Krejci859a15a2021-03-05 20:56:59 +010021#include "tree_edit.h"
Radek Krejci0e59c312019-08-15 15:34:15 +020022#include "tree_schema.h"
Radek Krejci535ea9f2020-05-29 16:01:05 +020023
Radek Krejci5f9a3672021-03-05 21:35:22 +010024#include "plugins_exts_compile.h"
Radek Krejcif8d7f9a2021-03-10 14:32:36 +010025#include "plugins_exts_print.h"
Radek Krejci5f9a3672021-03-05 21:35:22 +010026
Radek Krejci535ea9f2020-05-29 16:01:05 +020027struct ly_ctx;
tadeas-vintrlik2aa36b42021-11-03 13:07:34 +010028struct ly_in;
Radek Krejci535ea9f2020-05-29 16:01:05 +020029struct lyd_node;
Radek Krejci0aa1f702021-04-01 16:16:19 +020030struct lysc_ext_substmt;
31struct lysp_ext_instance;
Radek Krejci0e59c312019-08-15 15:34:15 +020032
Radek Krejcid7e8a622018-10-29 15:54:55 +010033#ifdef __cplusplus
34extern "C" {
35#endif
36
37/**
Radek Krejci75104122021-04-01 15:37:45 +020038 * @page howtoPluginsExtensions Extension Plugins
39 *
40 * Note that the part of the libyang API here is available only by including a separated `<libyang/plugins_exts.h>` header
41 * file. Also note that the extension plugins API is versioned separately from libyang itself, so backward incompatible
42 * changes can come even without changing libyang major version.
43 *
44 * YANG extensions are very complex. Usually only its description specifies how it is supposed to behave, what are the
45 * allowed substatements, their cardinality or if the standard YANG statements placed inside the extension differs somehow
aPiecekb0445f22021-06-24 11:34:07 +020046 * in their meaning or behavior. libyang provides the Extension plugins API to implement such extensions and add its support
Radek Krejci75104122021-04-01 15:37:45 +020047 * into libyang itself. However we tried our best, the API is not (and it cannot be) so universal and complete to cover all
48 * possibilities. There are definitely use cases which cannot be simply implemented only with this API.
49 *
50 * libyang implements 3 important extensions: [NACM](https://tools.ietf.org/html/rfc8341), [Metadata](@ref howtoDataMetadata)
51 * and [yang-data](@ref howtoDataYangdata). Despite the core implementation in all three cases is done via extension plugin
52 * API, also other parts of the libyang code had to be extended to cover complete scope of the extensions.
53 *
54 * We believe, that the API is capable to allow implementation of very wide range of YANG extensions. However, if you see
55 * limitations for the particular YANG extension, don't hesitate to contact the project developers to discuss all the
56 * options, including updating the API.
57 *
58 * The plugin's functionality is provided to libyang via a set of callbacks specified as an array of ::lyplg_ext_record
59 * structures using the ::LYPLG_EXTENSIONS macro.
60 *
61 * The most important ::lyplg_ext.compile callback is responsible for processing the parsed extension instance. In this
62 * phase, the callback must validate all the substatements, their values or placement of the extension instance itself.
63 * If needed, the processed data can be stored in some form into the compiled schema representation of the extension
64 * instance. To make the compilation process as easy as possible, libyang provides several
65 * [helper functions](@ref pluginsExtensionsCompile) to handle the schema compilation context and to compile standard YANG
66 * statements in the same way the libyang does it internally.
67 *
68 * The data validation callback ::lyplg_ext.validate is used for additional validation of a data nodes that contains the
69 * connected extension instance directly (as a substatement) or indirectly in case of terminal nodes via their type (no
70 * matter if the extension instance is placed directly in the leaf's/leaf-list's type or in the type of the referenced
71 * typedef).
72 *
73 * The ::lyplg_ext.sprinter callback implement printing the compiled extension instance data when the schema (module) is
74 * being printed in the ::LYS_OUT_YANG_COMPILED (info) format. As for compile callback, there are also
75 * [helper functions](@ref pluginsExtensionsPrint) to access printer's context and to print standard YANG statements
76 * placed in the extension instance by libyang itself.
77 *
78 * The last callback, ::lyplg_ext.free, is supposed to free all the data allocated by the ::lyplg_ext.compile callback.
79 * To free the data created by helper function ::lys_compile_extension_instance(), the plugin can used
80 * ::lyplg_ext_instance_substatements_free().
81 *
82 * The plugin information contains also the plugin identifier (::lyplg_type.id). This string can serve to identify the
83 * specific plugin responsible to storing data value. In case the user can recognize the id string, it can access the
84 * plugin specific data with the appropriate knowledge of its structure.
85 *
86 * Logging information from an extension plugin is possible via ::lyplg_ext_log() function
87 */
88
89/**
90 * @defgroup pluginsExtensions Plugins: Extensions
91 *
92 * Structures and functions to for libyang plugins implementing specific YANG extensions defined in YANG modules. For more
93 * information, see @ref howtoPluginsTypes.
94 *
95 * This part of libyang API is available by including `<libyang/plugins_ext.h>` header file.
Radek Krejcid7e8a622018-10-29 15:54:55 +010096 *
97 * @{
98 */
99
100/**
Radek Krejci0935f412019-08-20 16:15:18 +0200101 * @brief Extensions API version
102 */
Michal Vasko8cc3f662022-03-29 11:25:51 +0200103#define LYPLG_EXT_API_VERSION 3
Radek Krejci0935f412019-08-20 16:15:18 +0200104
105/**
Radek Krejcia6f61e72021-03-24 21:00:19 +0100106 * @brief Macro to define plugin information in external plugins
107 *
108 * Use as follows:
109 * LYPLG_EXTENSIONS = {{<filled information of ::lyplg_ext_record>}, ..., {0}};
Radek Krejci0935f412019-08-20 16:15:18 +0200110 */
Radek Krejcia6f61e72021-03-24 21:00:19 +0100111#define LYPLG_EXTENSIONS \
112 uint32_t plugins_extensions_apiver__ = LYPLG_EXT_API_VERSION; \
113 const struct lyplg_ext_record plugins_extensions__[]
Radek Krejci0935f412019-08-20 16:15:18 +0200114
115/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200116 * @brief Free the extension instance's data compiled with ::lys_compile_extension_instance().
Radek Krejci1b2eef82021-02-17 11:17:27 +0100117 *
Radek Krejci75104122021-04-01 15:37:45 +0200118 * @param[in] ctx libyang context
Radek Krejci1b2eef82021-02-17 11:17:27 +0100119 * @param[in] substmts The sized array of extension instance's substatements. The whole array is freed except the storage
120 * places which are expected to be covered by the extension plugin.
Radek Krejci38d85362019-09-05 16:26:38 +0200121 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100122LIBYANG_API_DECL void lyplg_ext_instance_substatements_free(struct ly_ctx *ctx, struct lysc_ext_substmt *substmts);
Radek Krejci38d85362019-09-05 16:26:38 +0200123
124/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200125 * @brief Callback to compile extension from the lysp_ext_instance to the lysc_ext_instance. The later structure is generally prepared
126 * and only the extension specific data are supposed to be added (if any).
127 *
Radek Krejciadcf63d2021-02-09 10:21:18 +0100128 * The parsed generic statements can be processed by the callback on its own or the ::lys_compile_extension_instance
129 * function can be used to let the compilation to libyang following the standard rules for processing the YANG statements.
130 *
Radek Krejci0e59c312019-08-15 15:34:15 +0200131 * @param[in] cctx Current compile context.
132 * @param[in] p_ext Parsed extension instance data.
Michal Vaskoddd76592022-01-17 13:34:48 +0100133 * @param[in,out] c_ext Prepared compiled extension instance structure where an addition, extension-specific, data are
134 * supposed to be placed for later use (data validation or use of external tool).
Radek Krejci0e59c312019-08-15 15:34:15 +0200135 * @return LY_SUCCESS in case of success.
136 * @return LY_EVALID in case of non-conforming parsed data.
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100137 * @return LY_ENOT in case the extension instance is not supported and should be removed.
Radek Krejci0e59c312019-08-15 15:34:15 +0200138 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100139typedef LY_ERR (*lyplg_ext_compile_clb)(struct lysc_ctx *cctx, const struct lysp_ext_instance *p_ext,
140 struct lysc_ext_instance *c_ext);
Radek Krejci0e59c312019-08-15 15:34:15 +0200141
142/**
Michal Vaskoddd76592022-01-17 13:34:48 +0100143 * @brief Callback to print the compiled extension instance's private data in the INFO format.
144 *
145 * @param[in] ctx YANG printer context to provide output handler and other information for printing.
146 * @param[in] ext The compiled extension instance, mainly to access the extensions.
147 * @param[in,out] flag Flag to be shared with the caller regarding the opening brackets - 0 if the '{' not yet printed,
148 * 1 otherwise.
149 * @return LY_SUCCESS when everything was fine, other LY_ERR values in case of failure
150 */
151typedef LY_ERR (*lyplg_ext_schema_printer_clb)(struct lyspr_ctx *ctx, struct lysc_ext_instance *ext, ly_bool *flag);
152
153/**
154 * @brief Callback to free the extension-specific data created by its compilation.
Radek Krejci0e59c312019-08-15 15:34:15 +0200155 *
Radek Krejci38d85362019-09-05 16:26:38 +0200156 * @param[in] ctx libyang context.
Radek Krejci0e59c312019-08-15 15:34:15 +0200157 * @param[in,out] ext Compiled extension structure where the data to free are placed.
158 */
Radek Krejci0b013302021-03-29 15:22:32 +0200159typedef void (*lyplg_ext_free_clb)(struct ly_ctx *ctx, struct lysc_ext_instance *ext);
Radek Krejci0e59c312019-08-15 15:34:15 +0200160
161/**
Michal Vasko8cc3f662022-03-29 11:25:51 +0200162 * @brief Callback for getting a schema node for a new YANG instance data described by an extension instance.
163 * Needed only if the extension instance supports some nested standard YANG data.
Radek Krejci0e59c312019-08-15 15:34:15 +0200164 *
Michal Vaskoddd76592022-01-17 13:34:48 +0100165 * @param[in] ext Compiled extension instance.
Michal Vasko8cc3f662022-03-29 11:25:51 +0200166 * @param[in] parent Parsed parent data node. Set if @p sparent is NULL.
167 * @param[in] sparent Schema parent node. Set if @p parent is NULL.
168 * @param[in] prefix Element prefix, if any.
169 * @param[in] prefix_len Length of @p prefix.
170 * @param[in] format Format of @p prefix.
171 * @param[in] prefix_data Format-specific prefix data.
172 * @param[in] name Element name.
173 * @param[in] name_len Length of @p name.
174 * @param[out] snode Schema node to use for parsing the node.
Michal Vaskoddd76592022-01-17 13:34:48 +0100175 * @return LY_SUCCESS on success.
176 * @return LY_ENOT if the data are not described by @p ext.
177 * @return LY_ERR on error.
Radek Krejci0e59c312019-08-15 15:34:15 +0200178 */
Michal Vasko8cc3f662022-03-29 11:25:51 +0200179typedef LY_ERR (*lyplg_ext_data_snode_clb)(struct lysc_ext_instance *ext, const struct lyd_node *parent,
180 const struct lysc_node *sparent, const char *prefix, size_t prefix_len, LY_VALUE_FORMAT format, void *prefix_data,
181 const char *name, size_t name_len, const struct lysc_node **snode);
Radek Krejci0e59c312019-08-15 15:34:15 +0200182
183/**
Michal Vaskoddd76592022-01-17 13:34:48 +0100184 * @brief Callback for validating parsed YANG instance data described by an extension instance.
Radek Krejciadcf63d2021-02-09 10:21:18 +0100185 *
Michal Vaskoddd76592022-01-17 13:34:48 +0100186 * This callback is used only for nested data definition (with a standard YANG schema parent).
Radek Krejciadcf63d2021-02-09 10:21:18 +0100187 *
Michal Vaskoddd76592022-01-17 13:34:48 +0100188 * @param[in] ext Compiled extension instance.
Michal Vasko9af7cd42022-04-05 12:26:09 +0200189 * @param[in] sibling First sibling with schema node returned by ::lyplg_ext_data_snode_clb.
Michal Vaskoddd76592022-01-17 13:34:48 +0100190 * @param[in] val_opts Validation options, see @ref datavalidationoptions.
Michal Vaskof4c6f002022-04-01 09:12:22 +0200191 * @param[out] diff Optional diff with any changes made by the validation.
Michal Vaskoddd76592022-01-17 13:34:48 +0100192 * @return LY_SUCCESS on success.
193 * @return LY_ERR on error.
Radek Krejciadcf63d2021-02-09 10:21:18 +0100194 */
Michal Vaskof4c6f002022-04-01 09:12:22 +0200195typedef LY_ERR (*lyplg_ext_data_validate_clb)(struct lysc_ext_instance *ext, struct lyd_node *sibling, uint32_t val_opts,
196 struct lyd_node **diff);
tadeas-vintrlik2aa36b42021-11-03 13:07:34 +0100197
198/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200199 * @brief Extension plugin implementing various aspects of a YANG extension
200 */
Radek Krejcicc9e30f2021-03-29 12:45:08 +0200201struct lyplg_ext {
Michal Vaskoddd76592022-01-17 13:34:48 +0100202 const char *id; /**< plugin identification (mainly for distinguish incompatible versions
203 of the plugins for external tools) */
204 lyplg_ext_compile_clb compile; /**< callback to compile extension instance from the parsed data */
205 lyplg_ext_schema_printer_clb sprinter; /**< callback to print the compiled content (info format) of the extension
206 instance */
207 lyplg_ext_free_clb free; /**< free the extension-specific data created by its compilation */
tadeas-vintrlik2aa36b42021-11-03 13:07:34 +0100208
Michal Vasko8cc3f662022-03-29 11:25:51 +0200209 lyplg_ext_data_snode_clb snode; /**< callback to get schema node for nested YANG data */
Michal Vaskoddd76592022-01-17 13:34:48 +0100210 lyplg_ext_data_validate_clb validate; /**< callback to validate parsed data instances according to the extension
211 definition */
Radek Krejci0e59c312019-08-15 15:34:15 +0200212};
213
Radek Krejci3e6632f2021-03-22 22:08:21 +0100214struct lyplg_ext_record {
215 /* plugin identification */
216 const char *module; /**< name of the module where the extension is defined */
217 const char *revision; /**< optional module revision - if not specified, the plugin applies to any revision,
218 which is not an optimal approach due to a possible future revisions of the module.
219 Instead, there should be defined multiple items in the plugins list, each with the
220 different revision, but all with the same pointer to the plugin functions. The
221 only valid use case for the NULL revision is the case the module has no revision. */
tadeas-vintrlik2aa36b42021-11-03 13:07:34 +0100222 const char *name; /**< YANG name of the extension */
Radek Krejci3e6632f2021-03-22 22:08:21 +0100223
224 /* runtime data */
225 struct lyplg_ext plugin; /**< data to utilize plugin implementation */
226};
227
Michal Vasko61ad1ff2022-02-10 15:48:39 +0100228/**
229 * @brief Get specific run-time extension instance data from a callback set by ::ly_ctx_set_ext_data_clb().
230 *
231 * @param[in] ctx Context with the callback.
232 * @param[in] ext Compiled extension instance.
233 * @param[out] ext_data Provided extension instance data.
234 * @param[out] ext_data_free Whether the extension instance should free @p ext_data or not.
235 * @return LY_SUCCESS on success.
236 * @return LY_ERR on error.
237 */
Michal Vaskoddd76592022-01-17 13:34:48 +0100238LIBYANG_API_DECL LY_ERR lyplg_ext_get_data(const struct ly_ctx *ctx, const struct lysc_ext_instance *ext, void **ext_data,
239 ly_bool *ext_data_free);
240
241/**
242 * @brief Insert extension instance data into a parent.
243 *
244 * @param[in] parent Parent node to insert into.
245 * @param[in] first First top-level sibling node to insert.
246 * @return LY_SUCCESS on success.
247 * @return LY_ERR error on error.
248 */
249LIBYANG_API_DECL LY_ERR lyd_insert_ext(struct lyd_node *parent, struct lyd_node *first);
250
Radek Krejci0935f412019-08-20 16:15:18 +0200251/**
252 * @brief Provide a log message from an extension plugin.
253 *
254 * @param[in] ext Compiled extension structure providing generic information about the extension/plugin causing the message.
255 * @param[in] level Log message level (error, warning, etc.)
256 * @param[in] err_no Error type code.
257 * @param[in] path Path relevant to the message.
258 * @param[in] format Format string to print.
259 */
Jan Kundrátc53a7ec2021-12-09 16:01:19 +0100260LIBYANG_API_DECL void lyplg_ext_log(const struct lysc_ext_instance *ext, LY_LOG_LEVEL level, LY_ERR err_no, const char *path,
Radek Krejci0b013302021-03-29 15:22:32 +0200261 const char *format, ...);
Radek Krejci0935f412019-08-20 16:15:18 +0200262
Radek Krejci75104122021-04-01 15:37:45 +0200263/** @} pluginsExtensions */
Radek Krejcid7e8a622018-10-29 15:54:55 +0100264
265#ifdef __cplusplus
266}
267#endif
268
Radek Krejci0935f412019-08-20 16:15:18 +0200269#endif /* LY_PLUGINS_EXTS_H_ */