Loading...
Searching...
No Matches
Type Plugins

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

YANG allows to define new data types via typedef statements or even in leaf's/leaf-list's type statements. Such types are derived (directly or indirectly) from a set of YANG built-in types. libyang implements all handling of the data values of the YANG types via the Type Plugins API. Internally, there is implementation of the built-in types and others can be added as an external plugin (see Plugins).

Type plugin is supposed to

- store (and canonize) data value,
- validate it according to the type's restrictions,
- compare two values (lyd_value) of the same type,
- duplicate value (lyd_value),
- print it and
- free the specific data inserted into lyd_value.

These tasks are implemented as callbacks provided to libyang via lyplg_type_record structures defined as array using LYPLG_TYPES macro.

All the callbacks are supposed to do not log directly via libyang logger. Instead, they return LY_ERR value and ly_err_item error structure(s) describing the detected error(s) (helper functions ly_err_new() and ly_err_free() are available).

The main functionality is provided via lyplg_type_store_clb callback responsible for canonizing and storing provided string representation of the value in specified format (XML and JSON supported). Valid value is stored in lyd_value structure - its union allows to store data as one of the predefined type or in a custom form behind the void *ptr member of lyd_value structure. The callback is also responsible for storing canonized string representation of the value as lyd_value._canonical. If the type does not define canonical representation, the original representation is stored. In case there are any differences between the representation in specific input types, the plugin is supposed to store the value in JSON representation - typically, the difference is in prefix representation and JSON format uses directly the module names as prefixes.

Usually, all the validation according to the type's restrictions is done in the store callback. However, in case the type requires some validation referencing other entities in the data tree, the optional validation callback lyplg_type_validate_clb can be implemented.

The stored values can be compared in a specific way by providing lyplg_type_compare_clb. In case the best way to compare the values is to compare their canonical string representations, the lyplg_type_compare_simple() function can be used.

Data duplication is done with lyplg_type_dup_clb callbacks. Note that the callback is responsible even for duplicating the lyd_value._canonical, so the callback must be always present (the canonical value is always present). If there is nothing else to duplicate, the plugin can use the generic lyplg_type_dup_simple().

The stored value can be printed into the required format via lyplg_type_print_clb implementation. Simple printing canonical representation of the value is implemented by lyplg_type_print_simple().

And finally freeing any data stored in the lyd_value by the plugin is done by implementation of lyplg_type_free_clb. Freeing only the canonical string is implemented by lyplg_type_free_simple().

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.

Besides the mentioned `_simple` functions, libyang provides, as part of the type plugins API, all the callbacks implementing the built-in types in the internal plugins:

- simple callbacks handling only the canonical strings in the value,
- binary built-in type
- bits built-in type
- boolean built-in type
- decimal64 built-in type
- empty built-in type
- enumeration built-in type
- identityref built-in type
- instance-identifier built-in type
- integer built-in types
- leafref built-in type
- string built-in type
- union built-in type

And one derived type:

- xpath1.0 `ietf-yang-types` type

In addition to these callbacks, the API also provides several functions which can help to implement your own plugin for the derived YANG types:

- ly_err_new()
- ly_err_free()
- lyplg_type_lypath_new()
- lyplg_type_lypath_free()
- lyplg_type_prefix_data_new()
- lyplg_type_prefix_data_dup()
- lyplg_type_prefix_data_free()
- lyplg_type_get_prefix()
- lyplg_type_check_hints()
- lyplg_type_check_status()
- lyplg_type_lypath_check_status()
- lyplg_type_identity_isderived()
- lyplg_type_identity_module()
- lyplg_type_make_implemented()
- lyplg_type_parse_dec64()
- lyplg_type_parse_int()
- lyplg_type_parse_uint()
- lyplg_type_resolve_leafref()