blob: f521d7d93bdf7a967233325e4dfd32e5bf73df06 [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-vintrlikbf8aa6e2021-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-vintrlikbf8aa6e2021-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 Vaskoaac267d2022-01-17 13:34:48 +0100103#define LYPLG_EXT_API_VERSION 2
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átc6e39de2021-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 Vaskoaac267d2022-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 Vaskoaac267d2022-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 Vaskoaac267d2022-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 Vaskoaac267d2022-01-17 13:34:48 +0100162 * @brief Callback for parsing YANG instance data described by an extension instance.
Radek Krejci0e59c312019-08-15 15:34:15 +0200163 *
Michal Vaskoaac267d2022-01-17 13:34:48 +0100164 * This callback is used only for nested data definition (with a standard YANG schema parent).
165 * Note that the siblings parsed by this function and directly connected to @p parent must have the flag ::LYD_EXT set.
Radek Krejci0e59c312019-08-15 15:34:15 +0200166 *
Michal Vaskoaac267d2022-01-17 13:34:48 +0100167 * @param[in] in Input handler with the data to parse.
168 * @param[in] format Format if the data in @p in.
169 * @param[in] ext Compiled extension instance.
170 * @param[in,out] parent Data parent to append to.
171 * @param[in] parse_opts Parse options, see @ref dataparseroptions. They will always include ::LYD_PARSE_ONLY.
172 * @return LY_SUCCESS on success.
173 * @return LY_ENOT if the data are not described by @p ext.
174 * @return LY_ERR on error.
Radek Krejci0e59c312019-08-15 15:34:15 +0200175 */
Michal Vaskoaac267d2022-01-17 13:34:48 +0100176typedef LY_ERR (*lyplg_ext_data_parse_clb)(struct ly_in *in, LYD_FORMAT format, struct lysc_ext_instance *ext,
177 struct lyd_node *parent, uint32_t parse_opts);
Radek Krejci0e59c312019-08-15 15:34:15 +0200178
179/**
Michal Vaskoaac267d2022-01-17 13:34:48 +0100180 * @brief Callback for validating parsed YANG instance data described by an extension instance.
Radek Krejciadcf63d2021-02-09 10:21:18 +0100181 *
Michal Vaskoaac267d2022-01-17 13:34:48 +0100182 * This callback is used only for nested data definition (with a standard YANG schema parent).
Radek Krejciadcf63d2021-02-09 10:21:18 +0100183 *
Michal Vaskoaac267d2022-01-17 13:34:48 +0100184 * @param[in] ext Compiled extension instance.
185 * @param[in] sibling First sibling parsed by ::lyplg_ext_data_parse_clb.
186 * @param[in] val_opts Validation options, see @ref datavalidationoptions.
187 * @return LY_SUCCESS on success.
188 * @return LY_ERR on error.
Radek Krejciadcf63d2021-02-09 10:21:18 +0100189 */
Michal Vaskoaac267d2022-01-17 13:34:48 +0100190typedef LY_ERR (*lyplg_ext_data_validate_clb)(struct lysc_ext_instance *ext, struct lyd_node *sibling, uint32_t val_opts);
tadeas-vintrlikbf8aa6e2021-11-03 13:07:34 +0100191
192/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200193 * @brief Extension plugin implementing various aspects of a YANG extension
194 */
Radek Krejcicc9e30f2021-03-29 12:45:08 +0200195struct lyplg_ext {
Michal Vaskoaac267d2022-01-17 13:34:48 +0100196 const char *id; /**< plugin identification (mainly for distinguish incompatible versions
197 of the plugins for external tools) */
198 lyplg_ext_compile_clb compile; /**< callback to compile extension instance from the parsed data */
199 lyplg_ext_schema_printer_clb sprinter; /**< callback to print the compiled content (info format) of the extension
200 instance */
201 lyplg_ext_free_clb free; /**< free the extension-specific data created by its compilation */
tadeas-vintrlikbf8aa6e2021-11-03 13:07:34 +0100202
Michal Vaskoaac267d2022-01-17 13:34:48 +0100203 lyplg_ext_data_parse_clb parse; /**< callback to parse data instance according to the extension definition */
204 lyplg_ext_data_validate_clb validate; /**< callback to validate parsed data instances according to the extension
205 definition */
Radek Krejci0e59c312019-08-15 15:34:15 +0200206};
207
Radek Krejci3e6632f2021-03-22 22:08:21 +0100208struct lyplg_ext_record {
209 /* plugin identification */
210 const char *module; /**< name of the module where the extension is defined */
211 const char *revision; /**< optional module revision - if not specified, the plugin applies to any revision,
212 which is not an optimal approach due to a possible future revisions of the module.
213 Instead, there should be defined multiple items in the plugins list, each with the
214 different revision, but all with the same pointer to the plugin functions. The
215 only valid use case for the NULL revision is the case the module has no revision. */
tadeas-vintrlikbf8aa6e2021-11-03 13:07:34 +0100216 const char *name; /**< YANG name of the extension */
Radek Krejci3e6632f2021-03-22 22:08:21 +0100217
218 /* runtime data */
219 struct lyplg_ext plugin; /**< data to utilize plugin implementation */
220};
221
Michal Vaskoc08b9d22022-02-10 15:48:39 +0100222/**
223 * @brief Get specific run-time extension instance data from a callback set by ::ly_ctx_set_ext_data_clb().
224 *
225 * @param[in] ctx Context with the callback.
226 * @param[in] ext Compiled extension instance.
227 * @param[out] ext_data Provided extension instance data.
228 * @param[out] ext_data_free Whether the extension instance should free @p ext_data or not.
229 * @return LY_SUCCESS on success.
230 * @return LY_ERR on error.
231 */
Michal Vaskoaac267d2022-01-17 13:34:48 +0100232LIBYANG_API_DECL LY_ERR lyplg_ext_get_data(const struct ly_ctx *ctx, const struct lysc_ext_instance *ext, void **ext_data,
233 ly_bool *ext_data_free);
234
235/**
236 * @brief Insert extension instance data into a parent.
237 *
238 * @param[in] parent Parent node to insert into.
239 * @param[in] first First top-level sibling node to insert.
240 * @return LY_SUCCESS on success.
241 * @return LY_ERR error on error.
242 */
243LIBYANG_API_DECL LY_ERR lyd_insert_ext(struct lyd_node *parent, struct lyd_node *first);
244
Radek Krejci0935f412019-08-20 16:15:18 +0200245/**
246 * @brief Provide a log message from an extension plugin.
247 *
248 * @param[in] ext Compiled extension structure providing generic information about the extension/plugin causing the message.
249 * @param[in] level Log message level (error, warning, etc.)
250 * @param[in] err_no Error type code.
251 * @param[in] path Path relevant to the message.
252 * @param[in] format Format string to print.
253 */
Jan Kundrátc6e39de2021-12-09 16:01:19 +0100254LIBYANG_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 +0200255 const char *format, ...);
Radek Krejci0935f412019-08-20 16:15:18 +0200256
Radek Krejci75104122021-04-01 15:37:45 +0200257/** @} pluginsExtensions */
Radek Krejcid7e8a622018-10-29 15:54:55 +0100258
259#ifdef __cplusplus
260}
261#endif
262
Radek Krejci0935f412019-08-20 16:15:18 +0200263#endif /* LY_PLUGINS_EXTS_H_ */