blob: f540bd447b648c87c86a60dd8c1b591e263067dd [file] [log] [blame]
Radek Krejci5aeea3a2018-09-05 13:29:36 +02001/**
2 * @file context.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief internal context structures and functions
5 *
Michal Vasko25d6ad02020-10-22 12:20:22 +02006 * Copyright (c) 2015 - 2020 CESNET, z.s.p.o.
Radek Krejci5aeea3a2018-09-05 13:29:36 +02007 *
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
15#ifndef LY_CONTEXT_H_
16#define LY_CONTEXT_H_
17
Radek Krejcie7b95092019-05-15 11:03:07 +020018#include <stdint.h>
19
Radek Krejci6caa6ab2018-10-24 10:04:48 +020020#include "log.h"
Radek Krejcif0e1ba52020-05-22 15:14:35 +020021#include "parser_schema.h"
Tadeáš Vintrlík390b2722021-04-07 13:52:45 +020022#include "tree_data.h"
Radek Krejci5aeea3a2018-09-05 13:29:36 +020023
Radek Krejci6caa6ab2018-10-24 10:04:48 +020024#ifdef __cplusplus
25extern "C" {
26#endif
27
Michal Vasko3a41dff2020-07-15 14:30:28 +020028struct lyd_node;
Radek Krejci77114102021-03-10 15:21:57 +010029struct lys_module;
Radek Krejcica376bd2020-06-11 16:04:06 +020030struct lysc_node;
31
Radek Krejci5aeea3a2018-09-05 13:29:36 +020032/**
Radek Krejci8678fa42020-08-18 16:07:28 +020033 * @page howtoContext Context
Radek Krejci52785a22019-09-11 12:57:26 +020034 *
Radek Krejci8678fa42020-08-18 16:07:28 +020035 * The context concept allows callers to work in environments with different sets of YANG modules.
Radek Krejci52785a22019-09-11 12:57:26 +020036 *
Radek Krejci8678fa42020-08-18 16:07:28 +020037 * The first step with libyang is to create a new context using ::ly_ctx_new(). It returns a handler used in the following work.
38 * Note that the context is supposed to provide a stable environment for work with the data. Therefore the caller should prepare
Michal Vasko5a5e7f82021-04-15 11:11:03 +020039 * a complete context and after starting working with the data, the context and its content should not change. If it does,
40 * in most cases it leads to the context being recompiled and any parsed data invalid. Despite the API not enforcing this
41 * approach, it may change in future versions in the form of a locking mechanism which would allow further
Radek Krejci8678fa42020-08-18 16:07:28 +020042 * optimization of data manipulation. Also note that modules cannot be removed from their context. If you need to change the set
43 * of the schema modules in the context, the recommended way is to create a new context. To remove the context, there is ::ly_ctx_destroy() function.
Radek Krejci52785a22019-09-11 12:57:26 +020044 *
Radek Krejci8678fa42020-08-18 16:07:28 +020045 * The context has [several options](@ref contextoptions) changing behavior when processing YANG modules being inserted. The
46 * specific behavior is mentioned below. All the options can be set as a parameter when the context is being created or later
47 * with ::ly_ctx_set_options().
48 *
49 * When creating a new context, another optional parameter is search_dir It provide directory where libyang
50 * will automatically search for YANG modules being imported or included. There is actually a set of search paths which can be later
51 * modified using ::ly_ctx_set_searchdir(), ::ly_ctx_unset_searchdir() and ::ly_ctx_unset_searchdir_last() functions. Before the values
52 * in the set are used, also the current working directory is (non-recursively) searched. For the case of the explicitly set
53 * search directories, they are searched recursively - all their subdirectories (and symlinks) are taken into account. Searching
54 * in the current working directory can be avoided with the context's ::LY_CTX_DISABLE_SEARCHDIR_CWD option.
Radek Krejci52785a22019-09-11 12:57:26 +020055 * Searching in all the context's search dirs (without removing them) can be avoided with the context's
Radek Krejci8678fa42020-08-18 16:07:28 +020056 * ::LY_CTX_DISABLE_SEARCHDIRS option (or via ::ly_ctx_set_options()). This automatic searching can be preceded
57 * by a custom module searching callback (::ly_module_imp_clb) set via ::ly_ctx_set_module_imp_clb(). The algorithm of
58 * searching in search dirs is also available via API as ::lys_search_localfile() function.
Radek Krejci52785a22019-09-11 12:57:26 +020059 *
Radek Krejci8678fa42020-08-18 16:07:28 +020060 * YANG modules are added into the context using [parser functions](@ref howtoSchemaParsers) - \b lys_parse*().
61 * Alternatively, also ::ly_ctx_load_module() can be used - in that case the ::ly_module_imp_clb or automatic
62 * search in search directories and in the current working directory is used, as described above. YANG submodules cannot be loaded
63 * or even validated directly, they are loaded always only as includes of YANG modules. Explicitly parsed/loaded modules are
64 * handled as implemented - libyang is able to instantiate data representing such a module. The modules loaded implicitly, are
65 * not implemented and serve only as a source of grouping or typedef definitions. Context can hold multiple revisions of the same
66 * YANG module, but only one of them can be implemented. Details about the difference between implemented and imported modules
Michal Vasko25d6ad02020-10-22 12:20:22 +020067 * can be found on @ref howtoSchema page. This behavior can be changed with the context's ::LY_CTX_ALL_IMPLEMENTED option, which
68 * causes that all the parsed modules, whether loaded explicitly or implicitly, are set to be implemented. Note, that as
69 * a consequence of this option, only a single revision of any module can be present in the context in this case. Also, a less
70 * crude option ::LY_CTX_REF_IMPLEMENTED can be used to implement only referenced modules that should also be implemented.
Radek Krejci52785a22019-09-11 12:57:26 +020071 *
72 * When loading/importing a module without revision, the latest revision of the required module is supposed to load.
73 * For a context, the first time the latest revision of a module is requested, it is properly searched for and loaded.
74 * However, when this module is requested (without revision) the second time, the one found previously is returned.
Radek Krejci8678fa42020-08-18 16:07:28 +020075 * This has the advantage of not searching for the module repeatedly but there is a drawback in case the content of search
76 * directories is updated and a later revision become available. However, to force libyang to re-search the
77 * latest revision, ::ly_ctx_reset_latests() can be used (note that it applies to all the modules in the context).
Radek Krejci52785a22019-09-11 12:57:26 +020078 *
Radek Krejci8678fa42020-08-18 16:07:28 +020079 * Context holds all the schema modules internally. To get a specific module, use ::ly_ctx_get_module() (or some of its
80 * variants). If you need to do something with all the modules in the context, it is advised to iterate over them using
81 * ::ly_ctx_get_module_iter(). Alternatively, the ::ly_ctx_get_yanglib_data() function can be used to get complex information about the schemas in the context
82 * in the form of data tree defined by <a href="https://tools.ietf.org/html/rfc7895">ietf-yang-library</a> module.
Radek Krejci52785a22019-09-11 12:57:26 +020083 *
Radek Krejci8678fa42020-08-18 16:07:28 +020084 * YANG data can be parsed by \b lyd_parse_*() functions. Note, that functions for schema have \b lys_
85 * prefix (or \b lysp_ for the parsed and \b lysc_ for the compiled schema - for details see @ref howtoSchema page) while
86 * functions for instance data have \b lyd_ prefix. Details about data formats or handling data without the appropriate
87 * YANG module in context can be found on @ref howtoData page.
Radek Krejci52785a22019-09-11 12:57:26 +020088 *
Radek Krejci8678fa42020-08-18 16:07:28 +020089 * Besides the YANG modules, context holds also [error information](@ref howtoErrors) and
90 * [database of strings](@ref howtoContextDict), both connected with the processed YANG modules and data.
91 *
92 * - @subpage howtoErrors
93 * - @subpage howtoContextDict
Radek Krejci52785a22019-09-11 12:57:26 +020094 *
95 * \note API for this group of functions is available in the [context module](@ref context).
96 *
97 * Functions List
98 * --------------
Radek Krejci8678fa42020-08-18 16:07:28 +020099 *
Radek Krejci52785a22019-09-11 12:57:26 +0200100 * - ::ly_ctx_new()
Radek Krejci8678fa42020-08-18 16:07:28 +0200101 * - ::ly_ctx_destroy()
102 *
Radek Krejci52785a22019-09-11 12:57:26 +0200103 * - ::ly_ctx_set_searchdir()
Radek Krejci52785a22019-09-11 12:57:26 +0200104 * - ::ly_ctx_get_searchdirs()
Radek Krejci8678fa42020-08-18 16:07:28 +0200105 * - ::ly_ctx_unset_searchdir()
106 * - ::ly_ctx_unset_searchdir_last()
107 *
108 * - ::ly_ctx_set_options()
109 * - ::ly_ctx_get_options()
110 * - ::ly_ctx_unset_options()
111 *
Radek Krejci52785a22019-09-11 12:57:26 +0200112 * - ::ly_ctx_set_module_imp_clb()
113 * - ::ly_ctx_get_module_imp_clb()
Radek Krejci8678fa42020-08-18 16:07:28 +0200114 *
Radek Krejci52785a22019-09-11 12:57:26 +0200115 * - ::ly_ctx_load_module()
Radek Krejci52785a22019-09-11 12:57:26 +0200116 * - ::ly_ctx_get_module_iter()
117 * - ::ly_ctx_get_module()
118 * - ::ly_ctx_get_module_ns()
119 * - ::ly_ctx_get_module_implemented()
120 * - ::ly_ctx_get_module_implemented_ns()
121 * - ::ly_ctx_get_module_latest()
122 * - ::ly_ctx_get_module_latest_ns()
Michal Vasko8dc31992021-02-22 10:30:47 +0100123 * - ::ly_ctx_get_submodule()
124 * - ::ly_ctx_get_submodule_latest()
125 * - ::ly_ctx_get_submodule2()
126 * - ::ly_ctx_get_submodule2_latest()
Radek Krejci52785a22019-09-11 12:57:26 +0200127 * - ::ly_ctx_reset_latests()
Radek Krejci8678fa42020-08-18 16:07:28 +0200128 *
129 * - ::ly_ctx_get_yanglib_data()
Radek Krejci8678fa42020-08-18 16:07:28 +0200130 *
Michal Vasko794ab4b2021-03-31 09:42:19 +0200131 * - ::ly_ctx_get_change_count()
Radek Krejci0a60f1d2020-10-26 22:24:43 +0100132 * - ::ly_ctx_internal_modules_count()
Radek Krejci8678fa42020-08-18 16:07:28 +0200133 *
Radek Krejci52785a22019-09-11 12:57:26 +0200134 * - ::lys_search_localfile()
Radek Krejci8678fa42020-08-18 16:07:28 +0200135 * - ::lys_set_implemented()
136 *
137 */
138
139/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200140 * @defgroup context Context
141 * @{
142 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200143 * Structures and functions to manipulate with the libyang context containers.
144 *
145 * The \em context concept allows callers to work in environments with different sets of YANG schemas.
146 * More detailed information can be found at @ref howtoContext page.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200147 */
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200148
149/**
150 * @struct ly_ctx
151 * @brief libyang context handler.
152 */
153struct ly_ctx;
154
155/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200156 * @ingroup context
Radek Krejci8678fa42020-08-18 16:07:28 +0200157 * @defgroup contextoptions Context options
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200158 *
159 * Options to change context behavior.
Radek Krejci474f9b82019-07-24 11:36:37 +0200160 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200161 * @{
162 */
163
Michal Vasko25d6ad02020-10-22 12:20:22 +0200164#define LY_CTX_ALL_IMPLEMENTED 0x01 /**< All the imported modules of the schema being parsed are implemented. */
165#define LY_CTX_REF_IMPLEMENTED 0x02 /**< Implement all imported modules "referenced" from an implemented module.
166 Normally, leafrefs, augment and deviation targets are implemented as
167 specified by YANG 1.1. In addition to this, implement any modules of
168 nodes referenced by when and must conditions and by any default values.
169 Generally, only if all these modules are implemented, the explicitly
170 implemented modules can be properly used and instantiated in data. */
171#define LY_CTX_NO_YANGLIBRARY 0x04 /**< Do not internally implement ietf-yang-library module. The option
Radek Krejci8678fa42020-08-18 16:07:28 +0200172 causes that function ::ly_ctx_get_yanglib_data() does not work (returns ::LY_EINVAL) until
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200173 the ietf-yang-library module is loaded manually. While any revision
174 of this schema can be loaded with this option, note that the only
Radek Krejci8678fa42020-08-18 16:07:28 +0200175 revisions implemented by ::ly_ctx_get_yanglib_data() are 2016-06-21 and 2019-01-04.
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200176 This option cannot be changed on existing context. */
177#define LY_CTX_DISABLE_SEARCHDIRS 0x08 /**< Do not search for schemas in context's searchdirs neither in current
178 working directory. It is entirely skipped and the only way to get
Radek Krejci8678fa42020-08-18 16:07:28 +0200179 schema data for imports or for ::ly_ctx_load_module() is to use the
180 callbacks provided by caller via ::ly_ctx_set_module_imp_clb() */
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200181#define LY_CTX_DISABLE_SEARCHDIR_CWD 0x10 /**< Do not automatically search for schemas in current working
182 directory, which is by default searched automatically (despite not
183 recursively). */
184#define LY_CTX_PREFER_SEARCHDIRS 0x20 /**< When searching for schema, prefer searchdirs instead of user callback. */
aPiecek9922ea92021-04-12 07:59:20 +0200185#define LY_CTX_SET_PRIV_PARSED 0x40 /**< For all compiled nodes, their private objects (::lysc_node.priv) are used
186 by libyang as a reference to the corresponding parsed node (::lysp_node).
187 So if this option is set, the user must not change private objects.
188 Setting this option by ::ly_ctx_set_options() may result in context recompilation.
189 Resetting this option by ::ly_ctx_unset_options() cause that private
190 objects will be set to NULL. */
Radek Krejci0af46292019-01-11 16:02:31 +0100191
Michal Vaskob36053d2020-03-26 15:49:30 +0100192/** @} contextoptions */
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200193
194/**
195 * @brief Create libyang context.
196 *
197 * Context is used to hold all information about schemas. Usually, the application is supposed
198 * to work with a single context in which libyang is holding all schemas (and other internal
199 * information) according to which the data trees will be processed and validated. So, the schema
200 * trees are tightly connected with the specific context and they are held by the context internally
Radek Krejci8678fa42020-08-18 16:07:28 +0200201 * - caller does not need to keep pointers to the schemas returned by ::lys_parse(), context knows
202 * about them. The data trees created with \b lyd_parse_*() are still connected with the specific context,
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200203 * but they are not internally held by the context. The data tree just points and lean on some data
204 * held by the context (schema tree, string dictionary, etc.). Therefore, in case of data trees, caller
Radek Krejci8678fa42020-08-18 16:07:28 +0200205 * is supposed to keep pointers returned by the \b lyd_parse_*() functions and manage the data tree on its own. This
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200206 * also affects the number of instances of both tree types. While you can have only one instance of
207 * specific schema connected with a single context, number of data tree instances is not connected.
208 *
209 * @param[in] search_dir Directory where libyang will search for the imported or included modules
210 * and submodules. If no such directory is available, NULL is accepted.
211 * @param[in] options Context options, see @ref contextoptions.
212 * @param[out] new_ctx Pointer to the created libyang context if LY_SUCCESS returned.
213 * @return LY_ERR return value.
214 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200215LY_ERR ly_ctx_new(const char *search_dir, uint16_t options, struct ly_ctx **new_ctx);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200216
217/**
Tadeáš Vintrlík390b2722021-04-07 13:52:45 +0200218 * @brief Create libyang context according to the content of the given yang-library data.
219 *
220 * This function loads the yang-library data from the given path. If you need to pass the data as
221 * string, use ::::ly_ctx_new_ylmem(). Both functions extend functionality of ::ly_ctx_new() by loading
222 * modules specified in the ietf-yang-library form into the context being created.
223 * The preferred tree model revision is 2019-01-04. However, only the first module-set is processed and loaded
224 * into the context. If there are no matching nodes from this tree, the legacy tree (originally from model revision 2016-04-09)
225 * is processed. Note, that the modules are loaded the same way as in case of ::ly_ctx_load_module(), so the schema paths in the
226 * yang-library data are ignored and the modules are loaded from the context's search locations. On the other hand, YANG features
227 * of the modules are set as specified in the yang-library data.
228 * To get yang library data from a libyang context, use ::ly_ctx_get_yanglib_data().
229 *
230 * @param[in] search_dir Directory where libyang will search for the imported or included modules and submodules.
231 * If no such directory is available, NULL is accepted.
232 * @param[in] path Path to the file containing yang-library-data in the specified format
233 * @param[in] format Format of the data in the provided file.
234 * @param[in] options Context options, see @ref contextoptions.
235 * @param[out] ctx Pointer to the created libyang context if LY_SUCCESS returned.
236 * @return LY_ERR return value
237 */
238LY_ERR ly_ctx_new_ylpath(const char *search_dir, const char *path, LYD_FORMAT format, int options, struct ly_ctx **ctx);
239
240/**
241 * @brief Create libyang context according to the content of the given yang-library data.
242 *
243 * This function loads the yang-library data from the given string. If you need to pass the data as
244 * path to a file holding the data, use ::ly_ctx_new_ylpath(). Both functions extend functionality of
245 * ::ly_ctx_new() by loading modules specified in the ietf-yang-library form into the context being created.
246 * The preferred tree model revision is 2019-01-04. However, only the first module-set is processed and loaded
247 * into the context. If there are no matching nodes from this tree, the legacy tree (originally from model revision 2016-04-09)
248 * is processed. Note, that the modules are loaded the same way as in case of ::ly_ctx_load_module(), so the schema paths in the
249 * yang-library data are ignored and the modules are loaded from the context's search locations. On the other hand, YANG features
250 * of the modules are set as specified in the yang-library data.
251 * To get yang library data from a libyang context, use ::ly_ctx_get_yanglib_data().
252 *
253 * @param[in] search_dir Directory where libyang will search for the imported or included modules and submodules.
254 * If no such directory is available, NULL is accepted.
255 * @param[in] data String containing yang-library data in the specified format.
256 * @param[in] format Format of the data in the provided file.
257 * @param[in] options Context options, see @ref contextoptions.
258 * @param[out] ctx Pointer to the created libyang context if LY_SUCCESS returned.
259 * @return LY_ERR return value
260 */
261LY_ERR ly_ctx_new_ylmem(const char *search_dir, const char *data, LYD_FORMAT format, int options, struct ly_ctx **ctx);
262
263/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200264 * @brief Add the search path into libyang context
265 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200266 * To reset search paths set in the context, use ::ly_ctx_unset_searchdir() and then
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200267 * set search paths again.
268 *
269 * @param[in] ctx Context to be modified.
270 * @param[in] search_dir New search path to add to the current paths previously set in ctx.
271 * @return LY_ERR return value.
272 */
273LY_ERR ly_ctx_set_searchdir(struct ly_ctx *ctx, const char *search_dir);
274
275/**
276 * @brief Clean the search path(s) from the libyang context
277 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200278 * To remove the recently added search path(s), use ::ly_ctx_unset_searchdir_last().
Radek Krejcied5acc52019-04-25 15:57:04 +0200279 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200280 * @param[in] ctx Context to be modified.
281 * @param[in] value Searchdir to be removed, use NULL to remove them all.
282 * @return LY_ERR return value
283 */
Radek Krejcie58f97f2020-08-18 11:45:08 +0200284LY_ERR ly_ctx_unset_searchdir(struct ly_ctx *ctx, const char *value);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200285
286/**
Radek Krejcie58f97f2020-08-18 11:45:08 +0200287 * @brief Remove the least recently added search path(s) from the libyang context.
Radek Krejcied5acc52019-04-25 15:57:04 +0200288 *
Radek Krejci8678fa42020-08-18 16:07:28 +0200289 * To remove a specific search path by its value, use ::ly_ctx_unset_searchdir().
Radek Krejcied5acc52019-04-25 15:57:04 +0200290 *
291 * @param[in] ctx Context to be modified.
Radek Krejcie58f97f2020-08-18 11:45:08 +0200292 * @param[in] count Number of the searchdirs to be removed (starting by the least recently added).
293 * If the value is higher then the actual number of search paths, all paths are removed and no error is returned.
294 * Value 0 does not change the search path set.
Radek Krejcied5acc52019-04-25 15:57:04 +0200295 * @return LY_ERR return value
296 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200297LY_ERR ly_ctx_unset_searchdir_last(struct ly_ctx *ctx, uint32_t count);
Radek Krejcied5acc52019-04-25 15:57:04 +0200298
299/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200300 * @brief Get the NULL-terminated list of the search paths in libyang context. Do not modify the result!
301 *
302 * @param[in] ctx Context to query.
303 * @return NULL-terminated list (array) of the search paths, NULL if no searchpath was set.
304 * Do not modify the provided data in any way!
305 */
306const char * const *ly_ctx_get_searchdirs(const struct ly_ctx *ctx);
307
308/**
309 * @brief Get the currently set context's options.
310 *
311 * @param[in] ctx Context to query.
312 * @return Combination of all the currently set context's options, see @ref contextoptions.
313 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200314uint16_t ly_ctx_get_options(const struct ly_ctx *ctx);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200315
316/**
317 * @brief Set some of the context's options, see @ref contextoptions.
318 * @param[in] ctx Context to be modified.
319 * @param[in] option Combination of the context's options to be set, see @ref contextoptions.
aPiecek9922ea92021-04-12 07:59:20 +0200320 * If there is to be a change to ::LY_CTX_SET_PRIV_PARSED, the context will be recompiled
321 * and all ::lysc_node.priv in the modules will be overwritten, see ::LY_CTX_SET_PRIV_PARSED.
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200322 * @return LY_ERR value.
323 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200324LY_ERR ly_ctx_set_options(struct ly_ctx *ctx, uint16_t option);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200325
326/**
327 * @brief Unset some of the context's options, see @ref contextoptions.
328 * @param[in] ctx Context to be modified.
329 * @param[in] option Combination of the context's options to be unset, see @ref contextoptions.
330 * @return LY_ERR value.
331 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200332LY_ERR ly_ctx_unset_options(struct ly_ctx *ctx, uint16_t option);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200333
334/**
Michal Vasko794ab4b2021-03-31 09:42:19 +0200335 * @brief Get the change count of the context (module set) during its life-time.
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200336 *
337 * @param[in] ctx Context to be examined.
Michal Vasko794ab4b2021-03-31 09:42:19 +0200338 * @return Context change count.
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200339 */
Michal Vasko794ab4b2021-03-31 09:42:19 +0200340uint16_t ly_ctx_get_change_count(const struct ly_ctx *ctx);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200341
342/**
Michal Vaskob2786d72020-08-24 13:19:52 +0200343 * @brief Callback for freeing returned module data in #ly_module_imp_clb.
344 *
345 * @param[in] module_data Data to free.
346 * @param[in] user_data User-supplied callback data, same as for #ly_module_imp_clb.
347 */
348typedef void (*ly_module_imp_data_free_clb)(void *module_data, void *user_data);
349
350/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200351 * @brief Callback for retrieving missing included or imported models in a custom way.
352 *
Radek Krejcibb9d2242021-01-04 10:51:31 +0100353 * When @p submod_name is provided, the submodule is requested instead of the module (in this case only
Radek Krejcid33273d2018-10-25 14:55:52 +0200354 * the module name without its revision is provided).
355 *
356 * If an @arg free_module_data callback is provided, it will be used later to free the allegedly const data
357 * which were returned by this callback.
358 *
359 * @param[in] mod_name Missing module name.
Radek Krejci086c7132018-10-26 15:29:04 +0200360 * @param[in] mod_rev Optional missing module revision. If NULL and submod_name is not provided, the latest revision is
361 * requested, the parsed module is then marked by the latest_revision flag.
Radek Krejcid33273d2018-10-25 14:55:52 +0200362 * @param[in] submod_name Optional missing submodule name.
Radek Krejci086c7132018-10-26 15:29:04 +0200363 * @param[in] submod_rev Optional missing submodule revision. If NULL and submod_name is provided, the latest revision is
364 * requested, the parsed submodule is then marked by the latest_revision flag.
Radek Krejcid33273d2018-10-25 14:55:52 +0200365 * @param[in] user_data User-supplied callback data.
366 * @param[out] format Format of the returned module data.
367 * @param[out] module_data Requested module data.
368 * @param[out] free_module_data Callback for freeing the returned module data. If not set, the data will be left untouched.
369 * @return LY_ERR value. If the returned value differs from LY_SUCCESS, libyang continue in trying to get the module data
370 * according to the settings of its mechanism to search for the imported/included schemas.
371 */
Radek Krejcibb9d2242021-01-04 10:51:31 +0100372typedef LY_ERR (*ly_module_imp_clb)(const char *mod_name, const char *mod_rev, const char *submod_name, const char *submod_rev,
Michal Vaskob2786d72020-08-24 13:19:52 +0200373 void *user_data, LYS_INFORMAT *format, const char **module_data, ly_module_imp_data_free_clb *free_module_data);
Radek Krejcid33273d2018-10-25 14:55:52 +0200374
375/**
376 * @brief Get the custom callback for missing import/include module retrieval.
377 *
378 * @param[in] ctx Context to read from.
379 * @param[in] user_data Optional pointer for getting the user-supplied callback data.
380 * @return Callback or NULL if not set.
381 */
382ly_module_imp_clb ly_ctx_get_module_imp_clb(const struct ly_ctx *ctx, void **user_data);
383
384/**
385 * @brief Set missing include or import module callback. It is meant to be used when the models
386 * are not locally available (such as when downloading modules from a NETCONF server), it should
387 * not be required in other cases.
388 *
389 * @param[in] ctx Context that will use this callback.
390 * @param[in] clb Callback responsible for returning the missing model.
391 * @param[in] user_data Arbitrary data that will always be passed to the callback \p clb.
392 */
393void ly_ctx_set_module_imp_clb(struct ly_ctx *ctx, ly_module_imp_clb clb, void *user_data);
394
395/**
Radek Krejcib7db73a2018-10-24 14:18:40 +0200396 * @brief Get YANG module of the given name and revision.
397 *
398 * @param[in] ctx Context to work in.
399 * @param[in] name Name of the YANG module to get.
400 * @param[in] revision Requested revision date of the YANG module to get. If not specified,
401 * the schema with no revision is returned, if it is present in the context.
402 * @return Pointer to the YANG module, NULL if no schema in the context follows the name and revision requirements.
403 */
Radek Krejci0af46292019-01-11 16:02:31 +0100404struct lys_module *ly_ctx_get_module(const struct ly_ctx *ctx, const char *name, const char *revision);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200405
406/**
407 * @brief Get the latest revision of the YANG module specified by its name.
408 *
409 * YANG modules with no revision are supposed to be the oldest one.
410 *
411 * @param[in] ctx Context where to search.
412 * @param[in] name Name of the YANG module to get.
413 * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the
414 * given name is present in the context.
415 */
Radek Krejci0af46292019-01-11 16:02:31 +0100416struct lys_module *ly_ctx_get_module_latest(const struct ly_ctx *ctx, const char *name);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200417
418/**
419 * @brief Get the (only) implemented YANG module specified by its name.
420 *
421 * @param[in] ctx Context where to search.
422 * @param[in] name Name of the YANG module to get.
423 * @return The only implemented YANG module revision of the given name in the given context. NULL if there is no
424 * implemented module of the given name.
425 */
Radek Krejci0af46292019-01-11 16:02:31 +0100426struct lys_module *ly_ctx_get_module_implemented(const struct ly_ctx *ctx, const char *name);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200427
428/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200429 * @brief Iterate over all modules in the given context.
430 *
431 * @param[in] ctx Context with the modules.
432 * @param[in,out] index Index of the next module to get. Value of 0 starts from the beginning.
433 * The value is updated with each call, so to iterate over all modules the same variable is supposed
434 * to be used in all calls starting with value 0.
435 * @return Next context module, NULL if the last was already returned.
436 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200437const struct lys_module *ly_ctx_get_module_iter(const struct ly_ctx *ctx, uint32_t *index);
Radek Krejcied5acc52019-04-25 15:57:04 +0200438
439/**
Radek Krejcib7db73a2018-10-24 14:18:40 +0200440 * @brief Get YANG module of the given namespace and revision.
441 *
442 * @param[in] ctx Context to work in.
443 * @param[in] ns Namespace of the YANG module to get.
444 * @param[in] revision Requested revision date of the YANG module to get. If not specified,
445 * the schema with no revision is returned, if it is present in the context.
446 * @return Pointer to the YANG module, NULL if no schema in the context follows the namespace and revision requirements.
447 */
Radek Krejci0af46292019-01-11 16:02:31 +0100448struct lys_module *ly_ctx_get_module_ns(const struct ly_ctx *ctx, const char *ns, const char *revision);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200449
450/**
451 * @brief Get the latest revision of the YANG module specified by its namespace.
452 *
453 * YANG modules with no revision are supposed to be the oldest one.
454 *
455 * @param[in] ctx Context where to search.
456 * @param[in] ns Namespace of the YANG module to get.
457 * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the
458 * given namespace is present in the context.
459 */
Radek Krejci0af46292019-01-11 16:02:31 +0100460struct lys_module *ly_ctx_get_module_latest_ns(const struct ly_ctx *ctx, const char *ns);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200461
462/**
463 * @brief Get the (only) implemented YANG module specified by its namespace.
464 *
465 * @param[in] ctx Context where to search.
466 * @param[in] ns Namespace of the YANG module to get.
467 * @return The only implemented YANG module revision of the given namespace in the given context. NULL if there is no
468 * implemented module of the given namespace.
469 */
Radek Krejci0af46292019-01-11 16:02:31 +0100470struct lys_module *ly_ctx_get_module_implemented_ns(const struct ly_ctx *ctx, const char *ns);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200471
472/**
Michal Vasko8dc31992021-02-22 10:30:47 +0100473 * @brief Get a specific submodule from context. If its belongs-to module is known, use ::ly_ctx_get_submodule2().
474 *
475 * @param[in] ctx libyang context to search in.
476 * @param[in] submodule Submodule name to find.
477 * @param[in] revision Revision of the submodule to find, NULL for a submodule without a revision.
478 * @return Found submodule, NULL if there is none.
479 */
480const struct lysp_submodule *ly_ctx_get_submodule(const struct ly_ctx *ctx, const char *submodule, const char *revision);
481
482/**
483 * @brief Get the latests revision of a submodule from context. If its belongs-to module is known,
484 * use ::ly_ctx_get_submodule2_latest().
485 *
486 * @param[in] ctx libyang context to search in.
487 * @param[in] submodule Submodule name to find.
488 * @return Found submodule, NULL if there is none.
489 */
490const struct lysp_submodule *ly_ctx_get_submodule_latest(const struct ly_ctx *ctx, const char *submodule);
491
492/**
493 * @brief Get a specific submodule from a module. If the belongs-to module is not known, use ::ly_ctx_get_submodule().
494 *
495 * @param[in] module Belongs-to module to search in.
496 * @param[in] submodule Submodule name to find.
497 * @param[in] revision Revision of the submodule to find, NULL for a submodule without a revision.
498 * @return Found submodule, NULL if there is none.
499 */
500const struct lysp_submodule *ly_ctx_get_submodule2(const struct lys_module *module, const char *submodule,
501 const char *revision);
502
503/**
504 * @brief Get the latest revision of a submodule from a module. If the belongs-to module is not known,
505 * use ::ly_ctx_get_submodule_latest().
506 *
507 * @param[in] module Belongs-to module to search in.
508 * @param[in] submodule Submodule name to find.
509 * @return Found submodule, NULL if there is none.
510 */
511const struct lysp_submodule *ly_ctx_get_submodule2_latest(const struct lys_module *module, const char *submodule);
512
513/**
Radek Krejcie9e987e2018-10-31 12:50:27 +0100514 * @brief Reset cached latest revision information of the schemas in the context.
515 *
516 * When a (sub)module is imported/included without revision, the latest revision is
517 * searched. libyang searches for the latest revision in searchdirs and/or via provided
Radek Krejci8678fa42020-08-18 16:07:28 +0200518 * import callback ::ly_module_imp_clb() just once. Then it is expected that the content
Radek Krejcie9e987e2018-10-31 12:50:27 +0100519 * of searchdirs or data returned by the callback does not change. So when it changes,
520 * it is necessary to force searching for the latest revision in case of loading another
521 * module, which what this function does.
522 *
523 * The latest revision information is also reset when the searchdirs set changes via
Radek Krejci8678fa42020-08-18 16:07:28 +0200524 * ::ly_ctx_set_searchdir().
Radek Krejcie9e987e2018-10-31 12:50:27 +0100525 *
526 * @param[in] ctx libyang context where the latest revision information is going to be reset.
527 */
528void ly_ctx_reset_latests(struct ly_ctx *ctx);
529
530/**
Michal Vaskode79e222020-08-10 11:55:46 +0200531 * @brief Learn the number of internal modules of a context. Internal modules
532 * is considered one that was loaded during the context creation.
533 *
534 * @param[in] ctx libyang context to examine.
535 * @return Number of internal modules.
536 */
Radek Krejci0a60f1d2020-10-26 22:24:43 +0100537uint32_t ly_ctx_internal_modules_count(const struct ly_ctx *ctx);
Michal Vaskode79e222020-08-10 11:55:46 +0200538
539/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200540 * @brief Try to find the model in the searchpaths of \p ctx and load it into it. If custom missing
541 * module callback is set, it is used instead.
542 *
543 * The context itself is searched for the requested module first. If \p revision is not specified
544 * (the module of the latest revision is requested) and there is implemented revision of the requested
545 * module in the context, this implemented revision is returned despite there might be a newer revision.
546 * This behavior is cause by the fact that it is not possible to have multiple implemented revisions of
547 * the same module in the context.
548 *
549 * @param[in] ctx Context to add to.
550 * @param[in] name Name of the module to load.
551 * @param[in] revision Optional revision date of the module. If not specified, the latest revision is loaded.
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100552 * @param[in] features Optional array of features ended with NULL to be enabled if the module is being implemented.
Radek Krejci2415f882021-01-20 16:27:09 +0100553 * The feature string '*' enables all and array of length 1 with only the terminating NULL explicitly disables all
554 * the features. In case the parameter is NULL, the features are untouched - left disabled in newly loaded module or
555 * with the current features settings in case the module is already present in the context.
Radek Krejcied5acc52019-04-25 15:57:04 +0200556 * @return Pointer to the data model structure, NULL if not found or some error occurred.
557 */
Michal Vasko7b1ad1a2020-11-02 15:41:27 +0100558const struct lys_module *ly_ctx_load_module(struct ly_ctx *ctx, const char *name, const char *revision,
559 const char **features);
Radek Krejcied5acc52019-04-25 15:57:04 +0200560
561/**
Michal Vasko57c10cd2020-05-27 15:57:11 +0200562 * @brief Get data of the internal ietf-yang-library module with information about all the loaded modules.
563 * ietf-yang-library module must be loaded.
564 *
Michal Vasko794ab4b2021-03-31 09:42:19 +0200565 * Note that "/ietf-yang-library:yang-library/datastore" list instances are not created and should be
566 * appended by the caller. There is a single "/ietf-yang-library:yang-library/schema" instance created
567 * with the key value "complete".
568 *
569 * If the data identifier can be limited to the existence and changes of this context, the following
570 * last 2 parameters can be used:
571 *
572 * "%u" as @p content_id_format and ::ly_ctx_get_change_count() as its parameter.
573 *
Michal Vasko57c10cd2020-05-27 15:57:11 +0200574 * @param[in] ctx Context with the modules.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200575 * @param[out] root Generated yang-library data.
Michal Vasko794ab4b2021-03-31 09:42:19 +0200576 * @param[in] content_id_format Format string (printf-like) for the yang-library data identifier, which is
577 * the "content_id" node in the 2019-01-04 revision of ietf-yang-library.
578 * @param[in] ... Parameters for @p content_id_format.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200579 * @return LY_ERR value
Michal Vasko57c10cd2020-05-27 15:57:11 +0200580 */
Michal Vasko794ab4b2021-03-31 09:42:19 +0200581LY_ERR ly_ctx_get_yanglib_data(const struct ly_ctx *ctx, struct lyd_node **root, const char *content_id_format, ...);
Michal Vasko57c10cd2020-05-27 15:57:11 +0200582
583/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200584 * @brief Free all internal structures of the specified context.
585 *
586 * The function should be used before terminating the application to destroy
587 * and free all structures internally used by libyang. If the caller uses
588 * multiple contexts, the function should be called for each used context.
589 *
590 * All instance data are supposed to be freed before destroying the context.
Radek Krejci8678fa42020-08-18 16:07:28 +0200591 * Data models are destroyed automatically as part of ::ly_ctx_destroy() call.
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200592 *
Radek Krejci90ed21e2021-04-12 14:47:46 +0200593 * Note that the data stored by user into the ::lysc_node.priv pointer are kept
594 * untouched and the caller is responsible for freeing this private data.
595 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200596 * @param[in] ctx libyang context to destroy
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200597 */
Radek Krejci90ed21e2021-04-12 14:47:46 +0200598void ly_ctx_destroy(struct ly_ctx *ctx);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200599
600/** @} context */
601
602#ifdef __cplusplus
603}
604#endif
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200605
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200606#endif /* LY_CONTEXT_H_ */