libyang NEW support for user type plugins
Refs #448
diff --git a/src/libyang.h.in b/src/libyang.h.in
index 4334d7b..88cce31 100644
--- a/src/libyang.h.in
+++ b/src/libyang.h.in
@@ -49,7 +49,7 @@
* ([RFC 7951](https://tools.ietf.org/html/rfc7951)).
* - [Manipulation with the instance data](@ref howtodatamanipulators).
* - Support for [default values in the instance data](@ref howtodatawd) ([RFC 6243](https://tools.ietf.org/html/rfc6243)).
- * - Support for [YANG extensions](@ref howtoschemaextensions).
+ * - Support for [YANG extensions and user types](@ref howtoschemaplugins).
* - Support for [YANG Metadata](@ref howtoschemametadata) ([RFC 7952](https://tools.ietf.org/html/rfc6243)).
*
* The current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020)) as well as
@@ -234,7 +234,7 @@
*
* - @subpage howtoschemasparsers
* - @subpage howtoschemasfeatures
- * - @subpage howtoschemaextensions
+ * - @subpage howtoschemaplugins
* - @subpage howtoschemasprinters
*
* \note There are many functions to access information from the schema trees. Details are available in
@@ -327,7 +327,20 @@
*/
/**
- * @page howtoschemaextensions YANG Extensions Support
+ * @page howtoschemaplugins YANG Extension and User Type Support
+ *
+ * Extensions and user types are supported in the form of **plugins**. These are loaded from the plugin directory
+ * (`LIBDIR/libyang/`) whenever a context is created. However, the list of plugins can be refreshed manually by ly_load_plugins().
+ * The extension plugin directory path (default `LIBDIR/libyang/extensions/`) can be change via the
+ * `LIBYANG_EXTENSIONS_PLUGINS_DIR` environment variable and similarly the user type directory (default `LIBDIR/libyang/user_types/`)
+ * via `LIBYANG_USER_TYPES_PLUGINS_DIR`. Note, that unavailable plugins are not removed, only
+ * any new plugins are loaded. Also note that the availability of new plugins does not affect the current schemas in the
+ * contexts, they are applied only to the newly parsed schemas.
+ *
+ * The plugins list can be cleaned by ly_clean_plugins(). However, since various contexts (respectively their
+ * schemas) can link to the plugins, the cleanup is successful only when there is no remaining context.
+ *
+ * @section extensions Extensions
*
* YANG provides extensions as a mechanism how to add new statements into the language. Since they are very generic -
* extension instance can appear anywhere, they can contain any other YANG statement including extension instances and
@@ -336,7 +349,7 @@
* use cases should be covered and supported.
*
* Since libyang does not understand human text, it is not possible to get the complete defintion of the extension from
- * its description statement. Therefore, libyang allows the schema authors to provide @link lyext_plugin extension
+ * its description statement. Therefore, libyang allows the schema authors to provide @link extplugins extension
* plugin@endlink that provides information from the extension description to libyang.
*
* Here are some notes about the implementation of the particular YANG extensions features
@@ -380,8 +393,8 @@
* ::lys_ext_instance#ext_type is set to a different value than #LYEXT_FLAG, the structure can be cast to the particular
* extension instance structure to access the type-specific members.
*
- * Extension Plugins
- * -----------------
+ * @subsection extplugins Extension Plugins
+ *
* Extension plugins provide more detailed information about the extension in a understandable form for libyang. These
* information is usually provided in a text form in the extension's description statement. libyang provides several
* plugins for the common IETF extensions (NACM, Metadata, ...) that can be used as a code examples for other
@@ -407,18 +420,7 @@
* stored (as offset to the ::lys_ext_instance_complex#content member). The way how the data are stored is
* specified descriptions of #LY_STMT values.
*
- * The plugins are loaded from the plugin directory (LIBDIR/libyang/) whenever a context is created. However, the list
- * of plugins can be refreshed manually by lyext_load_plugins(). The plugin directory path can be change via the
- * `LIBYANG_EXTENSIONS_PLUGINS_DIR` environment variable. Note, that no more available plugins are not removed, only
- * the new plugins are loaded. Also note that availability of new plugins does not affect the current schemas in the
- * contexts, they are applied only to the newly parsed schemas.
- *
- * The plugins list can be cleaned by lyext_clean_plugins(). However, since various contexts (respectively their
- * schemas) can link to the plugins, the cleanup is successful only when there is no remaining context.
- *
- * Metadata Support
- * ----------------
- * @anchor howtoschemametadata
+ * @subsection howtoschemametadata Metadata Support
*
* YANG Metadata annotations are defined in [RFC 7952](https://tools.ietf.org/html/rfc6243) as YANG extension. In
* practice, it allows to have XML attributes (there is also a special encoding for JSON) in YANG modeled data.
@@ -467,12 +469,32 @@
* - the `select`'s content is XPath and it is internally transformed by libyang into the format where the
* XML namespace prefixes are replaced by the YANG module names.
*
+ * @section usertypes User Types
+ *
+ * Using this plugin mechanism, it is also possible to define what can be called **user types**. Values are
+ * always stored as a string in addition to being in a #lyd_val union. It is possible to customize how
+ * the value is stored in the union using a #lytype_store_clb callback.
+ *
+ * Generally, it is meant for storing certain types more effectively. For instance, when working with **ipv4-address**
+ * from the *ietf-inet-types* model, an application will most likely use the address in a binary form, not as a string.
+ * So, in the callback the value is simply transformed into the desired format and saved into #lyd_val value. However,
+ * the callback is allowed to store anything in the union. Another example, if there are many strings being created and
+ * handled, is to store the string length instead having 2 pointers to the same string.
+ *
+ * @subsection typeplugins User Type Plugins
+ *
+ * There is a simple example user type plugin in `src/user_types` that is not compiled nor installed.
+ *
+ * - ::lytype_plugin_list - plugin is supposed to provide callbacks for:
+ * + @link lytype_store_clb storing the value itself @endlink
+ * + freeing the stored value (optionally, if the store callback allocates memory)
+ *
* Functions List
* --------------
* - lys_ext_instance_presence()
* - lys_ext_instance_substmt()
- * - lyext_load_plugins()
- * - lyext_clean_plugins()
+ * - ly_load_plugins()
+ * - ly_clean_plugins()
*/
/**
@@ -1804,7 +1826,7 @@
LY_EINVAL, /**< Invalid value */
LY_EINT, /**< Internal error */
LY_EVALID, /**< Validation failure */
- LY_EEXT /**< Extension error reported by an extension plugin */
+ LY_EPLUGIN /**< Error reported by a plugin */
} LY_ERR;
/**