![]() |
libyang
1.0.184
YANG data modeling language library
|
The context concept allows callers to work in environments with different sets of YANG schemas.
The first step in libyang is to create a new context using ly_ctx_new(). It returns a handler used in the following work.
When creating a new context, search dir can be specified (NULL is accepted) to provide directory where libyang will automatically search for schemas being imported or included. The search path can be later changed via ly_ctx_set_searchdir() and ly_ctx_unset_searchdirs() functions. Before the search dirs, also the current working directory is (non-recursively) searched. For the case of the explicitly set search dirs, also all their subdirectories (and symlinks) are taken into account. Searching in the current working directory can be avoided with context's LY_CTX_DISABLE_SEARCHDIR_CWD option (or via ly_ctx_set_disable_searchdir_cwd()). 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_disable_searchdirs()). 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.
Schemas are added into the context using parser functions - lys_parse_*(). In case of schemas, also ly_ctx_load_module() can be used - in that case the ly_module_imp_clb or automatic search in search dir and in the current working directory is used.
Similarly, data trees can be parsed by lyd_parse_*() functions. Note, that functions for schemas have lys_ prefix while functions for instance data have lyd_ prefix. It can happen during data parsing that a schema is required and not found in the context or the schema is found, but is only imported, not implemented (so the data cannot actually be instantiated). In these cases, a callback is called, which should add this schema into the context or change its conformance to implemented. You can set the callback using ly_ctx_set_module_data_clb() (more in Parsing Data and Validating Data).
Context can hold multiple revisions of the same schema, but only one of them can be implemented. The schema is not implemented in case it is automatically loaded as import for another module and it is not referenced in such a module (and no other) as target of leafref, augment or deviation. All modules with deviation definition are always marked as implemented. The imported (not implemented) module can be set implemented by lys_set_implemented(). But the implemented module cannot be changed back to just imported module. The imported modules are used only as a source of definitions for types and groupings for uses statements. The data in such modules are ignored - caller is not allowed to create the data (including instantiating identities) defined in the model via data parsers, the default nodes are not added into any data tree and mandatory nodes are not checked in the data trees. This can be changed by ly_ctx_set_allimplemented() function, which causes that all the imported modules are automatically set to 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 the drawback that if a later revision of the module is later made available, this context will not use it. If you are aware of a case when this optimization could cause problems, you can disable it using a cmake(1) build option (variable).
Context holds all modules and their submodules internally. To get a specific module or submodule, use ly_ctx_get_module() and ly_ctx_get_submodule(). There are some additional alternatives to these functions (with different parameters). If you need to do something with all the modules or submodules in the context, it is advised to iterate over them using ly_ctx_get_module_iter(), it is the most efficient way. Alternatively, the ly_ctx_info() function can be used to get complex information about the schemas in the context in the form of data tree defined by ietf-yang-library schema. To get a specific node defined in a module in the context, ly_ctx_find_path() or ly_ctx_get_node() can be used.
Modules held by a context can be removed by ly_ctx_remove_module(). Besides removing the module, it is possible just to disable it with lys_set_disabled(). In this case the module is hidden in the context (disabled modules can be iterated via ly_ctx_get_disabled_module_iter()) and not used during the common work with the context. The module is enabled explicitly by calling lys_set_enabled() or implicitly by the request to load the schema (directly or indirectly via import of another module) into the context.
To clean the context from all the loaded modules (except the internal modules), the ly_ctx_clean() function can be used. To remove the context, there is ly_ctx_destroy() function.