blob: 2a4594f3b204c45c1473766762afceb74aeb5a00 [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 Krejci0aa1f702021-04-01 16:16:19 +020028struct lysc_ext_substmt;
29struct lysp_ext_instance;
Radek Krejci0e59c312019-08-15 15:34:15 +020030
Radek Krejcid7e8a622018-10-29 15:54:55 +010031#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
Radek Krejci75104122021-04-01 15:37:45 +020036 * @page howtoPluginsExtensions Extension Plugins
37 *
38 * Note that the part of the libyang API here is available only by including a separated `<libyang/plugins_exts.h>` header
39 * file. Also note that the extension plugins API is versioned separately from libyang itself, so backward incompatible
40 * changes can come even without changing libyang major version.
41 *
42 * YANG extensions are very complex. Usually only its description specifies how it is supposed to behave, what are the
43 * allowed substatements, their cardinality or if the standard YANG statements placed inside the extension differs somehow
aPiecekb0445f22021-06-24 11:34:07 +020044 * 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 +020045 * into libyang itself. However we tried our best, the API is not (and it cannot be) so universal and complete to cover all
46 * possibilities. There are definitely use cases which cannot be simply implemented only with this API.
47 *
48 * libyang implements 3 important extensions: [NACM](https://tools.ietf.org/html/rfc8341), [Metadata](@ref howtoDataMetadata)
49 * and [yang-data](@ref howtoDataYangdata). Despite the core implementation in all three cases is done via extension plugin
50 * API, also other parts of the libyang code had to be extended to cover complete scope of the extensions.
51 *
52 * We believe, that the API is capable to allow implementation of very wide range of YANG extensions. However, if you see
53 * limitations for the particular YANG extension, don't hesitate to contact the project developers to discuss all the
54 * options, including updating the API.
55 *
56 * The plugin's functionality is provided to libyang via a set of callbacks specified as an array of ::lyplg_ext_record
57 * structures using the ::LYPLG_EXTENSIONS macro.
58 *
59 * The most important ::lyplg_ext.compile callback is responsible for processing the parsed extension instance. In this
60 * phase, the callback must validate all the substatements, their values or placement of the extension instance itself.
61 * If needed, the processed data can be stored in some form into the compiled schema representation of the extension
62 * instance. To make the compilation process as easy as possible, libyang provides several
63 * [helper functions](@ref pluginsExtensionsCompile) to handle the schema compilation context and to compile standard YANG
64 * statements in the same way the libyang does it internally.
65 *
66 * The data validation callback ::lyplg_ext.validate is used for additional validation of a data nodes that contains the
67 * connected extension instance directly (as a substatement) or indirectly in case of terminal nodes via their type (no
68 * matter if the extension instance is placed directly in the leaf's/leaf-list's type or in the type of the referenced
69 * typedef).
70 *
71 * The ::lyplg_ext.sprinter callback implement printing the compiled extension instance data when the schema (module) is
72 * being printed in the ::LYS_OUT_YANG_COMPILED (info) format. As for compile callback, there are also
73 * [helper functions](@ref pluginsExtensionsPrint) to access printer's context and to print standard YANG statements
74 * placed in the extension instance by libyang itself.
75 *
76 * The last callback, ::lyplg_ext.free, is supposed to free all the data allocated by the ::lyplg_ext.compile callback.
77 * To free the data created by helper function ::lys_compile_extension_instance(), the plugin can used
78 * ::lyplg_ext_instance_substatements_free().
79 *
80 * The plugin information contains also the plugin identifier (::lyplg_type.id). This string can serve to identify the
81 * specific plugin responsible to storing data value. In case the user can recognize the id string, it can access the
82 * plugin specific data with the appropriate knowledge of its structure.
83 *
84 * Logging information from an extension plugin is possible via ::lyplg_ext_log() function
85 */
86
87/**
88 * @defgroup pluginsExtensions Plugins: Extensions
89 *
90 * Structures and functions to for libyang plugins implementing specific YANG extensions defined in YANG modules. For more
91 * information, see @ref howtoPluginsTypes.
92 *
93 * This part of libyang API is available by including `<libyang/plugins_ext.h>` header file.
Radek Krejcid7e8a622018-10-29 15:54:55 +010094 *
95 * @{
96 */
97
98/**
Radek Krejci0935f412019-08-20 16:15:18 +020099 * @brief Extensions API version
100 */
Radek Krejcia6f61e72021-03-24 21:00:19 +0100101#define LYPLG_EXT_API_VERSION 1
Radek Krejci0935f412019-08-20 16:15:18 +0200102
103/**
Radek Krejcia6f61e72021-03-24 21:00:19 +0100104 * @brief Macro to define plugin information in external plugins
105 *
106 * Use as follows:
107 * LYPLG_EXTENSIONS = {{<filled information of ::lyplg_ext_record>}, ..., {0}};
Radek Krejci0935f412019-08-20 16:15:18 +0200108 */
Radek Krejcia6f61e72021-03-24 21:00:19 +0100109#define LYPLG_EXTENSIONS \
110 uint32_t plugins_extensions_apiver__ = LYPLG_EXT_API_VERSION; \
111 const struct lyplg_ext_record plugins_extensions__[]
Radek Krejci0935f412019-08-20 16:15:18 +0200112
113/**
Radek Krejci8678fa42020-08-18 16:07:28 +0200114 * @brief Free the extension instance's data compiled with ::lys_compile_extension_instance().
Radek Krejci1b2eef82021-02-17 11:17:27 +0100115 *
Radek Krejci75104122021-04-01 15:37:45 +0200116 * @param[in] ctx libyang context
Radek Krejci1b2eef82021-02-17 11:17:27 +0100117 * @param[in] substmts The sized array of extension instance's substatements. The whole array is freed except the storage
118 * places which are expected to be covered by the extension plugin.
Radek Krejci38d85362019-09-05 16:26:38 +0200119 */
Jan Kundrátc6e39de2021-12-09 16:01:19 +0100120LIBYANG_API_DECL void lyplg_ext_instance_substatements_free(struct ly_ctx *ctx, struct lysc_ext_substmt *substmts);
Radek Krejci38d85362019-09-05 16:26:38 +0200121
122/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200123 * @brief Callback to compile extension from the lysp_ext_instance to the lysc_ext_instance. The later structure is generally prepared
124 * and only the extension specific data are supposed to be added (if any).
125 *
Radek Krejciadcf63d2021-02-09 10:21:18 +0100126 * The parsed generic statements can be processed by the callback on its own or the ::lys_compile_extension_instance
127 * function can be used to let the compilation to libyang following the standard rules for processing the YANG statements.
128 *
Radek Krejci0e59c312019-08-15 15:34:15 +0200129 * @param[in] cctx Current compile context.
130 * @param[in] p_ext Parsed extension instance data.
131 * @param[in,out] c_ext Prepared compiled extension instance structure where an addition, extension-specific, data are supposed to be placed
132 * for later use (data validation or use of external tool).
133 * @return LY_SUCCESS in case of success.
134 * @return LY_EVALID in case of non-conforming parsed data.
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100135 * @return LY_ENOT in case the extension instance is not supported and should be removed.
Radek Krejci0e59c312019-08-15 15:34:15 +0200136 */
Radek Krejci0b013302021-03-29 15:22:32 +0200137typedef 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 +0200138
139/**
Radek Krejci0b013302021-03-29 15:22:32 +0200140 * @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 +0200141 *
Radek Krejci38d85362019-09-05 16:26:38 +0200142 * @param[in] ctx libyang context.
Radek Krejci0e59c312019-08-15 15:34:15 +0200143 * @param[in,out] ext Compiled extension structure where the data to free are placed.
144 */
Radek Krejci0b013302021-03-29 15:22:32 +0200145typedef void (*lyplg_ext_free_clb)(struct ly_ctx *ctx, struct lysc_ext_instance *ext);
Radek Krejci0e59c312019-08-15 15:34:15 +0200146
147/**
148 * @brief Callback to decide if data instance is valid according to the schema.
149 *
Radek Krejci4f2e3e52021-03-30 14:20:28 +0200150 * The callback is used only for the extension instances placed in the data nodes or type (the
151 * ::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 +0200152 *
153 * @param[in] ext Extension instance to be checked.
Radek Krejci4f2e3e52021-03-30 14:20:28 +0200154 * @param[in] node Data node connected with the extension instance.
Radek Krejci0e59c312019-08-15 15:34:15 +0200155 *
156 * @return LY_SUCCESS on data validation success.
157 * @return LY_EVALID in case the validation fails.
158 */
Radek Krejci0b013302021-03-29 15:22:32 +0200159typedef LY_ERR (*lyplg_ext_data_validation_clb)(struct lysc_ext_instance *ext, struct lyd_node *node);
Radek Krejci0e59c312019-08-15 15:34:15 +0200160
161/**
Radek Krejciadcf63d2021-02-09 10:21:18 +0100162 * @brief Callback to print the compiled extension instance's private data in the INFO format.
163 *
164 * @param[in] ctx YANG printer context to provide output handler and other information for printing.
165 * @param[in] ext The compiled extension instance, mainly to access the extensions.
166 * @param[in, out] flag Flag to be shared with the caller regarding the opening brackets - 0 if the '{' not yet printed,
167 * 1 otherwise.
168 *
169 * @return LY_SUCCESS when everything was fine, other LY_ERR values in case of failure
170 */
Radek Krejci0b013302021-03-29 15:22:32 +0200171typedef 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 +0100172
173/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200174 * @brief Extension plugin implementing various aspects of a YANG extension
175 */
Radek Krejcicc9e30f2021-03-29 12:45:08 +0200176struct lyplg_ext {
Radek Krejci0b013302021-03-29 15:22:32 +0200177 const char *id; /**< Plugin identification (mainly for distinguish incompatible versions of the plugins for external tools) */
178 lyplg_ext_compile_clb compile; /**< Callback to compile extension instance from the parsed data */
179 lyplg_ext_data_validation_clb validate; /**< Callback to decide if data instance is valid according to the schema. */
180 lyplg_ext_schema_printer_clb sprinter; /**< Callback to print the compiled content (info format) of the extension instance */
181 lyplg_ext_free_clb free; /**< Free the extension instance specific data created by ::lyplg_ext.compile callback */
Radek Krejci0e59c312019-08-15 15:34:15 +0200182};
183
Radek Krejci3e6632f2021-03-22 22:08:21 +0100184struct lyplg_ext_record {
185 /* plugin identification */
186 const char *module; /**< name of the module where the extension is defined */
187 const char *revision; /**< optional module revision - if not specified, the plugin applies to any revision,
188 which is not an optimal approach due to a possible future revisions of the module.
189 Instead, there should be defined multiple items in the plugins list, each with the
190 different revision, but all with the same pointer to the plugin functions. The
191 only valid use case for the NULL revision is the case the module has no revision. */
192 const char *name; /**< name of the extension */
193
194 /* runtime data */
195 struct lyplg_ext plugin; /**< data to utilize plugin implementation */
196};
197
Radek Krejci0935f412019-08-20 16:15:18 +0200198/**
199 * @brief Provide a log message from an extension plugin.
200 *
201 * @param[in] ext Compiled extension structure providing generic information about the extension/plugin causing the message.
202 * @param[in] level Log message level (error, warning, etc.)
203 * @param[in] err_no Error type code.
204 * @param[in] path Path relevant to the message.
205 * @param[in] format Format string to print.
206 */
Jan Kundrátc6e39de2021-12-09 16:01:19 +0100207LIBYANG_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 +0200208 const char *format, ...);
Radek Krejci0935f412019-08-20 16:15:18 +0200209
Radek Krejci75104122021-04-01 15:37:45 +0200210/** @} pluginsExtensions */
Radek Krejcid7e8a622018-10-29 15:54:55 +0100211
212#ifdef __cplusplus
213}
214#endif
215
Radek Krejci0935f412019-08-20 16:15:18 +0200216#endif /* LY_PLUGINS_EXTS_H_ */