blob: f51171045cb5f56d118bccbd8dd7c3934b4d3c3c [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 Krejci0e59c312019-08-15 15:34:15 +020019#include "tree_schema.h"
Radek Krejci535ea9f2020-05-29 16:01:05 +020020#include "tree_schema_internal.h"
21
22struct ly_ctx;
23struct lyd_node;
Radek Krejci0e59c312019-08-15 15:34:15 +020024
Radek Krejcid7e8a622018-10-29 15:54:55 +010025#ifdef __cplusplus
26extern "C" {
27#endif
28
Radek Krejci0e59c312019-08-15 15:34:15 +020029
Radek Krejcid7e8a622018-10-29 15:54:55 +010030/**
31 * @defgroup extensions YANG Extensions
32 *
33 * @{
34 */
35
36/**
Radek Krejci0935f412019-08-20 16:15:18 +020037 * @brief Extensions API version
38 */
39#define LYEXT_API_VERSION 1
40
41/**
42 * @brief Macro to store version of extension plugins API in the plugins.
43 * It is matched when the plugin is being loaded by libyang.
44 */
45#define LYEXT_VERSION_CHECK int lyext_api_version = LYEXT_API_VERSION;
46
47/**
Radek Krejci0e59c312019-08-15 15:34:15 +020048 * @defgroup extensionscompile YANG Extensions - Compilation Helpers
49 * @ingroup extensions
50 * @brief Helper functions to compile (via lyext_clb_compile callback) statements inside the extension instance.
51 *
52 * NOTE: There is a lot of useful static functions in the tree_schema_compile.c which could be provided here. Since we don't want
53 * to have a large API with functions which will be never used, we provide here just the functions which are evidently needed.
54 * If you, as an extension plugin author, need to make some of the compile functions available, please contact libyang maintainers
55 * via the GITHUB issue tracker.
56 *
57 * @{
Radek Krejcid7e8a622018-10-29 15:54:55 +010058 */
Radek Krejcid7e8a622018-10-29 15:54:55 +010059
60/**
Radek Krejcid6b76452019-09-03 17:03:03 +020061 * @brief Possible cardinalities of the YANG statements.
62 *
63 * Used in extensions plugins to define cardinalities of the extension instance substatements.
64 */
65enum ly_stmt_cardinality {
66 LY_STMT_CARD_OPT, /* 0..1 */
67 LY_STMT_CARD_MAND, /* 1 */
68 LY_STMT_CARD_SOME, /* 1..n */
69 LY_STMT_CARD_ANY /* 0..n */
70};
71
72/**
73 * @brief Description of the extension instance substatements.
74 *
75 * Provided by extensions plugins to libyang's lyext_compile_stmts() to be able to correctly compile the content of extension instances.
Radek Krejci335332a2019-09-05 13:03:35 +020076 * Note that order of the defined records matters - just follow the values of enum ly_stmt and order the records from lower to higher values.
Radek Krejcid6b76452019-09-03 17:03:03 +020077 */
78struct lysc_ext_substmt {
79 enum ly_stmt stmt; /**< allowed substatement */
80 enum ly_stmt_cardinality cardinality; /**< cardinality of the substatement */
81 void *storage; /**< pointer to the storage of the compiled statement according to the specific
82 lysc_ext_substmt::stmt and lysc_ext_substmt::cardinality */
83};
84
85/**
86 * @brief Compile substatements of an extension instance.
Radek Krejci38d85362019-09-05 16:26:38 +020087 * TODO
Radek Krejcid6b76452019-09-03 17:03:03 +020088 */
89LY_ERR lys_compile_extension_instance(struct lysc_ctx *ctx, const struct lysp_ext_instance *ext, struct lysc_ext_substmt *substmts);
90
91/**
Radek Krejci38d85362019-09-05 16:26:38 +020092 * @brief Free the extension instance's data compiled with lys_compile_extension_instance().
93 * TODO
94 */
95void lysc_extension_instance_free(struct ly_ctx *ctx, struct lysc_ext_substmt *substmts);
96
97/**
Michal Vasko6f4cbb62020-02-28 11:15:47 +010098 * @brief Duplicate the compiled extension (definition) structure.
99 * TODO should this be in API? currently required for nacm_compile()
100 * Instead of duplicating memory, the reference counter in the @p orig is increased.
101 *
102 * @param[in] orig The extension structure to duplicate.
103 * @return The duplicated structure to use.
104 */
105struct lysc_ext *lysc_ext_dup(struct lysc_ext *orig);
106
107/**
Radek Krejci0e59c312019-08-15 15:34:15 +0200108 * @brief Update path in the compile context, which is used for logging where the compilation failed.
109 *
110 * @param[in] ctx Compile context with the path.
111 * @param[in] parent Parent of the current node to check difference of the node's module. The current module is taken from lysc_ctx::mod.
112 * @param[in] name Name of the node to update path with. If NULL, the last segment is removed. If the format is `{keyword}`, the following
113 * call updates the segment to the form `{keyword='name'}` (to remove this compound segment, 2 calls with NULL @p name must be used).
114 */
115void lysc_update_path(struct lysc_ctx *ctx, struct lysc_node *parent, const char *name);
116
117/** @} extensionscompile */
118
119/**
120 * @brief Callback to compile extension from the lysp_ext_instance to the lysc_ext_instance. The later structure is generally prepared
121 * and only the extension specific data are supposed to be added (if any).
122 *
123 * @param[in] cctx Current compile context.
124 * @param[in] p_ext Parsed extension instance data.
125 * @param[in,out] c_ext Prepared compiled extension instance structure where an addition, extension-specific, data are supposed to be placed
126 * for later use (data validation or use of external tool).
127 * @return LY_SUCCESS in case of success.
128 * @return LY_EVALID in case of non-conforming parsed data.
129 */
130typedef LY_ERR (*lyext_clb_compile)(struct lysc_ctx *cctx, const struct lysp_ext_instance *p_ext, struct lysc_ext_instance *c_ext);
131
132/**
133 * @brief Callback to free the extension specific data created by the lyext_clb_compile callback of the same extension plugin.
134 *
Radek Krejci38d85362019-09-05 16:26:38 +0200135 * @param[in] ctx libyang context.
Radek Krejci0e59c312019-08-15 15:34:15 +0200136 * @param[in,out] ext Compiled extension structure where the data to free are placed.
137 */
Radek Krejci38d85362019-09-05 16:26:38 +0200138typedef void (*lyext_clb_free)(struct ly_ctx *ctx, struct lysc_ext_instance *ext);
Radek Krejci0e59c312019-08-15 15:34:15 +0200139
140/**
141 * @brief Callback to decide if data instance is valid according to the schema.
142 *
143 * The callback is used only for the extension instances placed in the following parent statements
144 * (which is specified as lysc_ext_instance::parent_type):
145 * - LYEXT_PAR_NODE - @p node is instance of the schema node where the extension instance was specified.
146 * - LYEXT_PAR_TPDF - @p node is instance of the schema node with the value of the typedef's type where the extension instance was specified.
147 * - LYEXT_PAR_TYPE - @p node is instance of the schema node with the value of the type where the extension instance was specified.
148 * - LYEXT_PAR_TYPE_BIT - @p node is instance of the schema node with the value of the bit where the extension instance was specified.
149 * - LYEXT_PAR_TYPE_ENUM - @p node is instance of the schema node with the value of the enum where the extension instance was specified.
150 *
151 * @param[in] ext Extension instance to be checked.
152 * @param[in] node Data node, where the extension data are supposed to be placed.
153 *
154 * @return LY_SUCCESS on data validation success.
155 * @return LY_EVALID in case the validation fails.
156 */
157typedef LY_ERR (*lyext_clb_data_validation)(struct lysc_ext_instance *ext, struct lyd_node *node);
158
159/**
160 * @brief Extension plugin implementing various aspects of a YANG extension
161 */
162struct lyext_plugin {
163 const char *id; /**< Plugin identification (mainly for distinguish incompatible versions of the plugins for external tools) */
164 lyext_clb_compile compile; /**< Callback to compile extension instance from the parsed data */
165 lyext_clb_data_validation validate; /**< Callback to decide if data instance is valid according to the schema. */
166 /* TODO printers? (schema/data) */
167 lyext_clb_free free; /**< Free the extension instance specific data created by lyext_plugin::compile callback */
168};
169
Radek Krejci0935f412019-08-20 16:15:18 +0200170struct lyext_plugins_list {
171 const char *module; /**< name of the module where the extension is defined */
172 const char *revision; /**< optional module revision - if not specified, the plugin applies to any revision,
173 which is not an optimal approach due to a possible future revisions of the module.
174 Instead, there should be defined multiple items in the plugins list, each with the
175 different revision, but all with the same pointer to the plugin extension. The
176 only valid use case for the NULL revision is the case the module has no revision. */
177 const char *name; /**< name of the extension */
178 struct lyext_plugin *plugin; /**< plugin for the extension */
179};
180
181
182/**
183 * @brief Provide a log message from an extension plugin.
184 *
185 * @param[in] ext Compiled extension structure providing generic information about the extension/plugin causing the message.
186 * @param[in] level Log message level (error, warning, etc.)
187 * @param[in] err_no Error type code.
188 * @param[in] path Path relevant to the message.
189 * @param[in] format Format string to print.
190 */
191void lyext_log(const struct lysc_ext_instance *ext, LY_LOG_LEVEL level, LY_ERR err_no, const char *path, const char *format, ...);
192
Radek Krejci0e59c312019-08-15 15:34:15 +0200193/** @} extensions */
Radek Krejcid7e8a622018-10-29 15:54:55 +0100194
195#ifdef __cplusplus
196}
197#endif
198
Radek Krejci0935f412019-08-20 16:15:18 +0200199#endif /* LY_PLUGINS_EXTS_H_ */