libyang  2.0.7
libyang is YANG data modelling language parser and toolkit written (and providing API) in C.
Context
Collaboration diagram for Context:

Modules

 Context options
 

Data Structures

struct  ly_ctx
 libyang context handler. More...
 

Typedefs

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)
 Callback for retrieving missing included or imported models in a custom way. More...
 
typedef void(* ly_module_imp_data_free_clb) (void *module_data, void *user_data)
 Callback for freeing returned module data in ly_module_imp_clb. More...
 

Functions

LY_ERR ly_ctx_compile (struct ly_ctx *ctx)
 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. More...
 
void ly_ctx_destroy (struct ly_ctx *ctx)
 Free all internal structures of the specified context. More...
 
uint16_t ly_ctx_get_change_count (const struct ly_ctx *ctx)
 Get the change count of the context (module set) during its life-time. More...
 
struct lys_modulely_ctx_get_module (const struct ly_ctx *ctx, const char *name, const char *revision)
 Get YANG module of the given name and revision. More...
 
ly_module_imp_clb ly_ctx_get_module_imp_clb (const struct ly_ctx *ctx, void **user_data)
 Get the custom callback for missing import/include module retrieval. More...
 
struct lys_modulely_ctx_get_module_implemented (const struct ly_ctx *ctx, const char *name)
 Get the (only) implemented YANG module specified by its name. More...
 
struct lys_modulely_ctx_get_module_implemented_ns (const struct ly_ctx *ctx, const char *ns)
 Get the (only) implemented YANG module specified by its namespace. More...
 
const struct lys_modulely_ctx_get_module_iter (const struct ly_ctx *ctx, uint32_t *index)
 Iterate over all modules in the given context. More...
 
struct lys_modulely_ctx_get_module_latest (const struct ly_ctx *ctx, const char *name)
 Get the latest revision of the YANG module specified by its name. More...
 
struct lys_modulely_ctx_get_module_latest_ns (const struct ly_ctx *ctx, const char *ns)
 Get the latest revision of the YANG module specified by its namespace. More...
 
struct lys_modulely_ctx_get_module_ns (const struct ly_ctx *ctx, const char *ns, const char *revision)
 Get YANG module of the given namespace and revision. More...
 
uint16_t ly_ctx_get_options (const struct ly_ctx *ctx)
 Get the currently set context's options. More...
 
const char *const * ly_ctx_get_searchdirs (const struct ly_ctx *ctx)
 Get the NULL-terminated list of the search paths in libyang context. Do not modify the result! More...
 
const struct lysp_submodulely_ctx_get_submodule (const struct ly_ctx *ctx, const char *submodule, const char *revision)
 Get a specific submodule from context. If its belongs-to module is known, use ly_ctx_get_submodule2(). More...
 
const struct lysp_submodulely_ctx_get_submodule2 (const struct lys_module *module, const char *submodule, const char *revision)
 Get a specific submodule from a module. If the belongs-to module is not known, use ly_ctx_get_submodule(). More...
 
const struct lysp_submodulely_ctx_get_submodule2_latest (const struct lys_module *module, const char *submodule)
 Get the latest revision of a submodule from a module. If the belongs-to module is not known, use ly_ctx_get_submodule_latest(). More...
 
const struct lysp_submodulely_ctx_get_submodule_latest (const struct ly_ctx *ctx, const char *submodule)
 Get the latests revision of a submodule from context. If its belongs-to module is known, use ly_ctx_get_submodule2_latest(). More...
 
LY_ERR ly_ctx_get_yanglib_data (const struct ly_ctx *ctx, struct lyd_node **root, const char *content_id_format,...)
 Get data of the internal ietf-yang-library module with information about all the loaded modules. ietf-yang-library module must be loaded. More...
 
uint32_t ly_ctx_internal_modules_count (const struct ly_ctx *ctx)
 Learn the number of internal modules of a context. Internal modules is considered one that was loaded during the context creation. More...
 
const struct lys_modulely_ctx_load_module (struct ly_ctx *ctx, const char *name, const char *revision, const char **features)
 Try to find the model in the searchpaths of ctx and load it into it. If custom missing module callback is set, it is used instead. More...
 
LY_ERR ly_ctx_new (const char *search_dir, uint16_t options, struct ly_ctx **new_ctx)
 Create libyang context. More...
 
LY_ERR ly_ctx_new_ylmem (const char *search_dir, const char *data, LYD_FORMAT format, int options, struct ly_ctx **ctx)
 Create libyang context according to the content of the given yang-library data. More...
 
LY_ERR ly_ctx_new_ylpath (const char *search_dir, const char *path, LYD_FORMAT format, int options, struct ly_ctx **ctx)
 Create libyang context according to the content of the given yang-library data. More...
 
void ly_ctx_reset_latests (struct ly_ctx *ctx)
 Reset cached latest revision information of the schemas in the context. More...
 
void ly_ctx_set_module_imp_clb (struct ly_ctx *ctx, ly_module_imp_clb clb, void *user_data)
 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. More...
 
LY_ERR ly_ctx_set_options (struct ly_ctx *ctx, uint16_t option)
 Set some of the context's options, see Context options. More...
 
LY_ERR ly_ctx_set_searchdir (struct ly_ctx *ctx, const char *search_dir)
 Add the search path into libyang context. More...
 
LY_ERR ly_ctx_unset_options (struct ly_ctx *ctx, uint16_t option)
 Unset some of the context's options, see Context options. More...
 
LY_ERR ly_ctx_unset_searchdir (struct ly_ctx *ctx, const char *value)
 Clean the search path(s) from the libyang context. More...
 
LY_ERR ly_ctx_unset_searchdir_last (struct ly_ctx *ctx, uint32_t count)
 Remove the least recently added search path(s) from the libyang context. More...
 

Detailed Description

Structures and functions to manipulate with the libyang context containers.

The context concept allows callers to work in environments with different sets of YANG schemas. More detailed information can be found at Context page.


Data Structure Documentation

◆ ly_ctx

struct ly_ctx

libyang context handler.

Typedef Documentation

◆ ly_module_imp_clb

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)

Callback for retrieving missing included or imported models in a custom way.

When 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

  • free_module_data callback is provided, it will be used later to free the allegedly const data which were returned by this callback.
Parameters
[in]mod_nameMissing module name.
[in]mod_revOptional 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.
[in]submod_nameOptional missing submodule name.
[in]submod_revOptional 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.
[in]user_dataUser-supplied callback data.
[out]formatFormat of the returned module data.
[out]module_dataRequested module data.
[out]free_module_dataCallback for freeing the returned module data. If not set, the data will be left untouched.
Returns
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.

Definition at line 389 of file context.h.

◆ ly_module_imp_data_free_clb

typedef void(* ly_module_imp_data_free_clb) (void *module_data, void *user_data)

Callback for freeing returned module data in ly_module_imp_clb.

Parameters
[in]module_dataData to free.
[in]user_dataUser-supplied callback data, same as for ly_module_imp_clb.

Definition at line 365 of file context.h.

Function Documentation

◆ ly_ctx_compile()

LY_ERR ly_ctx_compile ( struct ly_ctx ctx)

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.

Parameters
[in]ctxContext to compile.
Returns
LY_ERR return value.

◆ ly_ctx_destroy()

void ly_ctx_destroy ( struct ly_ctx ctx)

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. Data models 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.

Parameters
[in]ctxlibyang context to destroy

◆ ly_ctx_get_change_count()

uint16_t ly_ctx_get_change_count ( const struct ly_ctx ctx)

Get the change count of the context (module set) during its life-time.

Parameters
[in]ctxContext to be examined.
Returns
Context change count.

◆ ly_ctx_get_module()

struct lys_module* ly_ctx_get_module ( const struct ly_ctx ctx,
const char *  name,
const char *  revision 
)

Get YANG module of the given name and revision.

Parameters
[in]ctxContext to work in.
[in]nameName of the YANG module to get.
[in]revisionRequested 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.
Returns
Pointer to the YANG module, NULL if no schema in the context follows the name and revision requirements.

◆ ly_ctx_get_module_imp_clb()

ly_module_imp_clb ly_ctx_get_module_imp_clb ( const struct ly_ctx ctx,
void **  user_data 
)

Get the custom callback for missing import/include module retrieval.

Parameters
[in]ctxContext to read from.
[in]user_dataOptional pointer for getting the user-supplied callback data.
Returns
Callback or NULL if not set.

◆ ly_ctx_get_module_implemented()

struct lys_module* ly_ctx_get_module_implemented ( const struct ly_ctx ctx,
const char *  name 
)

Get the (only) implemented YANG module specified by its name.

Parameters
[in]ctxContext where to search.
[in]nameName of the YANG module to get.
Returns
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.

◆ ly_ctx_get_module_implemented_ns()

struct lys_module* ly_ctx_get_module_implemented_ns ( const struct ly_ctx ctx,
const char *  ns 
)

Get the (only) implemented YANG module specified by its namespace.

Parameters
[in]ctxContext where to search.
[in]nsNamespace of the YANG module to get.
Returns
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.

◆ ly_ctx_get_module_iter()

const struct lys_module* ly_ctx_get_module_iter ( const struct ly_ctx ctx,
uint32_t *  index 
)

Iterate over all modules in the given context.

Parameters
[in]ctxContext with the modules.
[in,out]indexIndex 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.
Returns
Next context module, NULL if the last was already returned.

◆ ly_ctx_get_module_latest()

struct lys_module* ly_ctx_get_module_latest ( const struct ly_ctx ctx,
const char *  name 
)

Get the latest revision of the YANG module specified by its name.

YANG modules with no revision are supposed to be the oldest one.

Parameters
[in]ctxContext where to search.
[in]nameName of the YANG module to get.
Returns
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.

◆ ly_ctx_get_module_latest_ns()

struct lys_module* ly_ctx_get_module_latest_ns ( const struct ly_ctx ctx,
const char *  ns 
)

Get the latest revision of the YANG module specified by its namespace.

YANG modules with no revision are supposed to be the oldest one.

Parameters
[in]ctxContext where to search.
[in]nsNamespace of the YANG module to get.
Returns
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.

◆ ly_ctx_get_module_ns()

struct lys_module* ly_ctx_get_module_ns ( const struct ly_ctx ctx,
const char *  ns,
const char *  revision 
)

Get YANG module of the given namespace and revision.

Parameters
[in]ctxContext to work in.
[in]nsNamespace of the YANG module to get.
[in]revisionRequested 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.
Returns
Pointer to the YANG module, NULL if no schema in the context follows the namespace and revision requirements.

◆ ly_ctx_get_options()

uint16_t ly_ctx_get_options ( const struct ly_ctx ctx)

Get the currently set context's options.

Parameters
[in]ctxContext to query.
Returns
Combination of all the currently set context's options, see Context options.

◆ ly_ctx_get_searchdirs()

const char* const* ly_ctx_get_searchdirs ( const struct ly_ctx ctx)

Get the NULL-terminated list of the search paths in libyang context. Do not modify the result!

Parameters
[in]ctxContext to query.
Returns
NULL-terminated list (array) of the search paths, NULL if no searchpath was set. Do not modify the provided data in any way!

◆ ly_ctx_get_submodule()

const struct lysp_submodule* ly_ctx_get_submodule ( const struct ly_ctx ctx,
const char *  submodule,
const char *  revision 
)

Get a specific submodule from context. If its belongs-to module is known, use ly_ctx_get_submodule2().

Parameters
[in]ctxlibyang context to search in.
[in]submoduleSubmodule name to find.
[in]revisionRevision of the submodule to find, NULL for a submodule without a revision.
Returns
Found submodule, NULL if there is none.

◆ ly_ctx_get_submodule2()

const struct lysp_submodule* ly_ctx_get_submodule2 ( const struct lys_module module,
const char *  submodule,
const char *  revision 
)

Get a specific submodule from a module. If the belongs-to module is not known, use ly_ctx_get_submodule().

Parameters
[in]moduleBelongs-to module to search in.
[in]submoduleSubmodule name to find.
[in]revisionRevision of the submodule to find, NULL for a submodule without a revision.
Returns
Found submodule, NULL if there is none.

◆ ly_ctx_get_submodule2_latest()

const struct lysp_submodule* ly_ctx_get_submodule2_latest ( const struct lys_module module,
const char *  submodule 
)

Get the latest revision of a submodule from a module. If the belongs-to module is not known, use ly_ctx_get_submodule_latest().

Parameters
[in]moduleBelongs-to module to search in.
[in]submoduleSubmodule name to find.
Returns
Found submodule, NULL if there is none.

◆ ly_ctx_get_submodule_latest()

const struct lysp_submodule* ly_ctx_get_submodule_latest ( const struct ly_ctx ctx,
const char *  submodule 
)

Get the latests revision of a submodule from context. If its belongs-to module is known, use ly_ctx_get_submodule2_latest().

Parameters
[in]ctxlibyang context to search in.
[in]submoduleSubmodule name to find.
Returns
Found submodule, NULL if there is none.

◆ ly_ctx_get_yanglib_data()

LY_ERR ly_ctx_get_yanglib_data ( const struct ly_ctx ctx,
struct lyd_node **  root,
const char *  content_id_format,
  ... 
)

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 content_id_format and ly_ctx_get_change_count() as its parameter.

Parameters
[in]ctxContext with the modules.
[out]rootGenerated yang-library data.
[in]content_id_formatFormat 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.
[in]...Parameters for content_id_format.
Returns
LY_ERR value

◆ ly_ctx_internal_modules_count()

uint32_t ly_ctx_internal_modules_count ( const struct ly_ctx ctx)

Learn the number of internal modules of a context. Internal modules is considered one that was loaded during the context creation.

Parameters
[in]ctxlibyang context to examine.
Returns
Number of internal modules.

◆ ly_ctx_load_module()

const struct lys_module* ly_ctx_load_module ( struct ly_ctx ctx,
const char *  name,
const char *  revision,
const char **  features 
)

Try to find the model in the searchpaths of 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 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.

Parameters
[in]ctxContext to add to.
[in]nameName of the module to load.
[in]revisionOptional revision date of the module. If not specified, the latest revision is loaded.
[in]featuresOptional 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.
Returns
Pointer to the data model structure, NULL if not found or some error occurred.

◆ ly_ctx_new()

LY_ERR ly_ctx_new ( const char *  search_dir,
uint16_t  options,
struct ly_ctx **  new_ctx 
)

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 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 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.
Parameters
[in]search_dirDirectory where libyang will search for the imported or included modules and submodules. If no such directory is available, NULL is accepted.
[in]optionsContext options, see Context options.
[out]new_ctxPointer to the created libyang context if LY_SUCCESS returned.
Returns
LY_ERR return value.

◆ ly_ctx_new_ylmem()

LY_ERR ly_ctx_new_ylmem ( const char *  search_dir,
const char *  data,
LYD_FORMAT  format,
int  options,
struct ly_ctx **  ctx 
)

Create libyang context according to the content of the given yang-library data.

This function loads the yang-library data from the given string. If you need to pass the data as path to a file holding the data, use ly_ctx_new_ylpath(). 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().

Parameters
[in]search_dirDirectory where libyang will search for the imported or included modules and submodules. If no such directory is available, NULL is accepted.
[in]dataString containing yang-library data in the specified format.
[in]formatFormat of the data in the provided file.
[in]optionsContext options, see Context options.
[out]ctxPointer to the created libyang context if LY_SUCCESS returned.
Returns
LY_ERR return value

◆ ly_ctx_new_ylpath()

LY_ERR ly_ctx_new_ylpath ( const char *  search_dir,
const char *  path,
LYD_FORMAT  format,
int  options,
struct ly_ctx **  ctx 
)

Create libyang context according to the content of the given yang-library data.

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().

Parameters
[in]search_dirDirectory where libyang will search for the imported or included modules and submodules. If no such directory is available, NULL is accepted.
[in]pathPath to the file containing yang-library-data in the specified format
[in]formatFormat of the data in the provided file.
[in]optionsContext options, see Context options.
[out]ctxPointer to the created libyang context if LY_SUCCESS returned.
Returns
LY_ERR return value

◆ ly_ctx_reset_latests()

void ly_ctx_reset_latests ( struct ly_ctx ctx)

Reset cached latest revision information of the schemas in the context.

When a (sub)module is imported/included without revision, the latest revision is searched. libyang searches for the latest revision in searchdirs and/or via provided import callback ly_module_imp_clb() just once. Then it is expected that the content of searchdirs or data returned by the callback does not change. So when it changes, it is necessary to force searching for the latest revision in case of loading another module, which what this function does.

The latest revision information is also reset when the searchdirs set changes via ly_ctx_set_searchdir().

Parameters
[in]ctxlibyang context where the latest revision information is going to be reset.

◆ ly_ctx_set_module_imp_clb()

void ly_ctx_set_module_imp_clb ( struct ly_ctx ctx,
ly_module_imp_clb  clb,
void *  user_data 
)

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.

Parameters
[in]ctxContext that will use this callback.
[in]clbCallback responsible for returning the missing model.
[in]user_dataArbitrary data that will always be passed to the callback clb.

◆ ly_ctx_set_options()

LY_ERR ly_ctx_set_options ( struct ly_ctx ctx,
uint16_t  option 
)

Set some of the context's options, see Context options.

Parameters
[in]ctxContext to be modified.
[in]optionCombination of the context's options to be set, see Context options. 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.
Returns
LY_ERR value.

◆ ly_ctx_set_searchdir()

LY_ERR ly_ctx_set_searchdir ( struct ly_ctx ctx,
const char *  search_dir 
)

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.

Parameters
[in]ctxContext to be modified.
[in]search_dirNew search path to add to the current paths previously set in ctx.
Returns
LY_ERR return value.

◆ ly_ctx_unset_options()

LY_ERR ly_ctx_unset_options ( struct ly_ctx ctx,
uint16_t  option 
)

Unset some of the context's options, see Context options.

Parameters
[in]ctxContext to be modified.
[in]optionCombination of the context's options to be unset, see Context options.
Returns
LY_ERR value.

◆ ly_ctx_unset_searchdir()

LY_ERR ly_ctx_unset_searchdir ( struct ly_ctx ctx,
const char *  value 
)

Clean the search path(s) from the libyang context.

To remove the recently added search path(s), use ly_ctx_unset_searchdir_last().

Parameters
[in]ctxContext to be modified.
[in]valueSearchdir to be removed, use NULL to remove them all.
Returns
LY_ERR return value

◆ ly_ctx_unset_searchdir_last()

LY_ERR ly_ctx_unset_searchdir_last ( struct ly_ctx ctx,
uint32_t  count 
)

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().

Parameters
[in]ctxContext to be modified.
[in]countNumber 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.
Returns
LY_ERR return value