blob: f8260bf3320fb27a22d4a1bbb9ba5d5bb22887d4 [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 Krejci5aeea3a2018-09-05 13:29:36 +020021#include "tree_schema.h"
22
Radek Krejci6caa6ab2018-10-24 10:04:48 +020023#ifdef __cplusplus
24extern "C" {
25#endif
26
Radek Krejci5aeea3a2018-09-05 13:29:36 +020027/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +020028 * @defgroup context Context
29 * @{
30 *
31 * Structures and functions to manipulate with the libyang "containers". The \em context concept allows callers
32 * to work in environments with different sets of YANG schemas. More detailed information can be found at
33 * @ref howtocontext page.
Radek Krejci5aeea3a2018-09-05 13:29:36 +020034 */
Radek Krejci6caa6ab2018-10-24 10:04:48 +020035
36/**
37 * @struct ly_ctx
38 * @brief libyang context handler.
39 */
40struct ly_ctx;
41
42/**
43 * @defgroup contextoptions Context options
44 * @ingroup context
45 *
46 * Options to change context behavior.
Radek Krejci474f9b82019-07-24 11:36:37 +020047 *
48 * Note that the flags 0xFF00 are reserved for internal use.
49 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +020050 * @{
51 */
52
53#define LY_CTX_ALLIMPLEMENTED 0x01 /**< All the imports of the schema being parsed are treated implemented. */
54#define LY_CTX_TRUSTED 0x02 /**< Handle the schema being parsed as trusted and skip its validation
55 tests. Note that while this option improves performance, it can
56 lead to an undefined behavior if the schema is not correct. */
57#define LY_CTX_NOYANGLIBRARY 0x04 /**< Do not internally implement ietf-yang-library module. The option
58 causes that function ly_ctx_info() does not work (returns NULL) until
59 the ietf-yang-library module is loaded manually. While any revision
60 of this schema can be loaded with this option, note that the only
61 revisions implemented by ly_ctx_info() are 2016-04-09 and 2018-01-17.
62 This option cannot be changed on existing context. */
63#define LY_CTX_DISABLE_SEARCHDIRS 0x08 /**< Do not search for schemas in context's searchdirs neither in current
64 working directory. It is entirely skipped and the only way to get
65 schema data for imports or for ly_ctx_load_module() is to use the
66 callbacks provided by caller via ly_ctx_set_module_imp_clb() */
67#define LY_CTX_DISABLE_SEARCHDIR_CWD 0x10 /**< Do not automatically search for schemas in current working
68 directory, which is by default searched automatically (despite not
69 recursively). */
70#define LY_CTX_PREFER_SEARCHDIRS 0x20 /**< When searching for schema, prefer searchdirs instead of user callback. */
Radek Krejci0af46292019-01-11 16:02:31 +010071
Radek Krejci6caa6ab2018-10-24 10:04:48 +020072/**@} contextoptions */
73
74/**
75 * @brief Create libyang context.
76 *
77 * Context is used to hold all information about schemas. Usually, the application is supposed
78 * to work with a single context in which libyang is holding all schemas (and other internal
79 * information) according to which the data trees will be processed and validated. So, the schema
80 * trees are tightly connected with the specific context and they are held by the context internally
81 * - caller does not need to keep pointers to the schemas returned by lys_parse(), context knows
82 * about them. The data trees created with lyd_parse() are still connected with the specific context,
83 * but they are not internally held by the context. The data tree just points and lean on some data
84 * held by the context (schema tree, string dictionary, etc.). Therefore, in case of data trees, caller
85 * is supposed to keep pointers returned by the lyd_parse() and manage the data tree on its own. This
86 * also affects the number of instances of both tree types. While you can have only one instance of
87 * specific schema connected with a single context, number of data tree instances is not connected.
88 *
89 * @param[in] search_dir Directory where libyang will search for the imported or included modules
90 * and submodules. If no such directory is available, NULL is accepted.
91 * @param[in] options Context options, see @ref contextoptions.
92 * @param[out] new_ctx Pointer to the created libyang context if LY_SUCCESS returned.
93 * @return LY_ERR return value.
94 */
95LY_ERR ly_ctx_new(const char *search_dir, int options, struct ly_ctx **new_ctx);
96
97/**
98 * @brief Add the search path into libyang context
99 *
100 * To reset search paths set in the context, use ly_ctx_unset_searchdirs() and then
101 * set search paths again.
102 *
103 * @param[in] ctx Context to be modified.
104 * @param[in] search_dir New search path to add to the current paths previously set in ctx.
105 * @return LY_ERR return value.
106 */
107LY_ERR ly_ctx_set_searchdir(struct ly_ctx *ctx, const char *search_dir);
108
109/**
110 * @brief Clean the search path(s) from the libyang context
111 *
Radek Krejcied5acc52019-04-25 15:57:04 +0200112 * To remove the search path by its index, use ly_ctx_unset_searchdir().
113 *
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200114 * @param[in] ctx Context to be modified.
115 * @param[in] value Searchdir to be removed, use NULL to remove them all.
116 * @return LY_ERR return value
117 */
118LY_ERR ly_ctx_unset_searchdirs(struct ly_ctx *ctx, const char *value);
119
120/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200121 * @brief Remove the specific search path from the libyang context.
122 *
123 * To remove the search path by its value, use ly_ctx_unset_searchdirs().
124 *
125 * @param[in] ctx Context to be modified.
126 * @param[in] index Index of the searchdir to be removed.
127 * @return LY_ERR return value
128 */
129LY_ERR ly_ctx_unset_searchdir(struct ly_ctx *ctx, unsigned int index);
130
131/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200132 * @brief Get the NULL-terminated list of the search paths in libyang context. Do not modify the result!
133 *
134 * @param[in] ctx Context to query.
135 * @return NULL-terminated list (array) of the search paths, NULL if no searchpath was set.
136 * Do not modify the provided data in any way!
137 */
138const char * const *ly_ctx_get_searchdirs(const struct ly_ctx *ctx);
139
140/**
141 * @brief Get the currently set context's options.
142 *
143 * @param[in] ctx Context to query.
144 * @return Combination of all the currently set context's options, see @ref contextoptions.
145 */
146int ly_ctx_get_options(const struct ly_ctx *ctx);
147
148/**
149 * @brief Set some of the context's options, see @ref contextoptions.
150 * @param[in] ctx Context to be modified.
151 * @param[in] option Combination of the context's options to be set, see @ref contextoptions.
152 * @return LY_ERR value.
153 */
154LY_ERR ly_ctx_set_option(struct ly_ctx *ctx, int option);
155
156/**
157 * @brief Unset some of the context's options, see @ref contextoptions.
158 * @param[in] ctx Context to be modified.
159 * @param[in] option Combination of the context's options to be unset, see @ref contextoptions.
160 * @return LY_ERR value.
161 */
162LY_ERR ly_ctx_unset_option(struct ly_ctx *ctx, int option);
163
164/**
165 * @brief Get current ID of the modules set. The value is available also
166 * as module-set-id in ly_ctx_info() result.
167 *
168 * @param[in] ctx Context to be examined.
169 * @return Numeric identifier of the current context's modules set.
170 */
171uint16_t ly_ctx_get_module_set_id(const struct ly_ctx *ctx);
172
173/**
Radek Krejcid33273d2018-10-25 14:55:52 +0200174 * @brief Callback for retrieving missing included or imported models in a custom way.
175 *
176 * When submod_name is provided, the submodule is requested instead of the module (in this case only
177 * the module name without its revision is provided).
178 *
179 * If an @arg free_module_data callback is provided, it will be used later to free the allegedly const data
180 * which were returned by this callback.
181 *
182 * @param[in] mod_name Missing module name.
Radek Krejci086c7132018-10-26 15:29:04 +0200183 * @param[in] mod_rev Optional missing module revision. If NULL and submod_name is not provided, the latest revision is
184 * requested, the parsed module is then marked by the latest_revision flag.
Radek Krejcid33273d2018-10-25 14:55:52 +0200185 * @param[in] submod_name Optional missing submodule name.
Radek Krejci086c7132018-10-26 15:29:04 +0200186 * @param[in] submod_rev Optional missing submodule revision. If NULL and submod_name is provided, the latest revision is
187 * requested, the parsed submodule is then marked by the latest_revision flag.
Radek Krejcid33273d2018-10-25 14:55:52 +0200188 * @param[in] user_data User-supplied callback data.
189 * @param[out] format Format of the returned module data.
190 * @param[out] module_data Requested module data.
191 * @param[out] free_module_data Callback for freeing the returned module data. If not set, the data will be left untouched.
192 * @return LY_ERR value. If the returned value differs from LY_SUCCESS, libyang continue in trying to get the module data
193 * according to the settings of its mechanism to search for the imported/included schemas.
194 */
195typedef LY_ERR (*ly_module_imp_clb)(const char *mod_name, const char *mod_rev, const char *submod_name, const char *sub_rev,
196 void *user_data, LYS_INFORMAT *format, const char **module_data,
197 void (**free_module_data)(void *model_data, void *user_data));
198
199/**
200 * @brief Get the custom callback for missing import/include module retrieval.
201 *
202 * @param[in] ctx Context to read from.
203 * @param[in] user_data Optional pointer for getting the user-supplied callback data.
204 * @return Callback or NULL if not set.
205 */
206ly_module_imp_clb ly_ctx_get_module_imp_clb(const struct ly_ctx *ctx, void **user_data);
207
208/**
209 * @brief Set missing include or import module callback. It is meant to be used when the models
210 * are not locally available (such as when downloading modules from a NETCONF server), it should
211 * not be required in other cases.
212 *
213 * @param[in] ctx Context that will use this callback.
214 * @param[in] clb Callback responsible for returning the missing model.
215 * @param[in] user_data Arbitrary data that will always be passed to the callback \p clb.
216 */
217void ly_ctx_set_module_imp_clb(struct ly_ctx *ctx, ly_module_imp_clb clb, void *user_data);
218
219/**
Radek Krejcib7db73a2018-10-24 14:18:40 +0200220 * @brief Get YANG module of the given name and revision.
221 *
222 * @param[in] ctx Context to work in.
223 * @param[in] name Name of the YANG module to get.
224 * @param[in] revision Requested revision date of the YANG module to get. If not specified,
225 * the schema with no revision is returned, if it is present in the context.
226 * @return Pointer to the YANG module, NULL if no schema in the context follows the name and revision requirements.
227 */
Radek Krejci0af46292019-01-11 16:02:31 +0100228struct lys_module *ly_ctx_get_module(const struct ly_ctx *ctx, const char *name, const char *revision);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200229
230/**
231 * @brief Get the latest revision of the YANG module specified by its name.
232 *
233 * YANG modules with no revision are supposed to be the oldest one.
234 *
235 * @param[in] ctx Context where to search.
236 * @param[in] name Name of the YANG module to get.
237 * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the
238 * given name is present in the context.
239 */
Radek Krejci0af46292019-01-11 16:02:31 +0100240struct lys_module *ly_ctx_get_module_latest(const struct ly_ctx *ctx, const char *name);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200241
242/**
243 * @brief Get the (only) implemented YANG module specified by its name.
244 *
245 * @param[in] ctx Context where to search.
246 * @param[in] name Name of the YANG module to get.
247 * @return The only implemented YANG module revision of the given name in the given context. NULL if there is no
248 * implemented module of the given name.
249 */
Radek Krejci0af46292019-01-11 16:02:31 +0100250struct lys_module *ly_ctx_get_module_implemented(const struct ly_ctx *ctx, const char *name);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200251
252/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200253 * @brief Get the (only) implemented YANG module specified by its name.
254 *
255 * @param[in] ctx Context where to search.
256 * @param[in] name Name of the YANG module to get.
257 * @return The only implemented YANG module revision of the given name in the given context. NULL if there is no
258 * implemented module of the given name.
259 */
260/**
261 * @brief Iterate over all modules in the given context.
262 *
263 * @param[in] ctx Context with the modules.
264 * @param[in,out] index Index of the next module to get. Value of 0 starts from the beginning.
265 * The value is updated with each call, so to iterate over all modules the same variable is supposed
266 * to be used in all calls starting with value 0.
267 * @return Next context module, NULL if the last was already returned.
268 */
269const struct lys_module *ly_ctx_get_module_iter(const struct ly_ctx *ctx, unsigned int *index);
270
271/**
Radek Krejcib7db73a2018-10-24 14:18:40 +0200272 * @brief Get YANG module of the given namespace and revision.
273 *
274 * @param[in] ctx Context to work in.
275 * @param[in] ns Namespace of the YANG module to get.
276 * @param[in] revision Requested revision date of the YANG module to get. If not specified,
277 * the schema with no revision is returned, if it is present in the context.
278 * @return Pointer to the YANG module, NULL if no schema in the context follows the namespace and revision requirements.
279 */
Radek Krejci0af46292019-01-11 16:02:31 +0100280struct 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 +0200281
282/**
283 * @brief Get the latest revision of the YANG module specified by its namespace.
284 *
285 * YANG modules with no revision are supposed to be the oldest one.
286 *
287 * @param[in] ctx Context where to search.
288 * @param[in] ns Namespace of the YANG module to get.
289 * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the
290 * given namespace is present in the context.
291 */
Radek Krejci0af46292019-01-11 16:02:31 +0100292struct lys_module *ly_ctx_get_module_latest_ns(const struct ly_ctx *ctx, const char *ns);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200293
294/**
295 * @brief Get the (only) implemented YANG module specified by its namespace.
296 *
297 * @param[in] ctx Context where to search.
298 * @param[in] ns Namespace of the YANG module to get.
299 * @return The only implemented YANG module revision of the given namespace in the given context. NULL if there is no
300 * implemented module of the given namespace.
301 */
Radek Krejci0af46292019-01-11 16:02:31 +0100302struct lys_module *ly_ctx_get_module_implemented_ns(const struct ly_ctx *ctx, const char *ns);
Radek Krejcib7db73a2018-10-24 14:18:40 +0200303
304/**
Radek Krejcie9e987e2018-10-31 12:50:27 +0100305 * @brief Reset cached latest revision information of the schemas in the context.
306 *
307 * When a (sub)module is imported/included without revision, the latest revision is
308 * searched. libyang searches for the latest revision in searchdirs and/or via provided
309 * import callback ly_module_imp_clb() just once. Then it is expected that the content
310 * of searchdirs or data returned by the callback does not change. So when it changes,
311 * it is necessary to force searching for the latest revision in case of loading another
312 * module, which what this function does.
313 *
314 * The latest revision information is also reset when the searchdirs set changes via
315 * ly_ctx_set_searchdir().
316 *
317 * @param[in] ctx libyang context where the latest revision information is going to be reset.
318 */
319void ly_ctx_reset_latests(struct ly_ctx *ctx);
320
321/**
Radek Krejci0af46292019-01-11 16:02:31 +0100322 * @brief Make the specific module implemented.
323 *
324 * @param[in] ctx libyang context to change.
325 * @param[in] mod Module from the given context to make implemented. It is not an error
326 * to provide already implemented module, it just does nothing.
327 * @return LY_SUCCESS or LY_EDENIED in case the context contains some other revision of the
328 * same module which is already implemented.
329 */
330LY_ERR ly_ctx_module_implement(struct ly_ctx *ctx, struct lys_module *mod);
331
332/**
Radek Krejcied5acc52019-04-25 15:57:04 +0200333 * @brief Try to find the model in the searchpaths of \p ctx and load it into it. If custom missing
334 * module callback is set, it is used instead.
335 *
336 * The context itself is searched for the requested module first. If \p revision is not specified
337 * (the module of the latest revision is requested) and there is implemented revision of the requested
338 * module in the context, this implemented revision is returned despite there might be a newer revision.
339 * This behavior is cause by the fact that it is not possible to have multiple implemented revisions of
340 * the same module in the context.
341 *
342 * @param[in] ctx Context to add to.
343 * @param[in] name Name of the module to load.
344 * @param[in] revision Optional revision date of the module. If not specified, the latest revision is loaded.
345 * @return Pointer to the data model structure, NULL if not found or some error occurred.
346 */
347const struct lys_module *ly_ctx_load_module(struct ly_ctx *ctx, const char *name, const char *revision);
348
349/**
Radek Krejci6caa6ab2018-10-24 10:04:48 +0200350 * @brief Free all internal structures of the specified context.
351 *
352 * The function should be used before terminating the application to destroy
353 * and free all structures internally used by libyang. If the caller uses
354 * multiple contexts, the function should be called for each used context.
355 *
356 * All instance data are supposed to be freed before destroying the context.
357 * Data models are destroyed automatically as part of ly_ctx_destroy() call.
358 *
359 * @param[in] ctx libyang context to destroy
360 * @param[in] private_destructor Optional destructor function for private objects assigned
361 * to the nodes via lys_set_private(). If NULL, the private objects are not freed by libyang.
362 * Remember the differences between the structures derived from ::lysc_node and always check
363 * ::lysc_node#nodetype.
364 */
365void ly_ctx_destroy(struct ly_ctx *ctx, void (*private_destructor)(const struct lysc_node *node, void *priv));
366
367/** @} context */
368
369#ifdef __cplusplus
370}
371#endif
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200372
Radek Krejci5aeea3a2018-09-05 13:29:36 +0200373#endif /* LY_CONTEXT_H_ */