![]() |
libyang
2.0.7
libyang is YANG data modelling language parser and toolkit written (and providing API) in C.
|
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_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. 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_module * | ly_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_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. More... | |
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. More... | |
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. More... | |
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. More... | |
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. 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_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(). More... | |
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(). More... | |
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(). More... | |
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(). 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_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. 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... | |
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.
struct ly_ctx |
libyang context handler.
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
[in] | mod_name | Missing module name. |
[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. |
[in] | submod_name | Optional missing submodule name. |
[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. |
[in] | user_data | User-supplied callback data. |
[out] | format | Format of the returned module data. |
[out] | module_data | Requested module data. |
[out] | free_module_data | Callback for freeing the returned module data. If not set, the data will be left untouched. |
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.
[in] | module_data | Data to free. |
[in] | user_data | User-supplied callback data, same as for ly_module_imp_clb. |
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.
[in] | ctx | Context to compile. |
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.
[in] | ctx | libyang context to destroy |
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.
[in] | ctx | Context to be examined. |
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.
[in] | ctx | Context to work in. |
[in] | name | Name of the YANG module to get. |
[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. |
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.
[in] | ctx | Context to read from. |
[in] | user_data | Optional pointer for getting the user-supplied callback data. |
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.
[in] | ctx | Context where to search. |
[in] | name | Name of the YANG module to get. |
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.
[in] | ctx | Context where to search. |
[in] | ns | Namespace of the YANG module to get. |
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.
[in] | ctx | Context with the modules. |
[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. |
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.
[in] | ctx | Context where to search. |
[in] | name | Name of the YANG module to get. |
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.
[in] | ctx | Context where to search. |
[in] | ns | Namespace of the YANG module to get. |
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.
[in] | ctx | Context to work in. |
[in] | ns | Namespace of the YANG module to get. |
[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. |
uint16_t ly_ctx_get_options | ( | const struct ly_ctx * | ctx | ) |
Get the currently set context's options.
[in] | ctx | Context to query. |
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!
[in] | ctx | Context to query. |
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().
[in] | ctx | libyang context to search in. |
[in] | submodule | Submodule name to find. |
[in] | revision | Revision of the submodule to find, NULL for a submodule without a revision. |
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().
[in] | module | Belongs-to module to search in. |
[in] | submodule | Submodule name to find. |
[in] | revision | Revision of the submodule to find, NULL for a submodule without a revision. |
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().
[in] | module | Belongs-to module to search in. |
[in] | submodule | Submodule name to find. |
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().
[in] | ctx | libyang context to search in. |
[in] | submodule | Submodule name to find. |
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.
[in] | ctx | Context with the modules. |
[out] | root | Generated yang-library data. |
[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. |
[in] | ... | Parameters for content_id_format . |
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.
[in] | ctx | libyang context to examine. |
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.
[in] | ctx | Context to add to. |
[in] | name | Name of the module to load. |
[in] | revision | Optional revision date of the module. If not specified, the latest revision is loaded. |
[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. |
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
[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. |
[in] | options | Context options, see Context options. |
[out] | new_ctx | Pointer to the created libyang context if LY_SUCCESS returned. |
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().
[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. |
[in] | data | String containing yang-library data in the specified format. |
[in] | format | Format of the data in the provided file. |
[in] | options | Context options, see Context options. |
[out] | ctx | Pointer to the created libyang context if LY_SUCCESS returned. |
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().
[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. |
[in] | path | Path to the file containing yang-library-data in the specified format |
[in] | format | Format of the data in the provided file. |
[in] | options | Context options, see Context options. |
[out] | ctx | Pointer to the created libyang context if LY_SUCCESS returned. |
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().
[in] | ctx | libyang context where the latest revision information is going to be reset. |
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.
[in] | ctx | Context that will use this callback. |
[in] | clb | Callback responsible for returning the missing model. |
[in] | user_data | Arbitrary data that will always be passed to the callback clb . |
Set some of the context's options, see Context options.
[in] | ctx | Context to be modified. |
[in] | option | Combination 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. |
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.
[in] | ctx | Context to be modified. |
[in] | search_dir | New search path to add to the current paths previously set in ctx. |
Unset some of the context's options, see Context options.
[in] | ctx | Context to be modified. |
[in] | option | Combination of the context's options to be unset, see Context options. |
Clean the search path(s) from the libyang context.
To remove the recently added search path(s), use ly_ctx_unset_searchdir_last().
[in] | ctx | Context to be modified. |
[in] | value | Searchdir to be removed, use NULL to remove them all. |
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().
[in] | ctx | Context to be modified. |
[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. |