Loading...
Searching...
No Matches
Extension Plugins

Note that the part of the libyang API here is available only by including a separated `<libyang/plugins_exts.h>` header file. Also note that the extension plugins API is versioned separately from libyang itself, so backward incompatible changes can come even without changing libyang major version.

YANG extensions are very complex. Usually only its description specifies how it is supposed to behave, what are the allowed substatements, their cardinality or if the standard YANG statements placed inside the extension differs somehow in their meaning or behavior. libyang provides the Extension plugins API to implement such extensions and add its support into libyang itself. However we tried our best, the API is not (and it cannot be) so universal and complete to cover all possibilities. There are definitely use cases which cannot be simply implemented only with this API.

libyang implements 3 important extensions: NACM, Metadata and yang-data. Despite the core implementation in all three cases is done via extension plugin API, also other parts of the libyang code had to be extended to cover complete scope of the extensions.

We believe, that the API is capable to allow implementation of very wide range of YANG extensions. However, if you see limitations for the particular YANG extension, don't hesitate to contact the project developers to discuss all the options, including updating the API.

The plugin's functionality is provided to libyang via a set of callbacks specified as an array of lyplg_ext_record structures using the LYPLG_EXTENSIONS macro.

The most important callbacks are lyplg_ext.parse and lyplg_ext.compile. They are responsible for parsing and compiling extension instance. This should include validating all the substatements, their values, or placement of the extension instance itself. If needed, the processed data can be stored in some form into the compiled schema representation of the extension instance. To make this task as easy as possible, libyang provides several parsing and compilation helper functions to process known YANG statements exactly as if they were standard YANG statements.

The data validation callback lyplg_ext.validate is used for additional validation of a data nodes that contains the connected extension instance directly (as a substatement) or indirectly in case of terminal nodes via their type (no matter if the extension instance is placed directly in the leaf's/leaf-list's type or in the type of the referenced typedef).

The lyplg_ext.printer_info callback implement printing the compiled extension instance data when the schema (module) is being printed in the LYS_OUT_YANG_COMPILED (info) format. As for compile callback, there are also helper functions to access printer's context and to print standard YANG statements placed in the extension instance by libyang itself.

The lyplg_ext.printer_ctree and lyplg_ext.printer_ptree callbacks implement printing of YANG tree diagrams (RFC 8340) for extension instance data. These callbacks are called for extension instances that have parents of type LY_STMT_MODULE, LY_STMT_SUBMODULE. Or these callbacks are called if the printer_tree finds a compiled/parsed data-node containing an extension instance. The callbacks should then decide which nodes should be printed within the extension instance. In addition, it is possible to register additional callbacks to the printer_tree context to override the form of the each node in the extension instance.

The last callback, lyplg_ext.cfree, is supposed to free all the data allocated by the lyplg_ext.compile callback. To free the data created by helper function lyplg_ext_compile_extension_instance(), the plugin can used lyplg_ext_cfree_instance_substatements().

The plugin information contains also the plugin identifier (lyplg_type.id). This string can serve to identify the specific plugin responsible to storing data value. In case the user can recognize the id string, it can access the plugin specific data with the appropriate knowledge of its structure.

Logging information from an extension plugin is possible via lyplg_ext_parse_log() and lyplg_ext_compile_log() functions.