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 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 - 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 YANG Modules 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 ietf-yang-library module.

YANG data can be parsed by lyd_parse_*() functions. Note, that functions for schema have lys_ prefix (or lysp_ for the parsed and lysc_ for the compiled schema - for details see YANG Modules page) while functions for instance data have lyd_ prefix. Details about data formats or handling data without the appropriate YANG module in context can be found on Data Instances page.

Besides the YANG modules, context holds also error information and database of strings, both connected with the processed YANG modules and data.

Note: API for this group of functions is available in the context module.

Functions List