diff options
Diffstat (limited to 'src/context.h')
| -rw-r--r-- | src/context.h | 673 |
1 files changed, 673 insertions, 0 deletions
diff --git a/src/context.h b/src/context.h new file mode 100644 index 0000000..31f41b9 --- /dev/null +++ b/src/context.h @@ -0,0 +1,673 @@ +/** + * @file context.h + * @author Radek Krejci <rkrejci@cesnet.cz> + * @author Michal Vasko <mvasko@cesnet.cz> + * @brief internal context structures and functions + * + * Copyright (c) 2015 - 2023 CESNET, z.s.p.o. + * + * This source code is licensed under BSD 3-Clause License (the "License"). + * You may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://opensource.org/licenses/BSD-3-Clause + */ + +#ifndef LY_CONTEXT_H_ +#define LY_CONTEXT_H_ + +#include <stdint.h> + +#include "log.h" +#include "parser_schema.h" +#include "tree_data.h" + +#ifdef __cplusplus +extern "C" { +#endif + +struct lys_module; + +/** + * @page howtoContext Context + * + * The context concept allows callers to work in environments with different sets of YANG modules. + * + * The first step with libyang is to create a new context using ::ly_ctx_new(). It returns a handler used in the following work. + * Note that the context is supposed to provide a stable environment for work with the data. Therefore the caller should prepare + * a complete context and after starting working with the data, the context and its content should not change. If it does, + * in most cases it leads to the context being recompiled and any parsed data invalid. Despite the API not enforcing this + * approach, it may change in future versions in the form of a locking mechanism which would allow further + * optimization of data manipulation. Also note that modules cannot be removed from their context. If you need to change the set + * 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. + * + * The context has [several options](@ref contextoptions) changing behavior when processing YANG modules being inserted. The + * specific behavior is mentioned below. All the options can be set as a parameter when the context is being created or later + * with ::ly_ctx_set_options(). + * + * When creating a new context, another optional parameter is search_dir It provide directory where libyang + * will automatically search for YANG modules being imported or included. There is actually a set of search paths which can be later + * modified using ::ly_ctx_set_searchdir(), ::ly_ctx_unset_searchdir() and ::ly_ctx_unset_searchdir_last() functions. Before the values + * in the set are used, also the current working directory is (non-recursively) searched. For the case of the explicitly set + * search directories, they are searched recursively - all their subdirectories (and symlinks) are taken into account. Searching + * in the current working directory can be avoided with the context's ::LY_CTX_DISABLE_SEARCHDIR_CWD option. + * Searching in all the context's search dirs (without removing them) can be avoided with the context's + * ::LY_CTX_DISABLE_SEARCHDIRS option (or via ::ly_ctx_set_options()). This automatic searching can be preceded + * by a custom module searching callback (::ly_module_imp_clb) set via ::ly_ctx_set_module_imp_clb(). The algorithm of + * searching in search dirs is also available via API as ::lys_search_localfile() function. + * + * YANG modules are added into the context using [parser functions](@ref howtoSchemaParsers) - \b lys_parse*(). + * Alternatively, also ::ly_ctx_load_module() can be used - in that case the ::ly_module_imp_clb or automatic + * search in search directories and in the current working directory is used, as described above. YANG submodules cannot be loaded + * or even validated directly, they are loaded always only as includes of YANG modules. Explicitly parsed/loaded modules are + * handled as implemented - libyang is able to instantiate data representing such a module. The modules loaded implicitly, are + * not implemented and serve only as a source of grouping or typedef definitions. Context can hold multiple revisions of the same + * YANG module, but only one of them can be implemented. Details about the difference between implemented and imported modules + * can be found on @ref howtoSchema page. This behavior can be changed with the context's ::LY_CTX_ALL_IMPLEMENTED option, which + * causes that all the parsed modules, whether loaded explicitly or implicitly, are set to be implemented. Note, that as + * a consequence of this option, only a single revision of any module can be present in the context in this case. Also, a less + * crude option ::LY_CTX_REF_IMPLEMENTED can be used to implement only referenced modules that should also be implemented. + * + * When loading/importing a module without revision, the latest revision of the required module is supposed to load. + * For a context, the first time the latest revision of a module is requested, it is properly searched for and loaded. + * However, when this module is requested (without revision) the second time, the one found previously is returned. + * This has the advantage of not searching for the module repeatedly but there is a drawback in case the content of search + * directories is updated and a later revision become available. + * + * Context holds all the schema modules internally. To get a specific module, use ::ly_ctx_get_module() (or some of its + * variants). If you need to do something with all the modules in the context, it is advised to iterate over them using + * ::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 + * in the form of data tree defined by <a href="https://tools.ietf.org/html/rfc7895">ietf-yang-library</a> module. + * + * YANG data can be parsed by \b lyd_parse_*() functions. Note, that functions for schema have \b lys_ + * prefix (or \b lysp_ for the parsed and \b lysc_ for the compiled schema - for details see @ref howtoSchema page) while + * functions for instance data have \b lyd_ prefix. Details about data formats or handling data without the appropriate + * YANG module in context can be found on @ref howtoData page. + * + * Besides the YANG modules, context holds also [error information](@ref howtoErrors) and + * [database of strings](@ref howtoContextDict), both connected with the processed YANG modules and data. + * + * - @subpage howtoErrors + * - @subpage howtoContextDict + * + * \note API for this group of functions is available in the [context module](@ref context). + * + * Functions List + * -------------- + * + * - ::ly_ctx_new() + * - ::ly_ctx_destroy() + * + * - ::ly_ctx_set_searchdir() + * - ::ly_ctx_get_searchdirs() + * - ::ly_ctx_unset_searchdir() + * - ::ly_ctx_unset_searchdir_last() + * + * - ::ly_ctx_set_options() + * - ::ly_ctx_get_options() + * - ::ly_ctx_unset_options() + * + * - ::ly_ctx_set_module_imp_clb() + * - ::ly_ctx_get_module_imp_clb() + * + * - ::ly_ctx_load_module() + * - ::ly_ctx_get_module_iter() + * - ::ly_ctx_get_module() + * - ::ly_ctx_get_module_ns() + * - ::ly_ctx_get_module_implemented() + * - ::ly_ctx_get_module_implemented_ns() + * - ::ly_ctx_get_module_latest() + * - ::ly_ctx_get_module_latest_ns() + * - ::ly_ctx_get_submodule() + * - ::ly_ctx_get_submodule_latest() + * - ::ly_ctx_get_submodule2() + * - ::ly_ctx_get_submodule2_latest() + * + * - ::ly_ctx_get_yanglib_data() + * + * - ::ly_ctx_get_change_count() + * - ::ly_ctx_internal_modules_count() + * + * - ::lys_search_localfile() + * - ::lys_set_implemented() + * + */ + +/** + * @defgroup context Context + * @{ + * + * Structures and functions to manipulate with the libyang context containers. + * + * The \em context concept allows callers to work in environments with different sets of YANG schemas. + * More detailed information can be found at @ref howtoContext page. + */ + +/** + * @struct ly_ctx + * @brief libyang context handler. + */ +struct ly_ctx; + +/** + * @ingroup context + * @defgroup contextoptions Context options + * + * Options to change context behavior. + * + * @{ + */ + +#define LY_CTX_ALL_IMPLEMENTED 0x01 /**< All the imported modules of the schema being parsed are implemented. */ +#define LY_CTX_REF_IMPLEMENTED 0x02 /**< Implement all imported modules "referenced" from an implemented module. + Normally, leafrefs, augment and deviation targets are implemented as + specified by YANG 1.1. In addition to this, implement any modules of + nodes referenced by when and must conditions and by any default values. + Generally, only if all these modules are implemented, the explicitly + implemented modules can be properly used and instantiated in data. */ +#define LY_CTX_NO_YANGLIBRARY 0x04 /**< Do not internally implement ietf-yang-library module. The option + causes that function ::ly_ctx_get_yanglib_data() does not work (returns ::LY_EINVAL) until + the ietf-yang-library module is loaded manually. While any revision + of this schema can be loaded with this option, note that the only + revisions implemented by ::ly_ctx_get_yanglib_data() are 2016-06-21 and 2019-01-04. + This option cannot be changed on existing context. */ +#define LY_CTX_DISABLE_SEARCHDIRS 0x08 /**< Do not search for schemas in context's searchdirs neither in current + working directory. It is entirely skipped and the only way to get + schema data for imports or for ::ly_ctx_load_module() is to use the + callbacks provided by caller via ::ly_ctx_set_module_imp_clb() */ +#define LY_CTX_DISABLE_SEARCHDIR_CWD 0x10 /**< Do not automatically search for schemas in current working + directory, which is by default searched automatically (despite not + recursively). */ +#define LY_CTX_PREFER_SEARCHDIRS 0x20 /**< When searching for schema, prefer searchdirs instead of user callback. */ +#define LY_CTX_SET_PRIV_PARSED 0x40 /**< For all compiled nodes, their private objects (::lysc_node.priv) are used + by libyang as a reference to the corresponding parsed node (::lysp_node). + The exception are \"case\" statements, which are omitted (shorthand), + in that case the private objects are set to NULL. + So if this option is set, the user must not change private objects. + Setting this option by ::ly_ctx_set_options() may result in context recompilation. + Resetting this option by ::ly_ctx_unset_options() cause that private + objects will be set to NULL. */ +#define LY_CTX_EXPLICIT_COMPILE 0x80 /**< If this flag is set, the compiled modules and their schema nodes are + not automatically updated (compiled) on any context changes. In other words, they do + not immediately take effect. To do that, call ::ly_ctx_compile(). Changes + requiring compilation include adding new modules, changing their features, + and implementing parsed-only modules. This option allows efficient compiled + context creation without redundant recompilations. */ +#define LY_CTX_ENABLE_IMP_FEATURES 0x0100 /**< By default, all features of newly implemented imported modules of + a module that is being loaded are disabled. With this flag they all become + enabled. */ +#define LY_CTX_LEAFREF_EXTENDED 0x0200 /**< By default, path attribute of leafref accepts only path as defined in RFC 7950. + By using this option, the path attribute will also allow using XPath functions as deref() */ +#define LY_CTX_LEAFREF_LINKING 0x0400 /**< Link valid leafref nodes with its target during validation if leafref node is not using + 'require-instance false;'. It also enables usage of + [lyd_leafref_get_links](@ref lyd_leafref_get_links) and + [lyd_leafref_link_node_tree](@ref lyd_leafref_link_node_tree) APIs. */ +#define LY_CTX_BUILTIN_PLUGINS_ONLY 0x0800 /**< By default, context uses all available plugins for types and extensions, + both included and external. This options prevents all included plugins to be + loaded except for built-in YANG types so all derived types will use these and + for all purposes behave as the base type. The option can be used for cases when + invalid data needs to be stored in YANG node values. */ + +/** @} contextoptions */ + +/** + * @brief Create libyang context. + * + * Context is used to hold all information about schemas. Usually, the application is supposed + * to work with a single context in which libyang is holding all schemas (and other internal + * information) according to which the data trees will be processed and validated. So, the schema + * trees are tightly connected with the specific context and they are held by the context internally + * - caller does not need to keep pointers to the schemas returned by ::lys_parse(), context knows + * about them. The data trees created with \b lyd_parse_*() are still connected with the specific context, + * but they are not internally held by the context. The data tree just points and lean on some data + * held by the context (schema tree, string dictionary, etc.). Therefore, in case of data trees, caller + * is supposed to keep pointers returned by the \b lyd_parse_*() functions and manage the data tree on its own. This + * also affects the number of instances of both tree types. While you can have only one instance of + * specific schema connected with a single context, number of data tree instances is not connected. + * + * @param[in] search_dir Directory (or directories) where libyang will search for the imported or included modules + * and submodules. If no such directory is available, NULL is accepted. Several directories can be specified, + * delimited by colon ":" (on Windows, use semicolon ";" instead). + * @param[in] options Context options, see @ref contextoptions. + * @param[out] new_ctx Pointer to the created libyang context if LY_SUCCESS returned. + * @return LY_ERR return value. + */ +LIBYANG_API_DECL LY_ERR ly_ctx_new(const char *search_dir, uint16_t options, struct ly_ctx **new_ctx); + +/** + * @brief Create libyang context according to the provided yang-library data in a file. + * + * This function loads the yang-library data from the given path. If you need to pass the data as + * string, use ::::ly_ctx_new_ylmem(). Both functions extend functionality of ::ly_ctx_new() by loading + * modules specified in the ietf-yang-library form into the context being created. + * The preferred tree model revision is 2019-01-04. However, only the first module-set is processed and loaded + * into the context. If there are no matching nodes from this tree, the legacy tree (originally from model revision 2016-04-09) + * 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 + * yang-library data are ignored and the modules are loaded from the context's search locations. On the other hand, YANG features + * of the modules are set as specified in the yang-library data. + * To get yang library data from a libyang context, use ::ly_ctx_get_yanglib_data(). + * + * @param[in] search_dir Directory where libyang will search for the imported or included modules and submodules. + * If no such directory is available, NULL is accepted. + * @param[in] path Path to the file containing yang-library-data in the specified format + * @param[in] format Format of the data in the provided file. + * @param[in] options Context options, see @ref contextoptions. + * @param[in,out] ctx If *ctx is not NULL, the existing libyang context is modified. Otherwise, a pointer to a + * newly created context is returned here if LY_SUCCESS. + * @return LY_ERR return value + */ +LIBYANG_API_DECL LY_ERR ly_ctx_new_ylpath(const char *search_dir, const char *path, LYD_FORMAT format, int options, + struct ly_ctx **ctx); + +/** + * @brief Create libyang context according to the provided yang-library data in a string. + * + * Details in ::ly_ctx_new_ylpath(). + * + * @param[in] search_dir Directory where libyang will search for the imported or included modules and submodules. + * If no such directory is available, NULL is accepted. + * @param[in] data String containing yang-library data in the specified format. + * @param[in] format Format of the data in the provided file. + * @param[in] options Context options, see @ref contextoptions. + * @param[in,out] ctx If *ctx is not NULL, the existing libyang context is modified. Otherwise, a pointer to a + * newly created context is returned here if LY_SUCCESS. + * @return LY_ERR return value + */ +LIBYANG_API_DECL LY_ERR ly_ctx_new_ylmem(const char *search_dir, const char *data, LYD_FORMAT format, int options, + struct ly_ctx **ctx); + +/** + * @brief Create libyang context according to the provided yang-library data in a data tree. + * + * Details in ::ly_ctx_new_ylpath(). + * + * @param[in] search_dir Directory where libyang will search for the imported or included modules and submodules. + * If no such directory is available, NULL is accepted. + * @param[in] tree Data tree containing yang-library data. + * @param[in] options Context options, see @ref contextoptions. + * @param[in,out] ctx If *ctx is not NULL, the existing libyang context is modified. Otherwise, a pointer to a + * newly created context is returned here if LY_SUCCESS. + * @return LY_ERR return value + */ +LIBYANG_API_DECL LY_ERR ly_ctx_new_yldata(const char *search_dir, const struct lyd_node *tree, int options, + struct ly_ctx **ctx); + +/** + * @brief Compile (recompile) the context applying all the performed changes after the last context compilation. + * Should be used only if ::LY_CTX_EXPLICIT_COMPILE option is set, has no effect otherwise. + * + * @param[in] ctx Context to compile. + * @return LY_ERR return value. + */ +LIBYANG_API_DECL LY_ERR ly_ctx_compile(struct ly_ctx *ctx); + +/** + * @brief Add the search path into libyang context + * + * To reset search paths set in the context, use ::ly_ctx_unset_searchdir() and then + * set search paths again. + * + * @param[in] ctx Context to be modified. + * @param[in] search_dir New search path to add to the current paths previously set in ctx. + * @return LY_ERR return value. + */ +LIBYANG_API_DECL LY_ERR ly_ctx_set_searchdir(struct ly_ctx *ctx, const char *search_dir); + +/** + * @brief Clean the search path(s) from the libyang context + * + * To remove the recently added search path(s), use ::ly_ctx_unset_searchdir_last(). + * + * @param[in] ctx Context to be modified. + * @param[in] value Searchdir to be removed, use NULL to remove them all. + * @return LY_ERR return value + */ +LIBYANG_API_DECL LY_ERR ly_ctx_unset_searchdir(struct ly_ctx *ctx, const char *value); + +/** + * @brief Remove the least recently added search path(s) from the libyang context. + * + * To remove a specific search path by its value, use ::ly_ctx_unset_searchdir(). + * + * @param[in] ctx Context to be modified. + * @param[in] count Number of the searchdirs to be removed (starting by the least recently added). + * If the value is higher then the actual number of search paths, all paths are removed and no error is returned. + * Value 0 does not change the search path set. + * @return LY_ERR return value + */ +LIBYANG_API_DECL LY_ERR ly_ctx_unset_searchdir_last(struct ly_ctx *ctx, uint32_t count); + +/** + * @brief Get the NULL-terminated list of the search paths in libyang context. Do not modify the result! + * + * @param[in] ctx Context to query. + * @return NULL-terminated list (array) of the search paths, NULL if no searchpath was set. + * Do not modify the provided data in any way! + */ +LIBYANG_API_DECL const char * const *ly_ctx_get_searchdirs(const struct ly_ctx *ctx); + +/** + * @brief Get the currently set context's options. + * + * @param[in] ctx Context to query. + * @return Combination of all the currently set context's options, see @ref contextoptions. + */ +LIBYANG_API_DECL uint16_t ly_ctx_get_options(const struct ly_ctx *ctx); + +/** + * @brief Set some of the context's options, see @ref contextoptions. + * @param[in] ctx Context to be modified. + * @param[in] option Combination of the context's options to be set, see @ref contextoptions. + * If there is to be a change to ::LY_CTX_SET_PRIV_PARSED, the context will be recompiled + * and all ::lysc_node.priv in the modules will be overwritten, see ::LY_CTX_SET_PRIV_PARSED. + * @return LY_ERR value. + */ +LIBYANG_API_DECL LY_ERR ly_ctx_set_options(struct ly_ctx *ctx, uint16_t option); + +/** + * @brief Unset some of the context's options, see @ref contextoptions. + * @param[in] ctx Context to be modified. + * @param[in] option Combination of the context's options to be unset, see @ref contextoptions. + * @return LY_ERR value. + */ +LIBYANG_API_DECL LY_ERR ly_ctx_unset_options(struct ly_ctx *ctx, uint16_t option); + +/** + * @brief Get the change count of the context (module set) during its life-time. + * + * @param[in] ctx Context to be examined. + * @return Context change count. + */ +LIBYANG_API_DECL uint16_t ly_ctx_get_change_count(const struct ly_ctx *ctx); + +/** + * @brief Get the hash of all the modules in the context. Since order of the modules is significant, + * even when 2 contexts have the same modules but loaded in a different order, the hash will differ. + * + * Hash consists of all module names (1), their revisions (2), all enabled features (3), and their + * imported/implemented state (4). + * + * @param[in] ctx Context to be examined. + * @return Context modules hash. + */ +LIBYANG_API_DECL uint32_t ly_ctx_get_modules_hash(const struct ly_ctx *ctx); + +/** + * @brief Callback for freeing returned module data in #ly_module_imp_clb. + * + * @param[in] module_data Data to free. + * @param[in] user_data User-supplied callback data, same as for #ly_module_imp_clb. + */ +typedef void (*ly_module_imp_data_free_clb)(void *module_data, void *user_data); + +/** + * @brief Callback for retrieving missing included or imported models in a custom way. + * + * When @p submod_name is provided, the submodule is requested instead of the module (in this case only + * the module name without its revision is provided). + * + * If an @arg free_module_data callback is provided, it will be used later to free the allegedly const data + * which were returned by this callback. + * + * @param[in] mod_name Missing module name. + * @param[in] mod_rev Optional missing module revision. If NULL and submod_name is not provided, the latest revision is + * requested, the parsed module is then marked by the latest_revision flag. + * @param[in] submod_name Optional missing submodule name. + * @param[in] submod_rev Optional missing submodule revision. If NULL and submod_name is provided, the latest revision is + * requested, the parsed submodule is then marked by the latest_revision flag. + * @param[in] user_data User-supplied callback data. + * @param[out] format Format of the returned module data. + * @param[out] module_data Requested module data. + * @param[out] free_module_data Callback for freeing the returned module data. If not set, the data will be left untouched. + * @return LY_ERR value. If the returned value differs from LY_SUCCESS, libyang continue in trying to get the module data + * according to the settings of its mechanism to search for the imported/included schemas. + */ +typedef LY_ERR (*ly_module_imp_clb)(const char *mod_name, const char *mod_rev, const char *submod_name, const char *submod_rev, + void *user_data, LYS_INFORMAT *format, const char **module_data, ly_module_imp_data_free_clb *free_module_data); + +/** + * @brief Get the custom callback for missing import/include module retrieval. + * + * @param[in] ctx Context to read from. + * @param[in] user_data Optional pointer for getting the user-supplied callback data. + * @return Callback or NULL if not set. + */ +LIBYANG_API_DECL ly_module_imp_clb ly_ctx_get_module_imp_clb(const struct ly_ctx *ctx, void **user_data); + +/** + * @brief Set missing include or import module callback. It is meant to be used when the models + * are not locally available (such as when downloading modules from a NETCONF server), it should + * not be required in other cases. + * + * @param[in] ctx Context that will use this callback. + * @param[in] clb Callback responsible for returning the missing model. + * @param[in] user_data Arbitrary data that will always be passed to the callback @p clb. + */ +LIBYANG_API_DECL void ly_ctx_set_module_imp_clb(struct ly_ctx *ctx, ly_module_imp_clb clb, void *user_data); + +/** + * @brief Callback for getting arbitrary run-time data required by an extension instance. + * + * @param[in] ext Compiled extension instance. + * @param[in] user_data User-supplied callback data. + * @param[out] ext_data Provided extension instance data. + * @param[out] ext_data_free Whether the extension instance should free @p ext_data or not. + * @return LY_ERR value. + */ +typedef LY_ERR (*ly_ext_data_clb)(const struct lysc_ext_instance *ext, void *user_data, void **ext_data, + ly_bool *ext_data_free); + +/** + * @brief Set callback providing run-time extension instance data. The expected data depend on the extension. + * Data expected by internal extensions: + * + * - *ietf-yang-schema-mount:mount-point* (struct lyd_node \*\*ext_data)\n + * Operational data tree with at least `ietf-yang-library` data describing the mounted schema and + * `ietf-yang-schema-mount` **validated** data describing the specific mount point + * ([ref](https://datatracker.ietf.org/doc/html/rfc8528#section-3.3)). + * + * @param[in] ctx Context that will use this callback. + * @param[in] clb Callback responsible for returning the extension instance data. + * @param[in] user_data Arbitrary data that will always be passed to the callback @p clb. + */ +LIBYANG_API_DECL ly_ext_data_clb ly_ctx_set_ext_data_clb(struct ly_ctx *ctx, ly_ext_data_clb clb, void *user_data); + +/** + * @brief Get YANG module of the given name and revision. + * + * @param[in] ctx Context to work in. + * @param[in] name Name of the YANG module to get. + * @param[in] revision Requested revision date of the YANG module to get. If not specified, + * the schema with no revision is returned, if it is present in the context. + * @return Pointer to the YANG module, NULL if no schema in the context follows the name and revision requirements. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module(const struct ly_ctx *ctx, const char *name, const char *revision); + +/** + * @brief Get the latest revision of the YANG module specified by its name. + * + * YANG modules with no revision are supposed to be the oldest one. + * + * @param[in] ctx Context where to search. + * @param[in] name Name of the YANG module to get. + * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the + * given name is present in the context. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module_latest(const struct ly_ctx *ctx, const char *name); + +/** + * @brief Get the (only) implemented YANG module specified by its name. + * + * @param[in] ctx Context where to search. + * @param[in] name Name of the YANG module to get. + * @return The only implemented YANG module revision of the given name in the given context. NULL if there is no + * implemented module of the given name. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module_implemented(const struct ly_ctx *ctx, const char *name); + +/** + * @brief Iterate over all modules in the given context. + * + * @param[in] ctx Context with the modules. + * @param[in,out] index Index of the next module to get. Value of 0 starts from the beginning. + * The value is updated with each call, so to iterate over all modules the same variable is supposed + * to be used in all calls starting with value 0. + * @return Next context module, NULL if the last was already returned. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module_iter(const struct ly_ctx *ctx, uint32_t *index); + +/** + * @brief Get YANG module of the given namespace and revision. + * + * @param[in] ctx Context to work in. + * @param[in] ns Namespace of the YANG module to get. + * @param[in] revision Requested revision date of the YANG module to get. If not specified, + * the schema with no revision is returned, if it is present in the context. + * @return Pointer to the YANG module, NULL if no schema in the context follows the namespace and revision requirements. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module_ns(const struct ly_ctx *ctx, const char *ns, const char *revision); + +/** + * @brief Get the latest revision of the YANG module specified by its namespace. + * + * YANG modules with no revision are supposed to be the oldest one. + * + * @param[in] ctx Context where to search. + * @param[in] ns Namespace of the YANG module to get. + * @return The latest revision of the specified YANG module in the given context, NULL if no YANG module of the + * given namespace is present in the context. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module_latest_ns(const struct ly_ctx *ctx, const char *ns); + +/** + * @brief Get the (only) implemented YANG module specified by its namespace. + * + * @param[in] ctx Context where to search. + * @param[in] ns Namespace of the YANG module to get. + * @return The only implemented YANG module revision of the given namespace in the given context. NULL if there is no + * implemented module of the given namespace. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_get_module_implemented_ns(const struct ly_ctx *ctx, const char *ns); + +/** + * @brief Get a specific submodule from context. If its belongs-to module is known, use ::ly_ctx_get_submodule2(). + * + * @param[in] ctx libyang context to search in. + * @param[in] submodule Submodule name to find. + * @param[in] revision Revision of the submodule to find, NULL for a submodule without a revision. + * @return Found submodule, NULL if there is none. + */ +LIBYANG_API_DECL const struct lysp_submodule *ly_ctx_get_submodule(const struct ly_ctx *ctx, const char *submodule, + const char *revision); + +/** + * @brief Get the latests revision of a submodule from context. If its belongs-to module is known, + * use ::ly_ctx_get_submodule2_latest(). + * + * @param[in] ctx libyang context to search in. + * @param[in] submodule Submodule name to find. + * @return Found submodule, NULL if there is none. + */ +LIBYANG_API_DECL const struct lysp_submodule *ly_ctx_get_submodule_latest(const struct ly_ctx *ctx, const char *submodule); + +/** + * @brief Get a specific submodule from a module. If the belongs-to module is not known, use ::ly_ctx_get_submodule(). + * + * @param[in] module Belongs-to module to search in. + * @param[in] submodule Submodule name to find. + * @param[in] revision Revision of the submodule to find, NULL for a submodule without a revision. + * @return Found submodule, NULL if there is none. + */ +LIBYANG_API_DECL const struct lysp_submodule *ly_ctx_get_submodule2(const struct lys_module *module, const char *submodule, + const char *revision); + +/** + * @brief Get the latest revision of a submodule from a module. If the belongs-to module is not known, + * use ::ly_ctx_get_submodule_latest(). + * + * @param[in] module Belongs-to module to search in. + * @param[in] submodule Submodule name to find. + * @return Found submodule, NULL if there is none. + */ +LIBYANG_API_DECL const struct lysp_submodule *ly_ctx_get_submodule2_latest(const struct lys_module *module, + const char *submodule); + +/** + * @brief Learn the number of internal modules of a context. Internal modules + * is considered one that was loaded during the context creation. + * + * @param[in] ctx libyang context to examine. + * @return Number of internal modules. + */ +LIBYANG_API_DECL uint32_t ly_ctx_internal_modules_count(const struct ly_ctx *ctx); + +/** + * @brief Try to find the model in the searchpaths of \p ctx and load it into it. If custom missing + * module callback is set, it is used instead. + * + * The context itself is searched for the requested module first. If \p revision is not specified + * (the module of the latest revision is requested) and there is implemented revision of the requested + * module in the context, this implemented revision is returned despite there might be a newer revision. + * This behavior is cause by the fact that it is not possible to have multiple implemented revisions of + * the same module in the context. + * + * @param[in] ctx Context to add to. + * @param[in] name Name of the module to load. + * @param[in] revision Optional revision date of the module. If not specified, the latest revision is loaded. + * @param[in] features Optional array of features ended with NULL to be enabled if the module is being implemented. + * The feature string '*' enables all and array of length 1 with only the terminating NULL explicitly disables all + * the features. In case the parameter is NULL, the features are untouched - left disabled in newly loaded module or + * with the current features settings in case the module is already present in the context. + * @return Pointer to the data model structure, NULL if not found or some error occurred. + */ +LIBYANG_API_DECL struct lys_module *ly_ctx_load_module(struct ly_ctx *ctx, const char *name, const char *revision, + const char **features); + +/** + * @brief Get data of the internal ietf-yang-library module with information about all the loaded modules. + * ietf-yang-library module must be loaded. + * + * Note that "/ietf-yang-library:yang-library/datastore" list instances are not created and should be + * appended by the caller. There is a single "/ietf-yang-library:yang-library/schema" instance created + * with the key value "complete". + * + * If the data identifier can be limited to the existence and changes of this context, the following + * last 2 parameters can be used: + * + * "%u" as @p content_id_format and ::ly_ctx_get_change_count() as its parameter; + * "%u" as @p content_id_format and ::ly_ctx_get_modules_hash() as its parameter. + * + * @param[in] ctx Context with the modules. + * @param[out] root Generated yang-library data. + * @param[in] content_id_format Format string (printf-like) for the yang-library data identifier, which is + * the "content_id" node in the 2019-01-04 revision of ietf-yang-library. + * @param[in] ... Parameters for @p content_id_format. + * @return LY_ERR value + */ +LIBYANG_API_DECL LY_ERR ly_ctx_get_yanglib_data(const struct ly_ctx *ctx, struct lyd_node **root, + const char *content_id_format, ...); + +/** + * @brief Free all internal structures of the specified context. + * + * The function should be used before terminating the application to destroy + * and free all structures internally used by libyang. If the caller uses + * multiple contexts, the function should be called for each used context. + * + * All instance data are supposed to be freed before destroying the context using ::lyd_free_all(), for example. + * Data models (schemas) are destroyed automatically as part of ::ly_ctx_destroy() call. + * + * Note that the data stored by user into the ::lysc_node.priv pointer are kept + * untouched and the caller is responsible for freeing this private data. + * + * @param[in] ctx libyang context to destroy + */ +LIBYANG_API_DECL void ly_ctx_destroy(struct ly_ctx *ctx); + +/** @} context */ + +#ifdef __cplusplus +} +#endif + +#endif /* LY_CONTEXT_H_ */ |