blob: f8688797afd321100f81c677737bf3856a24c7c0 [file] [log] [blame]
Radek Krejci3e6632f2021-03-22 22:08:21 +01001/**
2 * @file plugins.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief Plugins manipulation.
5 *
6 * Copyright (c) 2021 CESNET, z.s.p.o.
7 *
8 * This source code is licensed under BSD 3-Clause License (the "License").
9 * You may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * https://opensource.org/licenses/BSD-3-Clause
13 */
14
15#ifndef LY_PLUGINS_H_
16#define LY_PLUGINS_H_
17
18#include "log.h"
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24/**
Radek Krejci75104122021-04-01 15:37:45 +020025 * @page howtoPlugins Plugins
26 *
27 * libyang supports two types of plugins to better support generic features of YANG that need some specific code for
28 * their specific instances in YANG modules. This is the case of YANG types, which are derived from YANG built-in types.
29 * The description of a derived type can specify some additional requirements or restriction that cannot be implemented
30 * generically and some special code is needed. The second case for libyang plugins are YANG extensions. For YANG extensions,
31 * most of the specification is hidden in their description (e.g. allowed substatements or place of the extension
32 * instantiation) and libyang is not able to process such a text in a generic way.
33 *
34 * In both cases, libyang provides API to get functionality implementing the specifics of each type or extension.
35 * Furthermore, there are several internal plugins, implementing built-in data types and selected derived types and YANG
36 * extensions. These internal plugins uses the same API and can be taken as examples for implementing user plugins. Internal
37 * plugins are always loaded with the first created [context](@ref howtoContext) and unloaded with destroying the last one.
38 * The external plugins are in the same phase loaded from the default directories specified at compile time via cmake
39 * variables `PLUGINS_DIR` (where the `extensions` and `types` subdirectories are added for each plugin type) or separately
40 * via `PLUGINS_DIR_EXTENSIONS` and `PLUGINS_DIR_TYPES` for each plugin type. The default directories can be replaced runtime
41 * using environment variables `LIBYANG_TYPES_PLUGINS_DIR` and `LIBYANG_EXTENSIONS_PLUGINS_DIR`.
42 *
43 * Order of the plugins determines their priority. libyang searches for the first match with the extension and type, so the
44 * firstly loaded plugin for the specific item is used. Since the internal plugins are loaded always before the external
45 * plugins, the internal plugins cannot be replaced.
46 *
47 * There is also a separate function ::lyplg_add() to add a plugin anytime later. Note, that such a plugin is being used
48 * after it is added with the lowest priority among other already loaded plugins. Also note that since all the plugins are
49 * unloaded with the destruction of the last context, creating a new context after that starts the standard plugins
50 * initiation and the manually added plugins are not loaded automatically.
51 *
52 * The following pages contain description of the API for creating user plugins.
53 *
54 * - @subpage howtoPluginsTypes
55 * - @subpage howtoPluginsExtensions
56 */
57
58/**
Radek Krejci3e6632f2021-03-22 22:08:21 +010059 * @defgroup plugins Plugins
60 * @{
61 *
62 */
63
64/**
65 * @brief Identifiers of the plugin type.
66 */
67enum LYPLG {
68 LYPLG_TYPE, /**< Specific type (typedef) */
69 LYPLG_EXTENSION /**< YANG extension */
70};
71
Radek Krejcibf940f92021-03-24 21:04:13 +010072/**
73 * @brief Manually load a plugin file.
74 *
75 * Note, that a plugin can be loaded only if there is at least one context. The loaded plugins are connected with the
76 * existence of a context. When all the contexts are destroyed, all the plugins are unloaded.
77 *
78 * @param[in] pathname Path to the plugin file. It can contain types or extensions plugins, both are accepted and correctly
79 * loaded.
80 *
81 * @return LY_SUCCESS if the file contains valid plugin compatible with the library version.
82 * @return LY_EDENIED in case there is no context and the plugin cannot be loaded.
83 * @return LY_EINVAL when pathname is NULL or the plugin contains invalid content for this libyang version.
84 * @return LY_ESYS when the plugin file cannot be loaded.
85 */
Jan Kundrátc6e39de2021-12-09 16:01:19 +010086LIBYANG_API_DECL LY_ERR lyplg_add(const char *pathname);
Radek Krejcibf940f92021-03-24 21:04:13 +010087
Radek Krejci3e6632f2021-03-22 22:08:21 +010088/** @} plugins */
89
90#ifdef __cplusplus
91}
92#endif
93
94#endif /* LY_PLUGINS_H_ */