blob: 2da8b4deaf5412531f9261ab37c803060000d534 [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"
Radek Krejci859a15a2021-03-05 20:56:59 +010020#include "tree_edit.h"
Radek Krejci0e59c312019-08-15 15:34:15 +020021#include "tree_schema.h"
Radek Krejci535ea9f2020-05-29 16:01:05 +020022
Radek Krejci5f9a3672021-03-05 21:35:22 +010023#include "plugins_exts_compile.h"
Radek Krejcif8d7f9a2021-03-10 14:32:36 +010024#include "plugins_exts_print.h"
Radek Krejci5f9a3672021-03-05 21:35:22 +010025
Radek Krejci535ea9f2020-05-29 16:01:05 +020026struct ly_ctx;
27struct lyd_node;
Radek Krejci77114102021-03-10 15:21:57 +010028struct lysc_ctx;
Radek Krejci0aa1f702021-04-01 16:16:19 +020029struct lysc_ext_instance;
30struct lysc_ext_substmt;
31struct lysp_ext_instance;
Radek Krejci77114102021-03-10 15:21:57 +010032struct lyspr_ctx;
Radek Krejci0e59c312019-08-15 15:34:15 +020033
Radek Krejcid7e8a622018-10-29 15:54:55 +010034#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
Radek Krejci75104122021-04-01 15:37:45 +020039 * @page howtoPluginsExtensions Extension Plugins
40 *
41 * Note that the part of the libyang API here is available only by including a separated `<libyang/plugins_exts.h>` header
42 * file. Also note that the extension plugins API is versioned separately from libyang itself, so backward incompatible
43 * changes can come even without changing libyang major version.
44 *
45 * YANG extensions are very complex. Usually only its description specifies how it is supposed to behave, what are the
46 * allowed substatements, their cardinality or if the standard YANG statements placed inside the extension differs somehow
47 * in their meaning or behavior. libyang provids the Extension plugins API to implement such extensions and add its support
48 * into libyang itself. However we tried our best, the API is not (and it cannot be) so universal and complete to cover all
49 * possibilities. There are definitely use cases which cannot be simply implemented only with this API.
50 *
51 * libyang implements 3 important extensions: [NACM](https://tools.ietf.org/html/rfc8341), [Metadata](@ref howtoDataMetadata)
52 * and [yang-data](@ref howtoDataYangdata). Despite the core implementation in all three cases is done via extension plugin
53 * API, also other parts of the libyang code had to be extended to cover complete scope of the extensions.
54 *
55 * We believe, that the API is capable to allow implementation of very wide range of YANG extensions. However, if you see
56 * limitations for the particular YANG extension, don't hesitate to contact the project developers to discuss all the
57 * options, including updating the API.
58 *
59 * The plugin's functionality is provided to libyang via a set of callbacks specified as an array of ::lyplg_ext_record
60 * structures using the ::LYPLG_EXTENSIONS macro.
61 *
62 * The most important ::lyplg_ext.compile callback is responsible for processing the parsed extension instance. In this
63 * phase, the callback must validate all the substatements, their values or placement of the extension instance itself.
64 * If needed, the processed data can be stored in some form into the compiled schema representation of the extension
65 * instance. To make the compilation process as easy as possible, libyang provides several
66 * [helper functions](@ref pluginsExtensionsCompile) to handle the schema compilation context and to compile standard YANG
67 * statements in the same way the libyang does it internally.
68 *
69 * The data validation callback ::lyplg_ext.validate is used for additional validation of a data nodes that contains the
70 * connected extension instance directly (as a substatement) or indirectly in case of terminal nodes via their type (no
71 * matter if the extension instance is placed directly in the leaf's/leaf-list's type or in the type of the referenced
72 * typedef).
73 *
74 * The ::lyplg_ext.sprinter callback implement printing the compiled extension instance data when the schema (module) is
75 * being printed in the ::LYS_OUT_YANG_COMPILED (info) format. As for compile callback, there are also
76 * [helper functions](@ref pluginsExtensionsPrint) to access printer's context and to print standard YANG statements
77 * placed in the extension instance by libyang itself.
78 *
79 * The last callback, ::lyplg_ext.free, is supposed to free all the data allocated by the ::lyplg_ext.compile callback.
80 * To free the data created by helper function ::lys_compile_extension_instance(), the plugin can used
81 * ::lyplg_ext_instance_substatements_free().
82 *
83 * The plugin information contains also the plugin identifier (::lyplg_type.id). This string can serve to identify the
84 * specific plugin responsible to storing data value. In case the user can recognize the id string, it can access the
85 * plugin specific data with the appropriate knowledge of its structure.
86 *
87 * Logging information from an extension plugin is possible via ::lyplg_ext_log() function
88 */
89
90/**
91 * @defgroup pluginsExtensions Plugins: Extensions
92 *
93 * Structures and functions to for libyang plugins implementing specific YANG extensions defined in YANG modules. For more
94 * information, see @ref howtoPluginsTypes.
95 *
96 * This part of libyang API is available by including `<libyang/plugins_ext.h>` header file.
Radek Krejcid7e8a622018-10-29 15:54:55 +010097 *
98 * @{
99 */
100
101/**
Radek Krejci0935f412019-08-20 16:15:18 +0200102 * @brief Extensions API version
103 */
Radek Krejcia6f61e72021-03-24 21:00:19 +0100104#define LYPLG_EXT_API_VERSION 1
Radek Krejci0935f412019-08-20 16:15:18 +0200105
106/**
Radek Krejcia6f61e72021-03-24 21:00:19 +0100107 * @brief Macro to define plugin information in external plugins
108 *
109 * Use as follows:
110 * LYPLG_EXTENSIONS = {{<filled information of ::lyplg_ext_record>}, ..., {0}};
Radek Krejci0935f412019-08-20 16:15:18 +0200111 */
Radek Krejcia6f61e72021-03-24 21:00:19 +0100112#define LYPLG_EXTENSIONS \
113 uint32_t plugins_extensions_apiver__ = LYPLG_EXT_API_VERSION; \
114 const struct lyplg_ext_record plugins_extensions__[]
Radek Krejci0935f412019-08-20 16:15:18 +0200115
116/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200117 * @brief Free the extension instance's data compiled with ::lys_compile_extension_instance().
Radek Krejci1b2eef82021-02-17 11:17:27 +0100118 *
Radek Krejci75104122021-04-01 15:37:45 +0200119 * @param[in] ctx libyang context
Radek Krejci1b2eef82021-02-17 11:17:27 +0100120 * @param[in] substmts The sized array of extension instance's substatements. The whole array is freed except the storage
121 * places which are expected to be covered by the extension plugin.
Radek Krejci38d85362019-09-05 16:26:38 +0200122 */
Radek Krejci0b013302021-03-29 15:22:32 +0200123void lyplg_ext_instance_substatements_free(struct ly_ctx *ctx, struct lysc_ext_substmt *substmts);
Radek Krejci38d85362019-09-05 16:26:38 +0200124
125/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200126 * @brief Callback to compile extension from the lysp_ext_instance to the lysc_ext_instance. The later structure is generally prepared
127 * and only the extension specific data are supposed to be added (if any).
128 *
Radek Krejciadcf63d2021-02-09 10:21:18 +0100129 * The parsed generic statements can be processed by the callback on its own or the ::lys_compile_extension_instance
130 * function can be used to let the compilation to libyang following the standard rules for processing the YANG statements.
131 *
Radek Krejci0e59c312019-08-15 15:34:15 +0200132 * @param[in] cctx Current compile context.
133 * @param[in] p_ext Parsed extension instance data.
134 * @param[in,out] c_ext Prepared compiled extension instance structure where an addition, extension-specific, data are supposed to be placed
135 * for later use (data validation or use of external tool).
136 * @return LY_SUCCESS in case of success.
137 * @return LY_EVALID in case of non-conforming parsed data.
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100138 * @return LY_ENOT in case the extension instance is not supported and should be removed.
Radek Krejci0e59c312019-08-15 15:34:15 +0200139 */
Radek Krejci0b013302021-03-29 15:22:32 +0200140typedef LY_ERR (*lyplg_ext_compile_clb)(struct lysc_ctx *cctx, const struct lysp_ext_instance *p_ext, struct lysc_ext_instance *c_ext);
Radek Krejci0e59c312019-08-15 15:34:15 +0200141
142/**
Radek Krejci0b013302021-03-29 15:22:32 +0200143 * @brief Callback to free the extension specific data created by the ::lyplg_ext_compile_clb callback of the same extension plugin.
Radek Krejci0e59c312019-08-15 15:34:15 +0200144 *
Radek Krejci38d85362019-09-05 16:26:38 +0200145 * @param[in] ctx libyang context.
Radek Krejci0e59c312019-08-15 15:34:15 +0200146 * @param[in,out] ext Compiled extension structure where the data to free are placed.
147 */
Radek Krejci0b013302021-03-29 15:22:32 +0200148typedef void (*lyplg_ext_free_clb)(struct ly_ctx *ctx, struct lysc_ext_instance *ext);
Radek Krejci0e59c312019-08-15 15:34:15 +0200149
150/**
151 * @brief Callback to decide if data instance is valid according to the schema.
152 *
Radek Krejci4f2e3e52021-03-30 14:20:28 +0200153 * The callback is used only for the extension instances placed in the data nodes or type (the
154 * ::lysc_ext_instance.parent_stmt value must be ::LY_STMT_IS_DATA_NODE() values or ::LY_STMT_TYPE):
Radek Krejci0e59c312019-08-15 15:34:15 +0200155 *
156 * @param[in] ext Extension instance to be checked.
Radek Krejci4f2e3e52021-03-30 14:20:28 +0200157 * @param[in] node Data node connected with the extension instance.
Radek Krejci0e59c312019-08-15 15:34:15 +0200158 *
159 * @return LY_SUCCESS on data validation success.
160 * @return LY_EVALID in case the validation fails.
161 */
Radek Krejci0b013302021-03-29 15:22:32 +0200162typedef LY_ERR (*lyplg_ext_data_validation_clb)(struct lysc_ext_instance *ext, struct lyd_node *node);
Radek Krejci0e59c312019-08-15 15:34:15 +0200163
164/**
Radek Krejciadcf63d2021-02-09 10:21:18 +0100165 * @brief Callback to print the compiled extension instance's private data in the INFO format.
166 *
167 * @param[in] ctx YANG printer context to provide output handler and other information for printing.
168 * @param[in] ext The compiled extension instance, mainly to access the extensions.
169 * @param[in, out] flag Flag to be shared with the caller regarding the opening brackets - 0 if the '{' not yet printed,
170 * 1 otherwise.
171 *
172 * @return LY_SUCCESS when everything was fine, other LY_ERR values in case of failure
173 */
Radek Krejci0b013302021-03-29 15:22:32 +0200174typedef LY_ERR (*lyplg_ext_schema_printer_clb)(struct lyspr_ctx *ctx, struct lysc_ext_instance *ext, ly_bool *flag);
Radek Krejciadcf63d2021-02-09 10:21:18 +0100175
176/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200177 * @brief Extension plugin implementing various aspects of a YANG extension
178 */
Radek Krejcicc9e30f2021-03-29 12:45:08 +0200179struct lyplg_ext {
Radek Krejci0b013302021-03-29 15:22:32 +0200180 const char *id; /**< Plugin identification (mainly for distinguish incompatible versions of the plugins for external tools) */
181 lyplg_ext_compile_clb compile; /**< Callback to compile extension instance from the parsed data */
182 lyplg_ext_data_validation_clb validate; /**< Callback to decide if data instance is valid according to the schema. */
183 lyplg_ext_schema_printer_clb sprinter; /**< Callback to print the compiled content (info format) of the extension instance */
184 lyplg_ext_free_clb free; /**< Free the extension instance specific data created by ::lyplg_ext.compile callback */
Radek Krejci0e59c312019-08-15 15:34:15 +0200185};
186
Radek Krejci3e6632f2021-03-22 22:08:21 +0100187struct lyplg_ext_record {
188 /* plugin identification */
189 const char *module; /**< name of the module where the extension is defined */
190 const char *revision; /**< optional module revision - if not specified, the plugin applies to any revision,
191 which is not an optimal approach due to a possible future revisions of the module.
192 Instead, there should be defined multiple items in the plugins list, each with the
193 different revision, but all with the same pointer to the plugin functions. The
194 only valid use case for the NULL revision is the case the module has no revision. */
195 const char *name; /**< name of the extension */
196
197 /* runtime data */
198 struct lyplg_ext plugin; /**< data to utilize plugin implementation */
199};
200
Radek Krejci0935f412019-08-20 16:15:18 +0200201/**
202 * @brief Provide a log message from an extension plugin.
203 *
204 * @param[in] ext Compiled extension structure providing generic information about the extension/plugin causing the message.
205 * @param[in] level Log message level (error, warning, etc.)
206 * @param[in] err_no Error type code.
207 * @param[in] path Path relevant to the message.
208 * @param[in] format Format string to print.
209 */
Radek Krejci0b013302021-03-29 15:22:32 +0200210void lyplg_ext_log(const struct lysc_ext_instance *ext, LY_LOG_LEVEL level, LY_ERR err_no, const char *path,
211 const char *format, ...);
Radek Krejci0935f412019-08-20 16:15:18 +0200212
Radek Krejci75104122021-04-01 15:37:45 +0200213/** @} pluginsExtensions */
Radek Krejcid7e8a622018-10-29 15:54:55 +0100214
215#ifdef __cplusplus
216}
217#endif
218
Radek Krejci0935f412019-08-20 16:15:18 +0200219#endif /* LY_PLUGINS_EXTS_H_ */