blob: 65e5a68af979493c7977e9403efabebbc8ec8899 [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 *
6 * Copyright (c) 2015 - 2017 CESNET, z.s.p.o.
7 *
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"
Radek Krejci5aeea3a2018-09-05 13:29:36 +020022
Radek Krejci6caa6ab2018-10-24 10:04:48 +020023#ifdef __cplusplus
24extern "C" {
25#endif
26
Michal Vasko3a41dff2020-07-15 14:30:28 +020027struct lyd_node;
Radek Krejcica376bd2020-06-11 16:04:06 +020028struct lysc_node;
29
Radek Krejci5aeea3a2018-09-05 13:29:36 +020030/**
Radek Krejci52785a22019-09-11 12:57:26 +020031 * @page howtocontext Context
32 *
33 * The context concept allows callers to work in environments with different sets of YANG schemas.
34 *
35 * The first step in libyang is to create a new context using ly_ctx_new(). It returns a handler
36 * used in the following work.
37 *
38 * When creating a new context, search dir can be specified (NULL is accepted) to provide directory
39 * where libyang will automatically search for schemas being imported or included. The search path
40 * can be later changed via ly_ctx_set_searchdir() and ly_ctx_unset_searchdir() functions. Before the search dirs,
41 * also the current working directory is (non-recursively) searched. For the case of the explicitly set search
42 * dirs, also all their subdirectories (and symlinks) are taken into account. Searching in the current working
43 * directory can be avoided with the context's #LY_CTX_DISABLE_SEARCHDIR_CWD option (or via ly_ctx_set_options()).
44 * Searching in all the context's search dirs (without removing them) can be avoided with the context's
45 * #LY_CTX_DISABLE_SEARCHDIRS option (or via ly_ctx_set_options()). This automatic searching can be preceded
46 * by a custom module searching callback (#ly_module_imp_clb) set via ly_ctx_set_module_imp_clb(). The algorithm of
47 * searching in search dirs is also available via API as lys_search_localfile() function.
48 *
49 * Schemas are added into the context using [parser functions](@ref howtoschemasparsers) - \b lys_parse_*().
50 * Alternatively, also ly_ctx_load_module() can be used - in that case the #ly_module_imp_clb or automatic
51 * search in search dir and in the current working directory is used. YANG submodules cannot be loaded or even validated
52 * directly, they are loaded always only as includes of YANG modules.
53 *
54 * YANG schemas are loaded in two steps. First, the input YANG/YIN data are parsed into \b lysp_* structures that reflect
55 * the structure of the input schema. Mostly just syntax checks are done, no reference or type checking is performed in
56 * this step. If the module is supposed to be implemented, not just imported by another module, the second step is to compile
57 * it. The compiled schema may significantly differ in structure from the source schema structure. All the references
58 * are resolved, groupings are instantiated, types are resolved (and compiled by grouping all the relevant restrictions
59 * when derived from another types) and many other syntactical checks are done.
60 *
61 * Similarly, data trees can be parsed by \b lyd_parse_*() functions. Note, that functions for schemas have \b lys_
62 * prefix (or \b lysp_ for the parsed and \b lysc_ for the compiled schema) while functions for instance data have
63 * \b lyd_ prefix. It can happen during data parsing that a schema is required and __not found__ in the context or
64 * the schema is found, but is __only imported__, not implemented (so the data cannot actually be instantiated).
65 * In these cases, a callback is called, which should add this schema into the context or change its conformance
66 * to implemented. You can set the callback using ly_ctx_set_module_data_clb() (more in @ref howtodataparsers
67 * and @ref howtodatavalidation).
68 *
69 * Context can hold multiple revisions of the same schema, but only one of them can be implemented. The schema is not
70 * implemented in case it is automatically loaded as import for another module and it is not referenced in such
71 * a module (and no other) as target of leafref, augment or deviation. All modules with deviation definition are always
72 * marked as implemented. The imported (not implemented) module can be set implemented by lys_set_implemented(). But
73 * the implemented module cannot be changed back to just imported module. The imported modules are used only as a
74 * source of definitions for types and groupings for uses statements. The data in such modules are ignored - caller
75 * is not allowed to create the data (including instantiating identities) defined in the model via data parsers,
76 * the default nodes are not added into any data tree and mandatory nodes are not checked in the data trees. This
77 * can be changed by ly_ctx_new()'s #LY_CTX_ALLIMPLEMENTED option (or via ly_ctx_set_options()), which causes that
78 * all the imported modules are automatically set to be implemented.
79 *
80 * When loading/importing a module without revision, the latest revision of the required module is supposed to load.
81 * For a context, the first time the latest revision of a module is requested, it is properly searched for and loaded.
82 * However, when this module is requested (without revision) the second time, the one found previously is returned.
83 * This has the advantage of not searching for the module repeatedly but the drawback that if a later revision
84 * of the module is later made available, this context will not use it. However, to force libyang to re-search the
85 * latest revision, ly_ctx_reset_latests() can be used (not that it applies to all the schemas in the context).
86 *
87 * Context holds all schema modules internally. To get a specific module, use ly_ctx_get_module() (or ly_ctx_get_module_ns())
88 * The returned structure includes both, parsed and compiled, schema variants. If you need to do something with all the modules
89 * in the context, it is advised to iterate over them using ly_ctx_get_module_iter(), it is the most efficient way.
90 * Alternatively, the ly_ctx_info() function can be used to get complex information about the schemas in the context
91 * in the form of data tree defined by <a href="https://tools.ietf.org/html/rfc7895">ietf-yang-library</a> schema.
92 * To get a specific node defined in a module in the context, ly_ctx_find_path() or ly_ctx_get_node() can be used.
93 *
94 * Modules cannot be removed from their context. If you need to change the set of the schema modules in the context
95 * (use only a subset), a new context must be created. To remove the context, there is ly_ctx_destroy() function.
96 *
97 * - @subpage howtocontextdict
98 *
99 * \note API for this group of functions is available in the [context module](@ref context).
100 *
101 * Functions List
102 * --------------
103 * - ::ly_ctx_new()
104 * - ::ly_ctx_set_searchdir()
105 * - ::ly_ctx_unset_searchdir()
106 * - ::ly_ctx_unset_searchdirs()
107 * - ::ly_ctx_get_searchdirs()
108 * - ::ly_ctx_set_module_imp_clb()
109 * - ::ly_ctx_get_module_imp_clb()
110 * - ::ly_ctx_set_module_data_clb()
111 * - ::ly_ctx_get_module_data_clb()
112 * - ::ly_ctx_set_options()
113 * - ::ly_ctx_unset_options()
114 * - ::ly_ctx_get_options()
115 * - ::ly_ctx_load_module()
116 * - ::ly_ctx_info()
117 * - ::ly_ctx_get_module_iter()
118 * - ::ly_ctx_get_module()
119 * - ::ly_ctx_get_module_ns()
120 * - ::ly_ctx_get_module_implemented()
121 * - ::ly_ctx_get_module_implemented_ns()
122 * - ::ly_ctx_get_module_latest()
123 * - ::ly_ctx_get_module_latest_ns()
124 * - ::ly_ctx_reset_latests()
125 * - ::ly_ctx_get_module_set_id()
126 * - ::ly_ctx_get_node()
127 * - ::ly_ctx_find_path()
128 * - ::ly_ctx_destroy()
129 * - ::lys_set_implemented()
130 * - ::lys_search_localfile()
131 */
132
133/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200134 * @defgroup context Context
135 * @{
136 *
137 * Structures and functions to manipulate with the libyang "containers". The \em context concept allows callers
138 * to work in environments with different sets of YANG schemas. More detailed information can be found at
139 * @ref howtocontext page.
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200140 */
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200141
142/**
143 * @struct ly_ctx
144 * @brief libyang context handler.
145 */
146struct ly_ctx;
147
148/**
149 * @defgroup contextoptions Context options
150 * @ingroup context
151 *
152 * Options to change context behavior.
Radek Krejci474f9b82019-07-24 11:36:37 +0200153 *
154 * Note that the flags 0xFF00 are reserved for internal use.
155 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200156 * @{
157 */
158
159#define LY_CTX_ALLIMPLEMENTED 0x01 /**< All the imports of the schema being parsed are treated implemented. */
160#define LY_CTX_TRUSTED 0x02 /**< Handle the schema being parsed as trusted and skip its validation
161 tests. Note that while this option improves performance, it can
162 lead to an undefined behavior if the schema is not correct. */
163#define LY_CTX_NOYANGLIBRARY 0x04 /**< Do not internally implement ietf-yang-library module. The option
164 causes that function ly_ctx_info() does not work (returns NULL) until
165 the ietf-yang-library module is loaded manually. While any revision
166 of this schema can be loaded with this option, note that the only
167 revisions implemented by ly_ctx_info() are 2016-04-09 and 2018-01-17.
168 This option cannot be changed on existing context. */
169#define LY_CTX_DISABLE_SEARCHDIRS 0x08 /**< Do not search for schemas in context's searchdirs neither in current
170 working directory. It is entirely skipped and the only way to get
171 schema data for imports or for ly_ctx_load_module() is to use the
172 callbacks provided by caller via ly_ctx_set_module_imp_clb() */
173#define LY_CTX_DISABLE_SEARCHDIR_CWD 0x10 /**< Do not automatically search for schemas in current working
174 directory, which is by default searched automatically (despite not
175 recursively). */
176#define LY_CTX_PREFER_SEARCHDIRS 0x20 /**< When searching for schema, prefer searchdirs instead of user callback. */
Radek Krejci0af46292019-01-11 16:02:31 +0100177
Michal Vaskob36053d2020-03-26 15:49:30 +0100178/** @} contextoptions */
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200179
180/**
181 * @brief Create libyang context.
182 *
183 * Context is used to hold all information about schemas. Usually, the application is supposed
184 * to work with a single context in which libyang is holding all schemas (and other internal
185 * information) according to which the data trees will be processed and validated. So, the schema
186 * trees are tightly connected with the specific context and they are held by the context internally
187 * - caller does not need to keep pointers to the schemas returned by lys_parse(), context knows
188 * about them. The data trees created with lyd_parse() are still connected with the specific context,
189 * but they are not internally held by the context. The data tree just points and lean on some data
190 * held by the context (schema tree, string dictionary, etc.). Therefore, in case of data trees, caller
191 * is supposed to keep pointers returned by the lyd_parse() and manage the data tree on its own. This
192 * also affects the number of instances of both tree types. While you can have only one instance of
193 * specific schema connected with a single context, number of data tree instances is not connected.
194 *
195 * @param[in] search_dir Directory where libyang will search for the imported or included modules
196 * and submodules. If no such directory is available, NULL is accepted.
197 * @param[in] options Context options, see @ref contextoptions.
198 * @param[out] new_ctx Pointer to the created libyang context if LY_SUCCESS returned.
199 * @return LY_ERR return value.
200 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200201LY_ERR ly_ctx_new(const char *search_dir, uint16_t options, struct ly_ctx **new_ctx);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200202
203/**
204 * @brief Add the search path into libyang context
205 *
Radek Krejcie58f97f2020-08-18 11:45:08 +0200206 * To reset search paths set in the context, use ly_ctx_unset_searchdir() and then
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200207 * set search paths again.
208 *
209 * @param[in] ctx Context to be modified.
210 * @param[in] search_dir New search path to add to the current paths previously set in ctx.
211 * @return LY_ERR return value.
212 */
213LY_ERR ly_ctx_set_searchdir(struct ly_ctx *ctx, const char *search_dir);
214
215/**
216 * @brief Clean the search path(s) from the libyang context
217 *
Radek Krejcie58f97f2020-08-18 11:45:08 +0200218 * To remove the recently added search path(s), use ly_ctx_unset_searchdir_last().
Radek Krejcied5acc52019-04-25 15:57:04 +0200219 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200220 * @param[in] ctx Context to be modified.
221 * @param[in] value Searchdir to be removed, use NULL to remove them all.
222 * @return LY_ERR return value
223 */
Radek Krejcie58f97f2020-08-18 11:45:08 +0200224LY_ERR ly_ctx_unset_searchdir(struct ly_ctx *ctx, const char *value);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200225
226/**
Radek Krejcie58f97f2020-08-18 11:45:08 +0200227 * @brief Remove the least recently added search path(s) from the libyang context.
Radek Krejcied5acc52019-04-25 15:57:04 +0200228 *
Radek Krejcie58f97f2020-08-18 11:45:08 +0200229 * To remove a specific search path by its value, use ly_ctx_unset_searchdir().
Radek Krejcied5acc52019-04-25 15:57:04 +0200230 *
231 * @param[in] ctx Context to be modified.
Radek Krejcie58f97f2020-08-18 11:45:08 +0200232 * @param[in] count Number of the searchdirs to be removed (starting by the least recently added).
233 * If the value is higher then the actual number of search paths, all paths are removed and no error is returned.
234 * Value 0 does not change the search path set.
Radek Krejcied5acc52019-04-25 15:57:04 +0200235 * @return LY_ERR return value
236 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200237LY_ERR ly_ctx_unset_searchdir_last(struct ly_ctx *ctx, uint32_t count);
Radek Krejcied5acc52019-04-25 15:57:04 +0200238
239/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200240 * @brief Get the NULL-terminated list of the search paths in libyang context. Do not modify the result!
241 *
242 * @param[in] ctx Context to query.
243 * @return NULL-terminated list (array) of the search paths, NULL if no searchpath was set.
244 * Do not modify the provided data in any way!
245 */
246const char * const *ly_ctx_get_searchdirs(const struct ly_ctx *ctx);
247
248/**
249 * @brief Get the currently set context's options.
250 *
251 * @param[in] ctx Context to query.
252 * @return Combination of all the currently set context's options, see @ref contextoptions.
253 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200254uint16_t ly_ctx_get_options(const struct ly_ctx *ctx);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200255
256/**
257 * @brief Set some of the context's options, see @ref contextoptions.
258 * @param[in] ctx Context to be modified.
259 * @param[in] option Combination of the context's options to be set, see @ref contextoptions.
260 * @return LY_ERR value.
261 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200262LY_ERR ly_ctx_set_options(struct ly_ctx *ctx, uint16_t option);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200263
264/**
265 * @brief Unset some of the context's options, see @ref contextoptions.
266 * @param[in] ctx Context to be modified.
267 * @param[in] option Combination of the context's options to be unset, see @ref contextoptions.
268 * @return LY_ERR value.
269 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200270LY_ERR ly_ctx_unset_options(struct ly_ctx *ctx, uint16_t option);
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200271
272/**
273 * @brief Get current ID of the modules set. The value is available also
274 * as module-set-id in ly_ctx_info() result.
275 *
276 * @param[in] ctx Context to be examined.
277 * @return Numeric identifier of the current context's modules set.
278 */
279uint16_t ly_ctx_get_module_set_id(const struct ly_ctx *ctx);
280
281/**
Michal Vaskob2786d72020-08-24 13:19:52 +0200282 * @brief Callback for freeing returned module data in #ly_module_imp_clb.
283 *
284 * @param[in] module_data Data to free.
285 * @param[in] user_data User-supplied callback data, same as for #ly_module_imp_clb.
286 */
287typedef void (*ly_module_imp_data_free_clb)(void *module_data, void *user_data);
288
289/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200290 * @brief Callback for retrieving missing included or imported models in a custom way.
291 *
292 * When submod_name is provided, the submodule is requested instead of the module (in this case only
293 * the module name without its revision is provided).
294 *
295 * If an @arg free_module_data callback is provided, it will be used later to free the allegedly const data
296 * which were returned by this callback.
297 *
298 * @param[in] mod_name Missing module name.
Radek Krejci086c7132018-10-26 15:29:04 +0200299 * @param[in] mod_rev Optional missing module revision. If NULL and submod_name is not provided, the latest revision is
300 * requested, the parsed module is then marked by the latest_revision flag.
Radek Krejcid33273d2018-10-25 14:55:52 +0200301 * @param[in] submod_name Optional missing submodule name.
Radek Krejci086c7132018-10-26 15:29:04 +0200302 * @param[in] submod_rev Optional missing submodule revision. If NULL and submod_name is provided, the latest revision is
303 * requested, the parsed submodule is then marked by the latest_revision flag.
Radek Krejcid33273d2018-10-25 14:55:52 +0200304 * @param[in] user_data User-supplied callback data.
305 * @param[out] format Format of the returned module data.
306 * @param[out] module_data Requested module data.
307 * @param[out] free_module_data Callback for freeing the returned module data. If not set, the data will be left untouched.
308 * @return LY_ERR value. If the returned value differs from LY_SUCCESS, libyang continue in trying to get the module data
309 * according to the settings of its mechanism to search for the imported/included schemas.
310 */
311typedef LY_ERR (*ly_module_imp_clb)(const char *mod_name, const char *mod_rev, const char *submod_name, const char *sub_rev,
Michal Vaskob2786d72020-08-24 13:19:52 +0200312 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 +0200313
314/**
315 * @brief Get the custom callback for missing import/include module retrieval.
316 *
317 * @param[in] ctx Context to read from.
318 * @param[in] user_data Optional pointer for getting the user-supplied callback data.
319 * @return Callback or NULL if not set.
320 */
321ly_module_imp_clb ly_ctx_get_module_imp_clb(const struct ly_ctx *ctx, void **user_data);
322
323/**
324 * @brief Set missing include or import module callback. It is meant to be used when the models
325 * are not locally available (such as when downloading modules from a NETCONF server), it should
326 * not be required in other cases.
327 *
328 * @param[in] ctx Context that will use this callback.
329 * @param[in] clb Callback responsible for returning the missing model.
330 * @param[in] user_data Arbitrary data that will always be passed to the callback \p clb.
331 */
332void ly_ctx_set_module_imp_clb(struct ly_ctx *ctx, ly_module_imp_clb clb, void *user_data);
333
334/**
Radek Krejcib7db73a2018-10-24 14:18:40 +0200335 * @brief Get YANG module of the given name and revision.
336 *
337 * @param[in] ctx Context to work in.
338 * @param[in] name Name of the YANG module to get.
339 * @param[in] revision Requested revision date of the YANG module to get. If not specified,
340 * the schema with no revision is returned, if it is present in the context.
341 * @return Pointer to the YANG module, NULL if no schema in the context follows the name and revision requirements.
342 */
Radek Krejci0af46292019-01-11 16:02:31 +0100343struct lys_module *ly_ctx_get_module(const struct ly_ctx *ctx, const char *name, const char *revision);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200344
345/**
346 * @brief Get the latest revision of the YANG module specified by its name.
347 *
348 * YANG modules with no revision are supposed to be the oldest one.
349 *
350 * @param[in] ctx Context where to search.
351 * @param[in] name Name of the YANG module to get.
352 * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the
353 * given name is present in the context.
354 */
Radek Krejci0af46292019-01-11 16:02:31 +0100355struct lys_module *ly_ctx_get_module_latest(const struct ly_ctx *ctx, const char *name);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200356
357/**
358 * @brief Get the (only) implemented YANG module specified by its name.
359 *
360 * @param[in] ctx Context where to search.
361 * @param[in] name Name of the YANG module to get.
362 * @return The only implemented YANG module revision of the given name in the given context. NULL if there is no
363 * implemented module of the given name.
364 */
Radek Krejci0af46292019-01-11 16:02:31 +0100365struct lys_module *ly_ctx_get_module_implemented(const struct ly_ctx *ctx, const char *name);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200366
367/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200368 * @brief Iterate over all modules in the given context.
369 *
370 * @param[in] ctx Context with the modules.
371 * @param[in,out] index Index of the next module to get. Value of 0 starts from the beginning.
372 * The value is updated with each call, so to iterate over all modules the same variable is supposed
373 * to be used in all calls starting with value 0.
374 * @return Next context module, NULL if the last was already returned.
375 */
Radek Krejci1deb5be2020-08-26 16:43:36 +0200376const struct lys_module *ly_ctx_get_module_iter(const struct ly_ctx *ctx, uint32_t *index);
Radek Krejcied5acc52019-04-25 15:57:04 +0200377
378/**
Radek Krejcib7db73a2018-10-24 14:18:40 +0200379 * @brief Get YANG module of the given namespace and revision.
380 *
381 * @param[in] ctx Context to work in.
382 * @param[in] ns Namespace of the YANG module to get.
383 * @param[in] revision Requested revision date of the YANG module to get. If not specified,
384 * the schema with no revision is returned, if it is present in the context.
385 * @return Pointer to the YANG module, NULL if no schema in the context follows the namespace and revision requirements.
386 */
Radek Krejci0af46292019-01-11 16:02:31 +0100387struct 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 +0200388
389/**
390 * @brief Get the latest revision of the YANG module specified by its namespace.
391 *
392 * YANG modules with no revision are supposed to be the oldest one.
393 *
394 * @param[in] ctx Context where to search.
395 * @param[in] ns Namespace of the YANG module to get.
396 * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the
397 * given namespace is present in the context.
398 */
Radek Krejci0af46292019-01-11 16:02:31 +0100399struct lys_module *ly_ctx_get_module_latest_ns(const struct ly_ctx *ctx, const char *ns);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200400
401/**
402 * @brief Get the (only) implemented YANG module specified by its namespace.
403 *
404 * @param[in] ctx Context where to search.
405 * @param[in] ns Namespace of the YANG module to get.
406 * @return The only implemented YANG module revision of the given namespace in the given context. NULL if there is no
407 * implemented module of the given namespace.
408 */
Radek Krejci0af46292019-01-11 16:02:31 +0100409struct lys_module *ly_ctx_get_module_implemented_ns(const struct ly_ctx *ctx, const char *ns);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200410
411/**
Michal Vasko308d0a72020-08-03 11:56:25 +0200412 * @brief Get a schema node based on the given data path (JSON format, see @ref howtoxpath).
413 *
414 * @param[in] ctx libyang context, set for absolute paths.
415 * @param[in] ctx_node Starting context node for a relative data path, set for relative paths.
Michal Vasko6229db02020-10-07 08:54:15 +0200416 * @param[in] path JSON path of the node to get.
Michal Vasko308d0a72020-08-03 11:56:25 +0200417 * @param[in] output Search operation output instead of input.
418 * @return Found schema node or NULL.
419 */
Michal Vasko6229db02020-10-07 08:54:15 +0200420const struct lysc_node *ly_ctx_get_node(const struct ly_ctx *ctx, const struct lysc_node *ctx_node, const char *path,
421 ly_bool output);
Michal Vasko308d0a72020-08-03 11:56:25 +0200422
423/**
Radek Krejcie9e987e2018-10-31 12:50:27 +0100424 * @brief Reset cached latest revision information of the schemas in the context.
425 *
426 * When a (sub)module is imported/included without revision, the latest revision is
427 * searched. libyang searches for the latest revision in searchdirs and/or via provided
428 * import callback ly_module_imp_clb() just once. Then it is expected that the content
429 * of searchdirs or data returned by the callback does not change. So when it changes,
430 * it is necessary to force searching for the latest revision in case of loading another
431 * module, which what this function does.
432 *
433 * The latest revision information is also reset when the searchdirs set changes via
434 * ly_ctx_set_searchdir().
435 *
436 * @param[in] ctx libyang context where the latest revision information is going to be reset.
437 */
438void ly_ctx_reset_latests(struct ly_ctx *ctx);
439
440/**
Michal Vaskode79e222020-08-10 11:55:46 +0200441 * @brief Learn the number of internal modules of a context. Internal modules
442 * is considered one that was loaded during the context creation.
443 *
444 * @param[in] ctx libyang context to examine.
445 * @return Number of internal modules.
446 */
447uint32_t ly_ctx_internal_module_count(const struct ly_ctx *ctx);
448
449/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200450 * @brief Try to find the model in the searchpaths of \p ctx and load it into it. If custom missing
451 * module callback is set, it is used instead.
452 *
453 * The context itself is searched for the requested module first. If \p revision is not specified
454 * (the module of the latest revision is requested) and there is implemented revision of the requested
455 * module in the context, this implemented revision is returned despite there might be a newer revision.
456 * This behavior is cause by the fact that it is not possible to have multiple implemented revisions of
457 * the same module in the context.
458 *
459 * @param[in] ctx Context to add to.
460 * @param[in] name Name of the module to load.
461 * @param[in] revision Optional revision date of the module. If not specified, the latest revision is loaded.
462 * @return Pointer to the data model structure, NULL if not found or some error occurred.
463 */
464const struct lys_module *ly_ctx_load_module(struct ly_ctx *ctx, const char *name, const char *revision);
465
466/**
Michal Vasko57c10cd2020-05-27 15:57:11 +0200467 * @brief Get current ID of the modules set. The value is available also
468 * as module-set-id in ::ly_ctx_get_yanglib_data() result.
469 *
470 * @param[in] ctx Context to be examined.
471 * @return Numeric identifier of the current context's modules set.
472 */
473uint16_t ly_ctx_get_yanglib_id(const struct ly_ctx *ctx);
474
475/**
476 * @brief Get data of the internal ietf-yang-library module with information about all the loaded modules.
477 * ietf-yang-library module must be loaded.
478 *
479 * @param[in] ctx Context with the modules.
Michal Vasko3a41dff2020-07-15 14:30:28 +0200480 * @param[out] root Generated yang-library data.
481 * @return LY_ERR value
Michal Vasko57c10cd2020-05-27 15:57:11 +0200482 */
Michal Vasko3a41dff2020-07-15 14:30:28 +0200483LY_ERR ly_ctx_get_yanglib_data(const struct ly_ctx *ctx, struct lyd_node **root);
Michal Vasko57c10cd2020-05-27 15:57:11 +0200484
485/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200486 * @brief Free all internal structures of the specified context.
487 *
488 * The function should be used before terminating the application to destroy
489 * and free all structures internally used by libyang. If the caller uses
490 * multiple contexts, the function should be called for each used context.
491 *
492 * All instance data are supposed to be freed before destroying the context.
493 * Data models are destroyed automatically as part of ly_ctx_destroy() call.
494 *
495 * @param[in] ctx libyang context to destroy
496 * @param[in] private_destructor Optional destructor function for private objects assigned
497 * to the nodes via lys_set_private(). If NULL, the private objects are not freed by libyang.
498 * Remember the differences between the structures derived from ::lysc_node and always check
499 * ::lysc_node#nodetype.
500 */
501void ly_ctx_destroy(struct ly_ctx *ctx, void (*private_destructor)(const struct lysc_node *node, void *priv));
502
503/** @} context */
504
505#ifdef __cplusplus
506}
507#endif
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200508
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200509#endif /* LY_CONTEXT_H_ */