1 /**
2  * @file tree_schema.h
3  * @author Radek Krejci <rkrejci@cesnet.cz>
4  * @brief libyang representation of data model trees.
5  *
6  * Copyright (c) 2015 - 2018 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_TREE_SCHEMA_H_
16 #define LY_TREE_SCHEMA_H_
17 
18 #include <limits.h>
19 #include <stddef.h>
20 #include <stdint.h>
21 #include <stdio.h>
22 #include <sys/types.h>
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /**
29  * @ingroup datatree
30  * @brief Macro to iterate via all sibling elements without affecting the list itself
31  *
32  * Works for all types of nodes despite it is data or schema tree, but all the
33  * parameters must be pointers to the same type.
34  *
35  * Use with opening curly bracket '{'. All parameters must be of the same type.
36  *
37  * @param START Pointer to the starting element.
38  * @param ELEM Iterator.
39  */
40 #define LY_TREE_FOR(START, ELEM) \
41     for ((ELEM) = (START); \
42          (ELEM); \
43          (ELEM) = (ELEM)->next)
44 
45 /**
46  * @ingroup datatree
47  * @brief Macro to iterate via all sibling elements allowing to modify the list itself (e.g. removing elements)
48  *
49  * Works for all types of nodes despite it is data or schema tree, but all the
50  * parameters must be pointers to the same type.
51  *
52  * Use with opening curly bracket '{'. All parameters must be of the same type.
53  *
54  * @param START Pointer to the starting element.
55  * @param NEXT Temporary storage to allow removing of the current iterator content.
56  * @param ELEM Iterator.
57  */
58 #define LY_TREE_FOR_SAFE(START, NEXT, ELEM) \
59     for ((ELEM) = (START); \
60          (ELEM) ? (NEXT = (ELEM)->next, 1) : 0; \
61          (ELEM) = (NEXT))
62 
63 /**
64  * @ingroup datatree
65  * @brief Macro to iterate via all elements in a tree. This is the opening part
66  * to the #LY_TREE_DFS_END - they always have to be used together.
67  *
68  * The function follows deep-first search algorithm:
69  * <pre>
70  *     1
71  *    / \
72  *   2   4
73  *  /   / \
74  * 3   5   6
75  * </pre>
76  *
77  * Works for all types of nodes despite it is data or schema tree, but all the
78  * parameters must be pointers to the same type. Use the same parameters for
79  * #LY_TREE_DFS_BEGIN and #LY_TREE_DFS_END.
80  *
81  * Since the next node is selected as part of #LY_TREE_DFS_END, do not use
82  * continue statement between the #LY_TREE_DFS_BEGIN and #LY_TREE_DFS_END.
83  *
84  * Use with opening curly bracket '{' after the macro.
85  *
86  * @param START Pointer to the starting element processed first.
87  * @param NEXT Temporary storage, do not use.
88  * @param ELEM Iterator intended for use in the block.
89  */
90 #define LY_TREE_DFS_BEGIN(START, NEXT, ELEM)                                  \
91     for ((ELEM) = (NEXT) = (START);                                           \
92          (ELEM);                                                              \
93          (ELEM) = (NEXT))
94 
95 /**
96  * @ingroup datatree
97  * @brief Macro to iterate via all elements in a tree. This is the closing part
98  * to the #LY_TREE_DFS_BEGIN - they always have to be used together.
99  *
100  * Works for all types of nodes despite it is data or schema tree, but all the
101  * parameters must be pointers to the same type - basic type of the tree (struct
102  * lys_node*, struct lyd_node* or struct lyxml_elem*). Use the same parameters for
103  * #LY_TREE_DFS_BEGIN and #LY_TREE_DFS_END. If the START parameter is a derived
104  * type (e.g. lys_node_leaf), caller is supposed to cast it to the base type
105  * identical to the other parameters.
106  *
107  * Use with closing curly bracket '}' after the macro.
108  *
109  * @param START Pointer to the starting element processed first.
110  * @param NEXT Temporary storage, do not use.
111  * @param ELEM Iterator intended for use in the block.
112  */
113 
114 #ifdef __cplusplus
115 #define TYPES_COMPATIBLE(type1, type2) typeid(*(type1)) == typeid(type2)
116 #elif defined(__GNUC__) || defined(__clang__)
117 #define TYPES_COMPATIBLE(type1, type2) __builtin_types_compatible_p(__typeof__(*(type1)), type2)
118 #else
119 #define TYPES_COMPATIBLE(type1, type2) _Generic(*(type1), type2: 1, default: 0)
120 #endif
121 
122 #define LY_TREE_DFS_END(START, NEXT, ELEM)                                    \
123     /* select element for the next run - children first */                    \
124     if (TYPES_COMPATIBLE(ELEM, struct lyd_node)) {                            \
125         /* child exception for leafs, leaflists and anyxml without children */\
126         if (((struct lyd_node *)(ELEM))->schema->nodetype & (LYS_LEAF | LYS_LEAFLIST | LYS_ANYDATA)) { \
127             (NEXT) = NULL;                                                    \
128         } else {                                                              \
129             (NEXT) = (ELEM)->child;                                           \
130         }                                                                     \
131     } else if (TYPES_COMPATIBLE(ELEM, struct lys_node)) {                     \
132         /* child exception for leafs, leaflists and anyxml without children */\
133         if (((struct lys_node *)(ELEM))->nodetype & (LYS_LEAF | LYS_LEAFLIST | LYS_ANYDATA)) { \
134             (NEXT) = NULL;                                                    \
135         } else {                                                              \
136             (NEXT) = (ELEM)->child;                                           \
137         }                                                                     \
138     } else {                                                                  \
139         (NEXT) = (ELEM)->child;                                               \
140     }                                                                         \
141                                                                               \
142     if (!(NEXT)) {                                                            \
143         /* no children */                                                     \
144         if ((ELEM) == (START)) {                                              \
145             /* we are done, (START) has no children */                        \
146             break;                                                            \
147         }                                                                     \
148         /* try siblings */                                                    \
149         (NEXT) = (ELEM)->next;                                                \
150     }                                                                         \
151     while (!(NEXT)) {                                                         \
152         /* parent is already processed, go to its sibling */                  \
153         if (TYPES_COMPATIBLE(ELEM, struct lys_node)                           \
154                 && (((struct lys_node *)(ELEM)->parent)->nodetype == LYS_AUGMENT)) {  \
155             (ELEM) = (ELEM)->parent->prev;                                    \
156         } else {                                                              \
157             (ELEM) = (ELEM)->parent;                                          \
158         }                                                                     \
159         /* no siblings, go back through parents */                            \
160         if (TYPES_COMPATIBLE(ELEM, struct lys_node)) {                        \
161             /* due to possible augments */                                    \
162             if (lys_parent((struct lys_node *)(ELEM)) == lys_parent((struct lys_node *)(START))) { \
163                 /* we are done, no next element to process */                 \
164                 break;                                                        \
165             }                                                                 \
166         } else if ((ELEM)->parent == (START)->parent) {                       \
167             /* we are done, no next element to process */                     \
168             break;                                                            \
169         }                                                                     \
170         (NEXT) = (ELEM)->next;                                                \
171     }
172 
173 /**
174  * @defgroup schematree Schema Tree
175  * @{
176  *
177  * Data structures and functions to manipulate and access schema tree.
178  */
179 
180 #define LY_ARRAY_MAX(var) (sizeof(var) == 8 ? ULLONG_MAX : ((1ULL << (sizeof(var) * 8)) - 1)) /**< maximal index the size_var is able to hold */
181 
182 #define LY_REV_SIZE 11   /**< revision data string length (including terminating NULL byte) */
183 
184 /**
185  * @brief Schema input formats accepted by libyang [parser functions](@ref howtoschemasparsers).
186  */
187 typedef enum {
188     LYS_IN_UNKNOWN = 0,  /**< unknown format, used as return value in case of error */
189     LYS_IN_YANG = 1,     /**< YANG schema input format */
190     LYS_IN_YIN = 2       /**< YIN schema input format */
191 } LYS_INFORMAT;
192 
193 /**
194  * @brief Schema output formats accepted by libyang [printer functions](@ref howtoschemasprinters).
195  */
196 typedef enum {
197     LYS_OUT_UNKNOWN = 0, /**< unknown format, used as return value in case of error */
198     LYS_OUT_YANG = 1,    /**< YANG schema output format */
199     LYS_OUT_YIN = 2,     /**< YIN schema output format */
200     LYS_OUT_TREE,        /**< Tree schema output format, for more information see the [printers](@ref howtoschemasprinters) page */
201     LYS_OUT_INFO,        /**< Info schema output format, for more information see the [printers](@ref howtoschemasprinters) page */
202     LYS_OUT_JSON,        /**< JSON schema output format, reflecting YIN format with conversion of attributes to object's members */
203 } LYS_OUTFORMAT;
204 
205 /**
206  * @defgroup schemaprinterflags Schema printer flags
207  * @brief Schema output flags accepted by libyang [printer functions](@ref howtoschemasprinters).
208  *
209  * @{
210  */
211 #define LYS_OUTOPT_TREE_RFC        0x01 /**< Conform to the RFC TODO tree output (only for tree format) */
212 #define LYS_OUTOPT_TREE_GROUPING   0x02 /**< Print groupings separately (only for tree format) */
213 #define LYS_OUTOPT_TREE_USES       0x04 /**< Print only uses instead the resolved grouping nodes (only for tree format) */
214 #define LYS_OUTOPT_TREE_NO_LEAFREF 0x08 /**< Do not print the target of leafrefs (only for tree format) */
215 
216 /**
217  * @}
218  */
219 
220 /* shortcuts for common in and out formats */
221 #define LYS_YANG 1       /**< YANG schema format, used for #LYS_INFORMAT and #LYS_OUTFORMAT */
222 #define LYS_YIN 2        /**< YIN schema format, used for #LYS_INFORMAT and #LYS_OUTFORMAT */
223 
224 /**
225  * @brief YANG schema node types
226  *
227  * Values are defined as separated bit values to allow checking using bitwise operations for multiple nodes.
228  */
229 typedef enum lys_nodetype {
230     LYS_UNKNOWN = 0x0000,        /**< uninitialized unknown statement node */
231     LYS_CONTAINER = 0x0001,      /**< container statement node */
232     LYS_CHOICE = 0x0002,         /**< choice statement node */
233     LYS_LEAF = 0x0004,           /**< leaf statement node */
234     LYS_LEAFLIST = 0x0008,       /**< leaf-list statement node */
235     LYS_LIST = 0x0010,           /**< list statement node */
236     LYS_ANYXML = 0x0020,         /**< anyxml statement node */
237     LYS_CASE = 0x0040,           /**< case statement node */
238     LYS_NOTIF = 0x0080,          /**< notification statement node */
239     LYS_RPC = 0x0100,            /**< rpc statement node */
240     LYS_INPUT = 0x0200,          /**< input statement node */
241     LYS_OUTPUT = 0x0400,         /**< output statement node */
242     LYS_GROUPING = 0x0800,       /**< grouping statement node */
243     LYS_USES = 0x1000,           /**< uses statement node */
244     LYS_AUGMENT = 0x2000,        /**< augment statement node */
245     LYS_ACTION = 0x4000,         /**< action statement node */
246     LYS_ANYDATA = 0x8020,        /**< anydata statement node, in tests it can be used for both #LYS_ANYXML and #LYS_ANYDATA */
247     LYS_EXT = 0x10000            /**< complex extension instance, ::lys_ext_instance_complex */
248 } LYS_NODE;
249 
250 /* all nodes sharing the node namespace except RPCs and notifications */
251 #define LYS_NO_RPC_NOTIF_NODE 0x807F
252 
253 #define LYS_ANY 0xFFFF
254 
255 /**
256  * @defgroup extensions YANG Extensions
257  *
258  * @{
259  */
260 
261 /**
262  * @brief List of YANG statements
263  *
264  * The description of each statement contains the storage type for the case the statement is specified by extension
265  * plugin to appear as a substatement to the extension instance. Note that the storage type/structure are used in
266  * case of #LY_STMT_CARD_OPT or #LY_STMT_CARD_MAND. In other cases, the data are stored as a pointer to the
267  * NULL-terminated array of base types:
268  *
269  *     char*     -> char**
270  *     lys_type* -> lys_type**
271  *     uint8_t   -> uint8_t*
272  *
273  * There are some items, that are not, in case of multiple instances, stored as an array of pointers.
274  * 1. The value is ORed with the previous value in the storage. Initial value is 0. This is the case of
275  *    e.g. #LY_STMT_STATUS. These items actually does not allow to have multiple instances (it does not make sense).
276  * 2. The lys_node_* data types are stored as a data tree, so in case of multiple instances, they are stored
277  *    as siblings to the first node.
278  *
279  * The values <= #LY_STMT_UNIQUE are compatible with #LYEXT_SUBSTMT values which defines the subset of YANG statements
280  * that does not store extension instances directly.
281  */
282 typedef enum {
283     LY_STMT_NODE = -1,    /**< mask for values #LY_STMT_ACTION - #LY_STMT_USES */
284     LY_STMT_UNKNOWN = 0,  /**< error return value */
285     LY_STMT_ARGUMENT = 1, /**< stored as __const char*__ + __uint8_t__, the second item contains yin element
286                                interpreted as follows: 1 - true; 2 - false/default, in case of multiple instances,
287                                the argument's values and yin elements are stored in two arrays
288                                (__const char **__ + __uint8_t *__) */
289     LY_STMT_BASE,         /**< stored as __const char*__ */
290     LY_STMT_BELONGSTO,    /**< belongs-to, stored as __const char*[2]__, the second item contains belongs-to's prefix,
291                                in case of multiple instances, the belongs-to's module values and prefixes are stored in
292                                two arrays (__const char **[2]__) */
293     LY_STMT_CONTACT,      /**< stored as __const char*__ */
294     LY_STMT_DEFAULT,      /**< stored as __const char*__ */
295     LY_STMT_DESCRIPTION,  /**< stored as __const char*__ */
296     LY_STMT_ERRTAG,       /**< error-app-tag, stored as __const char*__ */
297     LY_STMT_ERRMSG,       /**< error-message, stored as __const char*__ */
298     LY_STMT_KEY,          /**< stored as __const char*__ */
299     LY_STMT_NAMESPACE,    /**< stored as __const char*__ */
300     LY_STMT_ORGANIZATION, /**< organization, stored as __const char*__ */
301     LY_STMT_PATH,         /**< stored as __const char*__ */
302     LY_STMT_PREFIX,       /**< stored as __const char*__ */
303     LY_STMT_PRESENCE,     /**< stored as __const char*__ */
304     LY_STMT_REFERENCE,    /**< stored as __const char*__ */
305     LY_STMT_REVISIONDATE, /**< revision-date, stored as __const char*__ */
306     LY_STMT_UNITS,        /**< stored as __const char*__ */
307     LY_STMT_VALUE,        /**< stored as __int32_t*__ */
308     LY_STMT_VERSION,      /**< not supported in extension instances */
309     LY_STMT_MODIFIER,     /**< stored as __uint8_t__ interpreted as follows: 0 - not set/default; 1 - invert-match
310                                does not allow multiple instances */
311     LY_STMT_REQINSTANCE,  /**< require-instance, stored as __uint8_t__ interpreted as follows: 0 - not set/default;
312                                1 - true; 2 - false, does not allow multiple instances */
313     LY_STMT_YINELEM,      /**< not supported in extension instances  */
314     LY_STMT_CONFIG,       /**< stored as __uint16_t__ value (ORed with the previous value(s)), possible values are
315                                #LYS_CONFIG_R and #LYS_CONFIG_W (both ORed with #LYS_CONFIG_SET), does not allow multiple
316                                instances */
317     LY_STMT_MANDATORY,    /**< stored as __uint16_t__ value (ORed with the previous value(s)), possible values are
318                                #LYS_MAND_TRUE and #LYS_MAND_FALSE, does not allow multiple instances */
319     LY_STMT_ORDEREDBY,    /**< ordered-by, stored as __uint16_t__ value (ORed with the previous value(s)), possible
320                                value is #LYS_USERORDERED, does not allow multiple instances */
321     LY_STMT_STATUS,       /**< stored as __uint16_t__ value (ORed with the previous value(s)), possible values are
322                                #LYS_STATUS_CURR, #LYS_STATUS_DEPRC and #LYS_STATUS_OBSLT, does not allow multiple
323                                instances */
324     LY_STMT_DIGITS,       /**< fraction-digits, stored as __uint8_t__ */
325     LY_STMT_MAX,          /**< max-elements, stored as __uint32_t*__ */
326     LY_STMT_MIN,          /**< min-elements, stored as __uint32_t*__ */
327     LY_STMT_POSITION,     /**< stored as __uint32_t*__ */
328     LY_STMT_UNIQUE,       /**< stored as ::lys_unique* */
329     LY_STMT_MODULE,       /**< stored as ::lys_module* */
330     LY_STMT_ACTION,       /**< stored as ::lys_node_rpc_action*, part of the data tree */
331     LY_STMT_ANYDATA,      /**< stored as ::lys_node_anydata*, part of the data tree  */
332     LY_STMT_ANYXML,       /**< stored as ::lys_node_anydata*, part of the data tree  */
333     LY_STMT_CASE,         /**< stored as ::lys_node_case*, part of the data tree  */
334     LY_STMT_CHOICE,       /**< stored as ::lys_node_choice*, part of the data tree  */
335     LY_STMT_CONTAINER,    /**< stored as ::lys_node_container*, part of the data tree  */
336     LY_STMT_GROUPING,     /**< stored as ::lys_node_grp*, part of the data tree  */
337     LY_STMT_INPUT,        /**< stored as ::lys_node_inout*, part of the data tree, but it cannot appear multiple times */
338     LY_STMT_LEAF,         /**< stored as ::lys_node_leaf*, part of the data tree  */
339     LY_STMT_LEAFLIST,     /**< leaf-list, stored as ::lys_node_leaflist*, part of the data tree  */
340     LY_STMT_LIST,         /**< stored as ::lys_node_list*, part of the data tree  */
341     LY_STMT_NOTIFICATION, /**< stored as ::lys_node_notif*, part of the data tree  */
342     LY_STMT_OUTPUT,       /**< stored as ::lys_node_anydata*, part of the data tree, but it cannot apper multiple times */
343     LY_STMT_USES,         /**< stored as ::lys_node_uses*, part of the data tree  */
344     LY_STMT_TYPEDEF,      /**< stored as ::lys_tpdf* */
345     LY_STMT_TYPE,         /**< stored as ::lys_type* */
346     LY_STMT_IFFEATURE,    /**< if-feature, stored as ::lys_iffeature* */
347     LY_STMT_LENGTH,       /**< stored as ::lys_restr* */
348     LY_STMT_MUST,         /**< stored as ::lys_restr* */
349     LY_STMT_PATTERN,      /**< stored as ::lys_restr* */
350     LY_STMT_RANGE,        /**< stored as ::lys_restr* */
351     LY_STMT_WHEN,         /**< stored as ::lys_when* */
352     LY_STMT_REVISION,     /**< stored as ::lys_revision */
353     LY_STMT_SUBMODULE,    /**< not supported - submodules are tightly connected with their modules so it does not make
354                                any sense to have them instantiated under an extension instance */
355     LY_STMT_RPC,          /**< not supported, use actions instead */
356     LY_STMT_BIT,          /**< not supported in extension instances */
357     LY_STMT_ENUM,         /**< not supported in extension instances */
358     LY_STMT_REFINE,       /**< not supported in extension instances */
359     LY_STMT_AUGMENT,      /**< not supported in extension instances */
360     LY_STMT_DEVIATE,      /**< not supported in extension instances */
361     LY_STMT_DEVIATION,    /**< not supported in extension instances */
362     LY_STMT_EXTENSION,    /**< not supported in extension instances */
363     LY_STMT_FEATURE,      /**< not supported in extension instances */
364     LY_STMT_IDENTITY,     /**< not supported in extension instances */
365     LY_STMT_IMPORT,       /**< not supported in extension instances */
366     LY_STMT_INCLUDE,      /**< not supported in extension instances */
367 } LY_STMT;
368 
369 /**
370  * @brief Possible cardinalities of the YANG statements.
371  *
372  * Used in extensions plugins to define cardinalities of the extension instance substatements.
373  */
374 typedef enum {
375     LY_STMT_CARD_OPT,    /* 0..1 */
376     LY_STMT_CARD_MAND,   /* 1 */
377     LY_STMT_CARD_SOME,   /* 1..n */
378     LY_STMT_CARD_ANY     /* 0..n */
379 } LY_STMT_CARD;
380 
381 /**
382  * @brief Extension types
383  */
384 typedef enum {
385     LYEXT_ERR = -1,                /**< error value when #LYEXT_TYPE is expected as return value of a function */
386     LYEXT_FLAG = 0,                /**< simple extension with no substatements;
387                                         instance is stored directly as ::lys_ext_instance and no cast is needed;
388                                         plugin is expected directly as ::lyext_plugin and no cast is done */
389     LYEXT_COMPLEX                  /**< complex extension with YANG substatement(s);
390                                         instance is stored as ::lys_ext_instance_complex to which it can be cast from
391                                         ::lys_ext_instance;
392                                         plugin is expected as ::lyext_plugin_complex to which it can be cast from
393                                         ::lyext_plugin */
394 } LYEXT_TYPE;
395 
396 /**
397  * @defgroup extflags Extension flags
398  * @ingroup extensions
399  *
400  * Various flags for extensions.
401 
402  * @{
403  */
404 #define LYEXT_OPT_INHERIT    0x01    /**< When instantiated in lys_node, the extension is supposed to be inherited
405                                           into the children lys_node elements. The plugin can affect inheriting by a
406                                           callback to decide if the extension instance is supposed to be inherited.
407                                           The extension instance with this flag is not printed and it is just a shadow
408                                           copy of the original extension instance in some of the parents. */
409 /** @cond INTERNAL */
410 #define LYEXT_OPT_YANG       0x02    /**< temporarily stored pointer to string, which contain prefix and name of extension */
411 #define LYEXT_OPT_CONTENT    0x04    /**< content of lys_ext_instance_complex is copied from source (not dup, just memcpy). */
412 /** @endcond */
413 #define LYEXT_OPT_VALID      0x08    /**< needed to call calback for validation */
414 #define LYEXT_OPT_VALID_SUBTREE 0x10 /**< The plugin needs to do validation on nodes in the subtree of the extended node
415                                           (i.e. not only the extended node nor its direct children). valid_data callback
416                                           will be called when any descendant node in the subtree of the extended node is
417                                           modified. */
418 #define LYEXT_OPT_PLUGIN1    0x0100  /**< reserved flag for plugin-specific use */
419 #define LYEXT_OPT_PLUGIN2    0x0200  /**< reserved flag for plugin-specific use */
420 #define LYEXT_OPT_PLUGIN3    0x0400  /**< reserved flag for plugin-specific use */
421 #define LYEXT_OPT_PLUGIN4    0x0800  /**< reserved flag for plugin-specific use */
422 #define LYEXT_OPT_PLUGIN5    0x1000  /**< reserved flag for plugin-specific use */
423 #define LYEXT_OPT_PLUGIN6    0x2000  /**< reserved flag for plugin-specific use */
424 #define LYEXT_OPT_PLUGIN7    0x4000  /**< reserved flag for plugin-specific use */
425 #define LYEXT_OPT_PLUGIN8    0x8000  /**< reserved flag for plugin-specific use */
426 /**
427  * @}
428  */
429 
430 /**
431  * @brief Description of the extension instance substatement.
432  *
433  * Provided by extensions plugins to libyang to be able to parse the content of extension instances.
434  */
435 struct lyext_substmt {
436     LY_STMT stmt;              /**< allowed substatement */
437     size_t offset;             /**< offset in the ::lys_ext_instance_complex#content */
438     LY_STMT_CARD cardinality;  /**< cardinality of the substatement */
439 };
440 
441 /**
442  * @brief YANG extension definition
443  */
444 struct lys_ext {
445     const char *name;                /**< extension name */
446     const char *dsc;                 /**< description statement (optional) */
447     const char *ref;                 /**< reference statement (optional) */
448     uint16_t flags;                  /**< LYS_STATUS_* and LYS_YINELEM values (@ref snodeflags) */
449     uint8_t ext_size;                /**< number of elements in #ext array */
450     uint8_t padding[5];              /**< padding for compatibility with ::lys_node */
451     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
452     const char *argument;            /**< argument name, NULL if not specified, replacement for ::lys_node's iffeature */
453     struct lys_module *module;       /**< link to the extension's data model */
454     struct lyext_plugin *plugin;     /**< pointer to the plugin's data if any */
455 };
456 
457 /**
458  * @brief Generic extension instance structure
459  *
460  * The structure can be cast to another lys_ext_instance_* structure according to the extension type
461  * that can be get via lys_ext_type() function. Check the #LYEXT_TYPE values to get know the specific mapping
462  * between the extension type and lys_ext_instance_* structures.
463  */
464 struct lys_ext_instance {
465     struct lys_ext *def;             /**< definition of the instantiated extension,
466                                           according to the type in the extension's plugin structure, the
467                                           structure can be cast to the more specific structure */
468     void *parent;                    /**< pointer to the parent element holding the extension instance(s), use
469                                           ::lys_ext_instance#parent_type to access the schema element */
470     const char *arg_value;           /**< value of the instance's argument, if defined */
471     uint16_t flags;                  /**< [extension flags](@ref extflags) */
472     uint8_t ext_size;                /**< number of elements in #ext array */
473     uint8_t insubstmt_index;         /**< since some of the statements can appear multiple times, it is needed to
474                                           keep the position of the specific statement instance which contains
475                                           this extension instance. Order of both, the extension and the statement,
476                                           instances is the same. The index is filled only for LYEXT_SUBSTMT_BASE,
477                                           LYEXT_SUBSTMT_DEFAULT and LYEXT_SUBSTMT_UNIQUE values of the
478                                           ::lys_ext_instance#insubstmt member. To get the correct pointer to the
479                                           data connected with the index, use lys_ext_instance_substmt() */
480     uint8_t insubstmt;               /**< #LYEXT_SUBSTMT - id for the case the extension instance is actually inside
481                                           some of the node's members (substatements). libyang does not store extension
482                                           instances for all possible statements to save some, commonly unused, space. */
483     uint8_t parent_type;             /**< #LYEXT_PAR - type of the parent structure */
484     uint8_t ext_type;                /**< extension type (#LYEXT_TYPE) */
485     uint8_t padding;                 /**< 32b padding */
486     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
487     void *priv;                      /**< private caller's data, not used by libyang */
488     struct lys_module *module;       /**< pointer to the extension instance's module (mandatory) */
489     LYS_NODE nodetype;               /**< LYS_EXT */
490 };
491 
492 /**
493  * @brief Complex extension instance structure
494  *
495  * The structure extends the generic ::lys_ext_instance structure to be able to hold substatements as defined by the
496  * plugin.
497  */
498 struct lys_ext_instance_complex {
499     struct lys_ext *def;             /**< definition of the instantiated extension, the plugin's type is #LYEXT_COMPLEX */
500     void *parent;                    /**< pointer to the parent element holding the extension instance(s), use
501                                           ::lys_ext_instance#parent_type to access the schema element */
502     const char *arg_value;           /**< value of the instance's argument, if defined */
503     uint16_t flags;                  /**< [extension flags](@ref extflags) */
504     uint8_t ext_size;                /**< number of elements in #ext array */
505     uint8_t insubstmt_index;         /**< since some of the statements can appear multiple times, it is needed to
506                                           keep the position of the specific statement instance which contains
507                                           this extension instance. Order of both, the extension and the statement,
508                                           instances is the same. The index is filled only for LYEXT_SUBSTMT_BASE,
509                                           LYEXT_SUBSTMT_DEFAULT and LYEXT_SUBSTMT_UNIQUE values of the
510                                           ::lys_ext_instance#insubstmt member. To get the correct pointer to the
511                                           data connected with the index, use lys_ext_instance_substmt() */
512     uint8_t insubstmt;               /**< #LYEXT_SUBSTMT - id for the case the extension instance is actually inside
513                                           some of the node's members (substatements). libyang does not store extension
514                                           instances for all possible statements to save some, commonly unused, space. */
515     uint8_t parent_type;             /**< #LYEXT_PAR - type of the parent structure */
516     uint8_t ext_type;                /**< extension type (#LYEXT_TYPE) */
517     uint8_t padding;                 /**< 32b padding */
518     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
519     void *priv;                      /**< private caller's data, not used by libyang */
520     struct lys_module *module;       /**< pointer to the extension instance's module (mandatory) */
521     LYS_NODE nodetype;               /**< LYS_EXT */
522 
523     /* to this point the structure is compatible with the generic ::lys_ext_instance structure */
524     struct lyext_substmt *substmt;   /**< pointer to the plugin's list of substatements' information */
525     char content[1];                 /**< content of the extension instance */
526 };
527 
528 /**
529  * @brief Get address of the substatement structure to which the extension instance refers.
530  *
531  * If the extension instance's substmt value is 0, NULL is returned (extension instance refers to the parent, not to
532  * any of the parent's substatements).
533  *
534  * Returned pointer is supposed to be cast according to the extension instance's substmt value:
535  * - #LYEXT_SUBSTMT_ARGUMENT     -> const char* (lys_ext_instance.arg_value)
536  * - #LYEXT_SUBSTMT_BASE         -> struct lys_ident* (lys_type.info.ident.ref[index] or lys_ident.base[index])
537  * - #LYEXT_SUBSTMT_BELONGSTO    -> struct lys_module* (lys_submodule.belongsto)
538  * - #LYEXT_SUBSTMT_CONFIG       -> uint16_t* (e.g. lys_node.flags, use #LYS_CONFIG_MASK to get only the config flag)
539  * - #LYEXT_SUBSTMT_CONTACT      -> const char* (e.g. lys_module.contact)
540  * - #LYEXT_SUBSTMT_DEFAULT      -> const char* (e.g. lys_node_leaflist.dflt[index]) or struct lys_node*
541  *                                  (lys_node_choice.dflt) depending on the parent
542  * - #LYEXT_SUBSTMT_DESCRIPTION  -> const char* (e.g. lys_module.dsc)
543  * - #LYEXT_SUBSTMT_ERRTAG       -> const char* (lys_restr.eapptag)
544  * - #LYEXT_SUBSTMT_ERRMSG       -> const char* (lys_restr.emsg)
545  * - #LYEXT_SUBSTMT_DIGITS       -> uint8_t* (lys_type.info.dec64.dig)
546  * - #LYEXT_SUBSTMT_KEY          -> struct lys_node_leaf** (lys_node_list.keys)
547  * - #LYEXT_SUBSTMT_MANDATORY    -> uint16_t* (e.g. lys_node.flags, use #LYS_MAND_MASK to get only the mandatory flag)
548  * - #LYEXT_SUBSTMT_MAX          -> uint32_t* (e.g. lys_node_list.max)
549  * - #LYEXT_SUBSTMT_MIN          -> uint32_t* (e.g. lys_node_list.min)
550  * - #LYEXT_SUBSTMT_MODIFIER     -> NULL, the substatement is stored as a special value of the first byte of the
551  *                                  restriction's expression (ly_restr.expr[0])
552  * - #LYEXT_SUBSTMT_NAMESPACE    -> cont char* (lys_module.ns)
553  * - #LYEXT_SUBSTMT_ORDEREDBY    -> uint16_t* (e.g. lys_node.flags, use #LYS_USERORDERED as mask to get the flag)
554  * - #LYEXT_SUBSTMT_ORGANIZATION -> const char* (e.g. lys_module.org)
555  * - #LYEXT_SUBSTMT_PATH         -> const char* (lys_type.info.lref.path)
556  * - #LYEXT_SUBSTMT_POSITION     -> uint32_t* (bit.pos)
557  * - #LYEXT_SUBSTMT_PREFIX       -> const char* (e.g. lys_module.prefix)
558  * - #LYEXT_SUBSTMT_PRESENCE     -> const char* (lys_node_container.presence)
559  * - #LYEXT_SUBSTMT_REFERENCE    -> const char* (e.g. lys_node.ref)
560  * - #LYEXT_SUBSTMT_REQINSTANCE  -> int8_t* (lys_type.info.lref.req or lys_type.info.inst.req)
561  * - #LYEXT_SUBSTMT_REVISIONDATE -> const char* (e.g. lys_import.rev)
562  * - #LYEXT_SUBSTMT_STATUS       -> uint16_t* (e.g. lys_node.flags, use #LYS_STATUS_MASK to get only the status flag)
563  * - #LYEXT_SUBSTMT_UNIQUE       -> struct lys_unique* (lys_node_list.unique[index])
564  * - #LYEXT_SUBSTMT_UNITS        -> const char* (e.g. lys_node_leaf.units)
565  * - #LYEXT_SUBSTMT_VALUE        -> int32_t* (enm.value
566  * - #LYEXT_SUBSTMT_VERSION      -> NULL, the version is stored as a bit-field value so the address cannot be returned,
567  *                                  however the value can be simply accessed as ((struct lys_module*)ext->parent)->version
568  * - #LYEXT_SUBSTMT_YINELEM      -> NULL, the substatement is stored as a flag
569  *
570  * @param[in] ext The extension instance to explore
571  * @return Pointer to the data connected with the statement where the extension was instantiated. Details about
572  * casting the returned pointer are described above.
573  */
574 const void *lys_ext_instance_substmt(const struct lys_ext_instance *ext);
575 
576 /**
577  * @brief Get the position of the extension instance in the extensions list.
578  *
579  * @param[in] def Definition of the extension to search
580  * @param[in] ext Extensions list as they are stored in the schema tree nodes
581  * @param[in] ext_size Number of items in the extensions list
582  * @return -1 in case the extension is not present in the list, index of the extension in the provided list otherwise
583  */
584 int lys_ext_instance_presence(struct lys_ext *def, struct lys_ext_instance **ext, uint8_t ext_size);
585 
586 /**
587  * @brief get pointer to the place where the specified extension's substatement is supposed to be stored in the complex
588  * extension instance.
589  *
590  * @param[in] stmt Substatement to get
591  * @param[in] ext Complex extension instance to be explored.
592  * @param[out] info Optional output parameter providing information about the \p stmt from the plugin.
593  * @return Address of the storage in the \p ext, NULL if the substatement is not allowed in this extension or any other
594  * error (e.g. invalid input data).
595  */
596 void *lys_ext_complex_get_substmt(LY_STMT stmt, struct lys_ext_instance_complex *ext, struct lyext_substmt **info);
597 
598 /**
599  * @brief Get list of all the loaded plugins, both extension and user type ones.
600  *
601  * @return Const list of all the plugin names finished with NULL.
602  */
603 const char * const *ly_get_loaded_plugins(void);
604 
605 /**
606  * @brief Load the available YANG extension and type plugins from the plugin directory (LIBDIR/libyang/).
607  *
608  * This function is automatically called whenever a new context is created. Note that the removed plugins are kept
609  * in use until all the created contexts are destroyed via ly_ctx_destroy(), so only the newly added plugins are
610  * usually loaded by this function.
611  */
612 void ly_load_plugins(void);
613 
614 /* don't need the contents of these types, just forward-declare them for the next 2 functions. */
615 struct lyext_plugin_list;
616 struct lytype_plugin_list;
617 
618 /**
619  * @brief Directly register a YANG extension by pointer.
620  *
621  * This is intended to be called by executables or libraries using libyang, while bringing along their own
622  * application-specific extensions.  Instead of loading them from separate module files through dlopen (which can
623  * introduce additional problems like mismatching or incorrectly installed modules), they can be directly added
624  * by reference.
625  */
626 int ly_register_exts(struct lyext_plugin_list *plugin, const char *log_name);
627 
628 /**
629  * @brief Directly register a YANG type by pointer.
630  *
631  * This is the analog of ly_register_exts(), for types instead of extensions.
632  */
633 int ly_register_types(struct lytype_plugin_list *plugin, const char *log_name);
634 
635 /**
636  * @brief Unload all the YANG extension and type plugins.
637  *
638  * This function is automatically called whenever the context is destroyed. Note, that in case there is still a
639  * libyang context in use, the function does nothing since unloading the plugins would break the context's modules
640  * which may refer/use the plugins.
641  *
642  * Since the function is called with ly_ctx_destroy(), there is usually no need to call this function manually.
643  */
644 int ly_clean_plugins(void);
645 
646 /**
647  * @}
648  */
649 
650 /**
651  * @brief supported YANG schema version values
652  */
653 typedef enum LYS_VERSION {
654     LYS_VERSION_UNDEF = 0,  /**< no specific version, YANG 1.0 as default */
655     LYS_VERSION_1 = 1,      /**< YANG 1.0 */
656     LYS_VERSION_1_1 = 2     /**< YANG 1.1 */
657 } LYS_VERSION;
658 
659 /**
660  * @brief Main schema node structure representing YANG module.
661  *
662  * Compatible with ::lys_submodule structure with exception of the last, #ns member, which is replaced by
663  * ::lys_submodule#belongsto member. Sometimes, ::lys_submodule can be provided casted to ::lys_module. Such a thing
664  * can be determined via the #type member value.
665  */
666 struct lys_module {
667     struct ly_ctx *ctx;              /**< libyang context of the module (mandatory) */
668     const char *name;                /**< name of the module (mandatory) */
669     const char *prefix;              /**< prefix of the module (mandatory) */
670     const char *dsc;                 /**< description of the module */
671     const char *ref;                 /**< cross-reference for the module */
672     const char *org;                 /**< party/company responsible for the module */
673     const char *contact;             /**< contact information for the module */
674     const char *filepath;            /**< path, if the schema was read from a file, NULL in case of reading from memory */
675     uint8_t type:1;                  /**< 0 - structure type used to distinguish structure from ::lys_submodule */
676     uint8_t version:3;               /**< yang-version (LYS_VERSION):
677                                           - 0 = not specified, YANG 1.0 as default,
678                                           - 1 = YANG 1.0,
679                                           - 2 = YANG 1.1 */
680     uint8_t deviated:2;              /**< deviated flag:
681                                           - 0 = not deviated,
682                                           - 1 = the module is deviated by another module,
683                                           - 2 = deviation applied to this module are temporarily off */
684     uint8_t disabled:1;              /**< flag if the module is disabled in the context */
685     uint8_t implemented:1;           /**< flag if the module is implemented, not just imported */
686     uint8_t latest_revision:1;       /**< flag if the module was loaded without specific revision and is
687                                           the latest revision found */
688     uint8_t padding1:7;              /**< padding for 32b alignment */
689     uint8_t padding2[2];
690 
691     /* array sizes */
692     uint8_t rev_size;                /**< number of elements in #rev array */
693     uint8_t imp_size;                /**< number of elements in #imp array */
694     uint8_t inc_size;                /**< number of elements in #inc array */
695 
696     uint16_t ident_size;             /**< number of elements in #ident array */
697     uint16_t tpdf_size;              /**< number of elements in #tpdf array */
698 
699     uint8_t features_size;           /**< number of elements in #features array */
700     uint8_t augment_size;            /**< number of elements in #augment array */
701     uint8_t deviation_size;          /**< number of elements in #deviation array */
702     uint8_t extensions_size;         /**< number of elements in #extensions array */
703     uint8_t ext_size;                /**< number of elements in #ext array */
704 
705     struct lys_revision *rev;        /**< array of the module revisions, revisions[0] is always the last (newest)
706                                           revision of the module */
707     struct lys_import *imp;          /**< array of imported modules */
708     struct lys_include *inc;         /**< array of included submodules */
709     struct lys_tpdf *tpdf;           /**< array of typedefs */
710     struct lys_ident *ident;         /**< array of identities */
711     struct lys_feature *features;    /**< array of feature definitions */
712     struct lys_node_augment *augment;/**< array of augments */
713     struct lys_deviation *deviation; /**< array of specified deviations */
714     struct lys_ext *extensions;      /**< array of specified extensions */
715     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
716 
717     /* specific module's items in comparison to submodules */
718     struct lys_node *data;           /**< first data statement, includes also RPCs and Notifications */
719     const char *ns;                  /**< namespace of the module (mandatory) */
720 };
721 
722 /**
723  * @brief Submodule schema node structure that can be included into a YANG module.
724  *
725  * Compatible with ::lys_module structure with exception of the last, #belongsto member, which is replaced by
726  * ::lys_module#data and ::lys_module#ns members. Sometimes, ::lys_submodule can be provided casted to ::lys_module.
727  * Such a thing can be determined via the #type member value.
728  */
729 struct lys_submodule {
730     struct ly_ctx *ctx;              /**< libyang context of the submodule (mandatory) */
731     const char *name;                /**< name of the submodule (mandatory) */
732     const char *prefix;              /**< prefix of the belongs-to module */
733     const char *dsc;                 /**< description of the submodule */
734     const char *ref;                 /**< cross-reference for the submodule */
735     const char *org;                 /**< party responsible for the submodule */
736     const char *contact;             /**< contact information for the submodule */
737     const char *filepath;            /**< path to the file from which the submodule was read */
738     uint8_t type:1;                  /**< 1 - structure type used to distinguish structure from ::lys_module */
739     uint8_t version:3;               /**< yang-version (LYS_VERSION):
740                                           - 0 = not specified, YANG 1.0 as default,
741                                           - 1 = YANG 1.0,
742                                           - 2 = YANG 1.1 */
743     uint8_t deviated:2;              /**< deviated flag (same as in main module):
744                                           - 0 = not deviated,
745                                           - 1 = the module is deviated by another module,
746                                           - 2 = deviation applied to this module are temporarily off */
747     uint8_t disabled:1;              /**< flag if the module is disabled in the context (same as in main module) */
748     uint8_t implemented:1;           /**< flag if the module is implemented, not just imported (same as in main module) */
749     uint8_t padding[3];              /**< padding for 32b alignment */
750 
751     /* array sizes */
752     uint8_t rev_size;                /**< number of elements in #rev array */
753     uint8_t imp_size;                /**< number of elements in #imp array */
754     uint8_t inc_size;                /**< number of elements in #inc array */
755 
756     uint16_t ident_size;             /**< number of elements in #ident array */
757     uint16_t tpdf_size;              /**< number of elements in #tpdf array */
758 
759     uint8_t features_size;           /**< number of elements in #features array */
760     uint8_t augment_size;            /**< number of elements in #augment array */
761     uint8_t deviation_size;          /**< number of elements in #deviation array */
762     uint8_t extensions_size;         /**< number of elements in #extensions array */
763     uint8_t ext_size;                /**< number of elements in #ext array */
764 
765     struct lys_revision *rev;        /**< array of the module revisions, revisions[0] is always the last (newest)
766                                           revision of the submodule */
767     struct lys_import *imp;          /**< array of imported modules */
768     struct lys_include *inc;         /**< array of included submodules */
769     struct lys_tpdf *tpdf;           /**< array of typedefs */
770     struct lys_ident *ident;         /**< array if identities */
771     struct lys_feature *features;    /**< array of feature definitions */
772     struct lys_node_augment *augment;/**< array of augments */
773     struct lys_deviation *deviation; /**< array of specified deviations */
774     struct lys_ext *extensions;      /**< array of specified extensions */
775     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
776 
777     /* specific submodule's items in comparison to modules */
778     struct lys_module *belongsto;    /**< belongs-to (parent module) */
779 };
780 
781 /**
782  * @brief YANG built-in types
783  */
784 typedef enum {
785     LY_TYPE_DER = 0,      /**< Derived type */
786     LY_TYPE_BINARY,       /**< Any binary data ([RFC 6020 sec 9.8](http://tools.ietf.org/html/rfc6020#section-9.8)) */
787     LY_TYPE_BITS,         /**< A set of bits or flags ([RFC 6020 sec 9.7](http://tools.ietf.org/html/rfc6020#section-9.7)) */
788     LY_TYPE_BOOL,         /**< "true" or "false" ([RFC 6020 sec 9.5](http://tools.ietf.org/html/rfc6020#section-9.5)) */
789     LY_TYPE_DEC64,        /**< 64-bit signed decimal number ([RFC 6020 sec 9.3](http://tools.ietf.org/html/rfc6020#section-9.3))*/
790     LY_TYPE_EMPTY,        /**< A leaf that does not have any value ([RFC 6020 sec 9.11](http://tools.ietf.org/html/rfc6020#section-9.11)) */
791     LY_TYPE_ENUM,         /**< Enumerated strings ([RFC 6020 sec 9.6](http://tools.ietf.org/html/rfc6020#section-9.6)) */
792     LY_TYPE_IDENT,        /**< A reference to an abstract identity ([RFC 6020 sec 9.10](http://tools.ietf.org/html/rfc6020#section-9.10)) */
793     LY_TYPE_INST,         /**< References a data tree node ([RFC 6020 sec 9.13](http://tools.ietf.org/html/rfc6020#section-9.13)) */
794     LY_TYPE_LEAFREF,      /**< A reference to a leaf instance ([RFC 6020 sec 9.9](http://tools.ietf.org/html/rfc6020#section-9.9))*/
795     LY_TYPE_STRING,       /**< Human-readable string ([RFC 6020 sec 9.4](http://tools.ietf.org/html/rfc6020#section-9.4)) */
796     LY_TYPE_UNION,        /**< Choice of member types ([RFC 6020 sec 9.12](http://tools.ietf.org/html/rfc6020#section-9.12)) */
797     LY_TYPE_INT8,         /**< 8-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
798     LY_TYPE_UINT8,        /**< 8-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
799     LY_TYPE_INT16,        /**< 16-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
800     LY_TYPE_UINT16,       /**< 16-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
801     LY_TYPE_INT32,        /**< 32-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
802     LY_TYPE_UINT32,       /**< 32-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
803     LY_TYPE_INT64,        /**< 64-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
804     LY_TYPE_UINT64,       /**< 64-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
805     LY_TYPE_UNKNOWN,      /**< Unknown type (used in edit-config leaves) */
806 } LY_DATA_TYPE;
807 #define LY_DATA_TYPE_COUNT 20 /**< Number of different types */
808 
809 /**
810  *
811  */
812 struct lys_type_info_binary {
813     struct lys_restr *length;    /**< length restriction (optional), see
814                                       [RFC 6020 sec. 9.4.4](http://tools.ietf.org/html/rfc6020#section-9.4.4) */
815 };
816 
817 /**
818  * @brief Single bit value specification for ::lys_type_info_bits.
819  */
820 struct lys_type_bit {
821     const char *name;                /**< bit's name (mandatory) */
822     const char *dsc;                 /**< bit's description (optional) */
823     const char *ref;                 /**< bit's reference (optional) */
824     uint16_t flags;                  /**< bit's flags, whether the position was auto-assigned
825                                           and the status(one of LYS_NODE_STATUS_* values or 0 for default) */
826     uint8_t ext_size;                /**< number of elements in #ext array */
827     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
828 
829     /* 32b padding for compatibility with ::lys_node */
830     uint32_t pos;                    /**< bit's position (mandatory) */
831 
832     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
833     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
834 };
835 
836 /**
837  * @brief Container for information about bits types (#LY_TYPE_BINARY), used in ::lys_type_info.
838  */
839 struct lys_type_info_bits {
840     struct lys_type_bit *bit;/**< array of bit definitions */
841     unsigned int count;      /**< number of bit definitions in the bit array */
842 };
843 
844 /**
845  * @brief Container for information about decimal64 types (#LY_TYPE_DEC64), used in ::lys_type_info.
846  */
847 struct lys_type_info_dec64 {
848     struct lys_restr *range; /**< range restriction (optional), see
849                                   [RFC 6020 sec. 9.2.4](http://tools.ietf.org/html/rfc6020#section-9.2.4) */
850     uint8_t dig;             /**< fraction-digits restriction (mandatory). Note that in case of types not directly
851                                   derived from built-in decimal64, dig is present even it cannot be specified in schema.
852                                   That's because the value is inherited for simpler access to the value and easier
853                                   manipulation with the decimal64 data */
854     uint64_t div;            /**< auxiliary value for moving decimal point (dividing the stored value to get the real value) */
855 };
856 
857 /**
858  * @brief Single enumeration value specification for ::lys_type_info_enums.
859  */
860 struct lys_type_enum {
861     const char *name;                /**< enum's name (mandatory) */
862     const char *dsc;                 /**< enum's description (optional) */
863     const char *ref;                 /**< enum's reference (optional) */
864     uint16_t flags;                  /**< enum's flags, whether the value was auto-assigned
865                                           and the status(one of LYS_NODE_STATUS_* values or 0 for default) */
866     uint8_t ext_size;                /**< number of elements in #ext array */
867     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
868 
869     /* 32b padding for compatibility with ::lys_node */
870     int32_t value;                   /**< enum's value (mandatory) */
871 
872     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
873     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
874 };
875 
876 /**
877  * @brief Container for information about enumeration types (#LY_TYPE_ENUM), used in ::lys_type_info.
878  */
879 struct lys_type_info_enums {
880     struct lys_type_enum *enm;/**< array of enum definitions */
881     unsigned int count;       /**< number of enum definitions in the enm array */
882 };
883 
884 /**
885  * @brief Container for information about identity types (#LY_TYPE_IDENT), used in ::lys_type_info.
886  */
887 struct lys_type_info_ident {
888     struct lys_ident **ref;   /**< array of pointers (reference) to the identity definition (mandatory) */
889     unsigned int count;       /**< number of base identity references */
890 };
891 
892 /**
893  * @brief Container for information about instance-identifier types (#LY_TYPE_INST), used in ::lys_type_info.
894  */
895 struct lys_type_info_inst {
896     int8_t req;              /**< require-instance restriction, see
897                                   [RFC 6020 sec. 9.13.2](http://tools.ietf.org/html/rfc6020#section-9.13.2):
898                                   - -1 = false,
899                                   - 0 not defined (true),
900                                   - 1 = true */
901 };
902 
903 /**
904  * @brief Container for information about integer types, used in ::lys_type_info.
905  */
906 struct lys_type_info_num {
907     struct lys_restr *range; /**< range restriction (optional), see
908                                   [RFC 6020 sec. 9.2.4](http://tools.ietf.org/html/rfc6020#section-9.2.4) */
909 };
910 
911 /**
912  * @brief Container for information about leafref types (#LY_TYPE_LEAFREF), used in ::lys_type_info.
913  */
914 struct lys_type_info_lref {
915     const char *path;        /**< path to the referred leaf or leaf-list node (mandatory), see
916                                   [RFC 6020 sec. 9.9.2](http://tools.ietf.org/html/rfc6020#section-9.9.2) */
917     struct lys_node_leaf* target; /**< target schema node according to path */
918     int8_t req;              /**< require-instance restriction:
919                                   - -1 = false,
920                                   - 0 not defined (true),
921                                   - 1 = true */
922 };
923 
924 /**
925  * @brief Container for information about string types (#LY_TYPE_STRING), used in ::lys_type_info.
926  */
927 struct lys_type_info_str {
928     struct lys_restr *length;/**< length restriction (optional), see
929                                   [RFC 6020 sec. 9.4.4](http://tools.ietf.org/html/rfc6020#section-9.4.4) */
930     struct lys_restr *patterns; /**< array of pattern restrictions (optional), see
931                                   [RFC 6020 sec. 9.4.6](http://tools.ietf.org/html/rfc6020#section-9.4.6)
932                                   In each pattern, the first byte of expr is modifier:
933                                   - 0x06 (ACK) for match
934                                   - 0x15 (NACK) for invert-match
935                                   So the expression itself always starts at expr[1] */
936     unsigned int pat_count;  /**< number of pattern definitions in the patterns array */
937 #ifdef LY_ENABLED_CACHE
938     void **patterns_pcre;    /**< array of compiled patterns to optimize its evaluation, represented as
939                                   array of pointers to results of pcre_compile() and pcre_study().
940                                   For internal use only. */
941 #endif
942 };
943 
944 /**
945  * @brief Container for information about union types (#LY_TYPE_UNION), used in ::lys_type_info.
946  */
947 struct lys_type_info_union {
948     struct lys_type *types;  /**< array of union's subtypes */
949     unsigned int count;      /**< number of subtype definitions in types array */
950     int has_ptr_type;        /**< types include an instance-identifier or leafref meaning the union must always be resolved
951                                   after parsing */
952 };
953 
954 /**
955  * @brief Union for holding type-specific information in ::lys_type.
956  */
957 union lys_type_info {
958     struct lys_type_info_binary binary; /**< part for #LY_TYPE_BINARY */
959     struct lys_type_info_bits bits;     /**< part for #LY_TYPE_BITS */
960     struct lys_type_info_dec64 dec64;   /**< part for #LY_TYPE_DEC64 */
961     struct lys_type_info_enums enums;   /**< part for #LY_TYPE_ENUM */
962     struct lys_type_info_ident ident;   /**< part for #LY_TYPE_IDENT */
963     struct lys_type_info_inst inst;     /**< part for #LY_TYPE_INST */
964     struct lys_type_info_num num;       /**< part for integer types */
965     struct lys_type_info_lref lref;     /**< part for #LY_TYPE_LEAFREF */
966     struct lys_type_info_str str;       /**< part for #LY_TYPE_STRING */
967     struct lys_type_info_union uni;     /**< part for #LY_TYPE_UNION */
968 };
969 
970 /**
971  * @brief YANG type structure providing information from the schema
972  */
973 struct lys_type {
974     LY_DATA_TYPE _PACKED base;       /**< base type */
975     uint8_t value_flags;             /**< value type flags */
976     uint8_t ext_size;                /**< number of elements in #ext array */
977     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
978     struct lys_tpdf *der;            /**< pointer to the superior typedef. If NULL,
979                                           structure provides information about one of the built-in types */
980     struct lys_tpdf *parent;         /**< except ::lys_tpdf, it can points also to ::lys_node_leaf or ::lys_node_leaflist
981                                           so access only the compatible members! */
982     union lys_type_info info;        /**< detailed type-specific information */
983     /*
984      * here is an overview of the info union:
985      * LY_TYPE_BINARY (binary)
986      * struct lys_restr *binary.length;   length restriction (optional), see
987      *                                    [RFC 6020 sec. 9.4.4](http://tools.ietf.org/html/rfc6020#section-9.4.4)
988      * -----------------------------------------------------------------------------------------------------------------
989      * LY_TYPE_BITS (bits)
990      * struct lys_type_bit *bits.bit;     array of bit definitions
991      *   const char *bits.bit[i].name;    bit's name (mandatory)
992      *   const char *bits.bit[i].dsc;     bit's description (optional)
993      *   const char *bits.bit[i].ref;     bit's reference (optional)
994      *   uint8_t bits.bit[i].flags;       bit's flags, whether the position was auto-assigned
995      *                                    and the status(one of LYS_NODE_STATUS_* values or 0 for default)
996      *   uint8_t bits.bit[i].iffeature_size;            number of elements in the bit's #iffeature array
997      *   uint8_t bits.bit[i].ext_size;                  number of elements in the bit's #ext array
998      *   uint32_t bits.bit[i].pos;        bit's position (mandatory)
999      *   struct lys_iffeature *bits.bit[i].iffeature;   array of bit's if-feature expressions
1000      *   struct lys_ext_instance **bits.bit[i].ext;     array of pointers to the bit's extension instances (optional)
1001      * unsigned int bits.count;           number of bit definitions in the bit array
1002      * -----------------------------------------------------------------------------------------------------------------
1003      * LY_TYPE_DEC64 (dec64)
1004      * struct lys_restr *dec64.range;     range restriction (optional), see
1005      *                                    [RFC 6020 sec. 9.2.4](http://tools.ietf.org/html/rfc6020#section-9.2.4)
1006      * struct lys_ext_instance **dec64.ext;             array of pointers to the bit's extension instances (optional)
1007      * uint8_t dec64.ext_size;                          number of elements in the bit's #ext array
1008      * uint8_t dec64.dig;                 fraction-digits restriction (mandatory)
1009      * uint64_t dec64.div;                auxiliary value for moving decimal point (dividing the stored value to get
1010      *                                    the real value) (mandatory, corresponds to the fraction-digits)
1011      * -----------------------------------------------------------------------------------------------------------------
1012      * LY_TYPE_ENUM (enums)
1013      * struct lys_type_enum *enums.enm;   array of enum definitions
1014      *   const char *enums.enm[i].name;   enum's name (mandatory)
1015      *   const char *enums.enm[i].dsc;    enum's description (optional)
1016      *   const char *enums.enm[i].ref;    enum's reference (optional)
1017      *   uint8_t enums.enm[i].flags;      enum's flags, whether the value was auto-assigned
1018      *                                    and the status(one of LYS_NODE_STATUS_* values or 0 for default)
1019      *   uint8_t enums.enum[i].iffeature_size;          number of elements in the bit's #iffeature array
1020      *   uint8_t enums.enum[i].ext_size;                number of elements in the bit's #ext array
1021      *   int32_t enums.enm[i].value;      enum's value (mandatory)
1022      *   struct lys_iffeature *enums.enum[i].iffeature; array of bit's if-feature expressions
1023      *   struct lys_ext_instance **enums.enum[i].ext;   array of pointers to the bit's extension instances (optional)
1024      * unsigned int enums.count;          number of enum definitions in the enm array
1025      * -----------------------------------------------------------------------------------------------------------------
1026      * LY_TYPE_IDENT (ident)
1027      * struct lys_ident **ident.ref;      array of pointers (reference) to the identity definition (mandatory)
1028      * unsigned int ident.count;          number of base identity references
1029      * -----------------------------------------------------------------------------------------------------------------
1030      * LY_TYPE_INST (inst)
1031      * int8_t inst.req;                   require-identifier restriction, see
1032      *                                    [RFC 6020 sec. 9.13.2](http://tools.ietf.org/html/rfc6020#section-9.13.2):
1033      *                                    - -1 = false,
1034      *                                    - 0 not defined,
1035      *                                    - 1 = true
1036      * -----------------------------------------------------------------------------------------------------------------
1037      * LY_TYPE_*INT* (num)
1038      * struct lys_restr *num.range;       range restriction (optional), see
1039      *                                    [RFC 6020 sec. 9.2.4](http://tools.ietf.org/html/rfc6020#section-9.2.4)
1040      * -----------------------------------------------------------------------------------------------------------------
1041      * LY_TYPE_LEAFREF (lref)
1042      * const char *lref.path;             path to the referred leaf or leaf-list node (mandatory), see
1043      *                                    [RFC 6020 sec. 9.9.2](http://tools.ietf.org/html/rfc6020#section-9.9.2)
1044      * struct lys_node_leaf *lref.target; target schema node according to path
1045      * int8_t lref.req;                   require-instance restriction: -1 = false; 0 not defined (true); 1 = true
1046      * -----------------------------------------------------------------------------------------------------------------
1047      * LY_TYPE_STRING (str)
1048      * struct lys_restr *str.length;      length restriction (optional), see
1049      *                                    [RFC 6020 sec. 9.4.4](http://tools.ietf.org/html/rfc6020#section-9.4.4)
1050      * struct lys_restr *str.patterns;    array of pattern restrictions (optional), see
1051      *                                    [RFC 6020 sec. 9.4.6](http://tools.ietf.org/html/rfc6020#section-9.4.6)
1052      * unsigned int str.pat_count;        number of pattern definitions in the patterns array
1053      * -----------------------------------------------------------------------------------------------------------------
1054      * LY_TYPE_UNION (uni)
1055      * struct lys_type *uni.types;        array of union's subtypes
1056      * unsigned int uni.count;            number of subtype definitions in types array
1057      * int uni.has_ptr_type;              types recursively include an instance-identifier or leafref (union must always
1058      *                                    be resolved after it is parsed)
1059      */
1060 };
1061 
1062 #define LYS_IFF_NOT  0x00
1063 #define LYS_IFF_AND  0x01
1064 #define LYS_IFF_OR   0x02
1065 #define LYS_IFF_F    0x03
1066 
1067 /**
1068  * @brief Compiled if-feature expression structure
1069  */
1070 struct lys_iffeature {
1071     uint8_t *expr;                   /**< 2bits array describing the if-feature expression in prefix format */
1072     uint8_t ext_size;                /**< number of elements in #ext array */
1073     struct lys_feature **features;   /**< array of pointers to the features used in expression */
1074     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1075 };
1076 
1077 /**
1078  * @defgroup snodeflags Schema nodes flags
1079  * @ingroup schematree
1080  *
1081  * Various flags for schema nodes.
1082  *
1083  *     1 - container    6 - anydata/anyxml    11 - output       16 - type(def)
1084  *     2 - choice       7 - case              12 - grouping     17 - identity
1085  *     3 - leaf         8 - notification      13 - uses         18 - refine
1086  *     4 - leaflist     9 - rpc               14 - augment      19 - extension
1087  *     5 - list        10 - input             15 - feature
1088  *
1089  *                                            1 1 1 1 1 1 1 1 1 1
1090  *                          1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9
1091  *     --------------------+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1092  *      1 LYS_USESGRP      | | | | | | | | | | | | |x| | | | | | |
1093  *        LYS_AUTOASSIGNED | | | | | | | | | | | | | | | |x| | | |
1094  *        LYS_CONFIG_W     |x|x|x|x|x|x|x| | | | | | | | | | |x| |
1095  *        LYS_NOTAPPLIED   | | | | | | | | | | | | | |x| | | | | |
1096  *        LYS_YINELEM      | | | | | | | | | | | | | | | | | | |x|
1097  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1098  *      2 LYS_CONFIG_R     |x|x|x|x|x|x|x| | | | | | | | | | |x| |
1099  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1100  *      3 LYS_CONFIG_SET   |x|x|x|x|x|x| | | | | | | | | | | | | |
1101  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1102  *      4 LYS_STATUS_CURR  |x|x|x|x|x|x|x|x|x| | |x|x|x|x|x|x| |x|
1103  *        LYS_RFN_MAXSET   | | | | | | | | | | | | | | | | | |x| |
1104  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1105  *      5 LYS_STATUS_DEPRC |x|x|x|x|x|x|x|x|x| | |x|x|x|x|x|x| |x|
1106  *        LYS_RFN_MINSET   | | | | | | | | | | | | | | | | | |x| |
1107  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1108  *      6 LYS_STATUS_OBSLT |x|x|x|x|x|x|x|x|x| | |x|x|x|x|x|x| |x|
1109  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1110  *      7 LYS_MAND_TRUE    | |x|x| | |x| | | | | | | | | | | |x| |
1111  *        LYS_IMPLICIT     | | | | | | |x| | |x|x| | | | | | | | |
1112  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1113  *      8 LYS_MAND_FALSE   | |x|x| | |x| | | | | | | | | | | |x| |
1114  *        LYS_INCL_STATUS  |x| | | |x| | | | | | | | | | | | | | |
1115  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1116  *      9 LYS_USERORDERED  | | | |x|x| | | | | | | | | | | | |r| |
1117  *        LYS_UNIQUE       | | |x| | | | | | | | | | | | | | |r| |
1118  *        LYS_FENABLED     | | | | | | | | | | | | | | |x| | |r| |
1119  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1120  *     10 LYS_XPCONF_DEP   |x|x|x|x|x|x|x|x|x|x|x| |x|x| | | |r| |
1121  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1122  *     11 LYS_XPSTATE_DEP  |x|x|x|x|x|x|x|x|x|x|x| |x|x| | | |r| |
1123  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1124  *     12 LYS_LEAFREF_DEP  |x|x|x|x|x|x|x|x|x|x|x| |x|x| | | |r| |
1125  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1126  *     13 LYS_DFLTJSON     | | |x|x| | | | | | | | | | | |x| |r| |
1127  *                         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1128  *     14 LYS_VALID_EXT    |x| |x|x|x|x| | | | | | | | | |x| | | |
1129  *     --------------------+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1130  *
1131  *     x - used
1132  *     r - reserved for internal use
1133  * @{
1134  */
1135 #define LYS_CONFIG_W     0x01        /**< config true; */
1136 #define LYS_CONFIG_R     0x02        /**< config false; */
1137 #define LYS_CONFIG_SET   0x04        /**< config explicitely set in the node */
1138 #define LYS_CONFIG_MASK  0x03        /**< mask for config value */
1139 #define LYS_STATUS_CURR  0x08        /**< status current; */
1140 #define LYS_STATUS_DEPRC 0x10        /**< status deprecated; */
1141 #define LYS_STATUS_OBSLT 0x20        /**< status obsolete; */
1142 #define LYS_STATUS_MASK  0x38        /**< mask for status value */
1143 #define LYS_RFN_MAXSET   0x08        /**< refine has max-elements set */
1144 #define LYS_RFN_MINSET   0x10        /**< refine has min-elements set */
1145 #define LYS_MAND_TRUE    0x40        /**< mandatory true; applicable only to
1146                                           ::lys_node_choice, ::lys_node_leaf and ::lys_node_anydata */
1147 #define LYS_MAND_FALSE   0x80        /**< mandatory false; applicable only to
1148                                           ::lys_node_choice, ::lys_node_leaf and ::lys_node_anydata */
1149 #define LYS_INCL_STATUS  0x80        /**< flag that the subtree includes status node(s), applicable only to
1150                                           ::lys_node_container and lys_node_list */
1151 #define LYS_MAND_MASK    0xc0        /**< mask for mandatory values */
1152 #define LYS_USERORDERED  0x100       /**< ordered-by user lists, applicable only to
1153                                           ::lys_node_list and ::lys_node_leaflist */
1154 #define LYS_FENABLED     0x100       /**< feature enabled flag, applicable only to ::lys_feature */
1155 #define LYS_UNIQUE       0x100       /**< part of the list's unique, applicable only to ::lys_node_leaf */
1156 #define LYS_AUTOASSIGNED 0x01        /**< value was auto-assigned, applicable only to
1157                                           ::lys_type enum and bits flags */
1158 #define LYS_USESGRP      0x01        /**< flag for resolving uses in groupings, applicable only to ::lys_node_uses */
1159 #define LYS_IMPLICIT     0x40        /**< flag for implicitely created LYS_INPUT, LYS_OUTPUT and LYS_CASE nodes */
1160 #define LYS_XPCONF_DEP   0x200       /**< flag marking nodes, whose validation (when, must expressions)
1161                                           depends on configuration data nodes outside their subtree (applicable only
1162                                           to RPCs, notifications, and actions) */
1163 #define LYS_XPSTATE_DEP  0x400       /**< flag marking nodes, whose validation (when, must expressions)
1164                                           depends on state data nodes outside their subtree (applicable only to RPCs,
1165                                           notifications, and actions) */
1166 #define LYS_LEAFREF_DEP  0x800       /**< flag marking nodes, whose validation (leafrefs)
1167                                           depends on nodes outside their subtree (applicable to RPCs,
1168                                           notifications, actions) or outside their module (applicate to data) */
1169 #define LYS_DFLTJSON     0x1000       /**< default value (in ::lys_node_leaf, ::lys_node_leaflist, :lys_tpdf) was
1170                                           converted into JSON format, since it contains identityref value which is
1171                                           being used in JSON format (instead of module prefixes, we use the module
1172                                           names) */
1173 #define LYS_NOTAPPLIED   0x01        /**< flag for the not applied augments to allow keeping the resolved target */
1174 #define LYS_YINELEM      0x01        /**< yin-element true for extension's argument */
1175 #define LYS_VALID_EXT    0x2000      /**< flag marking nodes that need to be validated using an extension validation function */
1176 #define LYS_VALID_EXT_SUBTREE 0x4000 /**< flag marking nodes that need to be validated using an extension
1177                                           validation function when one of their children nodes is modified */
1178 
1179 /**
1180  * @}
1181  */
1182 
1183 #ifdef LY_ENABLED_CACHE
1184 
1185 /**
1186  * @brief Maximum number of hashes stored in a schema node if cache is enabled.
1187  */
1188 #define LYS_NODE_HASH_COUNT 4
1189 
1190 #endif
1191 
1192 /**
1193  * @brief Common structure representing single YANG data statement describing.
1194  *
1195  * This is a common structure to allow having a homogeneous tree of nodes despite the nodes are actually
1196  * heterogeneous. It allow one to go through the tree in a simple way. However, if you want to work with
1197  * the node in some way or get more appropriate information, you are supposed to cast it to the appropriate
1198  * lys_node_* structure according to the #nodetype value.
1199  *
1200  * To traverse through all the child elements, use #LY_TREE_FOR or #LY_TREE_FOR_SAFE macro. To traverse
1201  * the whole subtree, use #LY_TREE_DFS_BEGIN macro.
1202  *
1203  * To cover all possible schema nodes, the ::lys_node type is used in ::lyd_node#schema for referencing schema
1204  * definition for a specific data node instance.
1205  *
1206  * The #priv member is completely out of libyang control. It is just a pointer to allow libyang
1207  * caller to store some proprietary data (e.g. callbacks) connected with the specific schema tree node.
1208  */
1209 struct lys_node {
1210     const char *name;                /**< node name (mandatory) */
1211     const char *dsc;                 /**< description statement (optional) */
1212     const char *ref;                 /**< reference statement (optional) */
1213     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1214     uint8_t ext_size;                /**< number of elements in #ext array */
1215     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1216 
1217     uint8_t padding[4];              /**< 32b padding - on 64b it just fills the already required data making the
1218                                           space for type-specific values used by the structures derived from lys_node,
1219                                           on 32b it adds one word to lys_node, but this space is anyway required by
1220                                           the (really used) derived structures, so there is no wasting (except
1221                                           ::lys_node_choice, ::lys_node_case and ::lys_node_augment) */
1222 
1223     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1224     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1225     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1226 
1227     LYS_NODE nodetype;               /**< type of the node (mandatory) */
1228     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1229     struct lys_node *child;          /**< pointer to the first child node \note Since other lys_node_*
1230                                           structures represent end nodes, this member
1231                                           is replaced in those structures. Therefore, be careful with accessing
1232                                           this member without having information about the ::lys_node#nodetype. */
1233     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1234     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1235                                           never NULL. If there is no sibling node, pointer points to the node
1236                                           itself. In case of the first node, this pointer points to the last
1237                                           node in the list. */
1238 
1239     void *priv;                      /**< private caller's data, not used by libyang */
1240 
1241 #ifdef LY_ENABLED_CACHE
1242     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1243 #endif
1244 };
1245 
1246 /**
1247  * @brief Schema container node structure.
1248  *
1249  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when,
1250  * #must, #tpdf, and #presence members.
1251  *
1252  * The container schema node can be instantiated in the data tree, so the ::lys_node_container can be directly
1253  * referenced from ::lyd_node#schema.
1254  */
1255 struct lys_node_container {
1256     const char *name;                /**< node name (mandatory) */
1257     const char *dsc;                 /**< description statement (optional) */
1258     const char *ref;                 /**< reference statement (optional) */
1259     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1260     uint8_t ext_size;                /**< number of elements in #ext array */
1261     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1262 
1263     /* non compatible 32b with ::lys_node */
1264     uint8_t padding[1];              /**< padding for 32b alignment */
1265     uint8_t must_size;               /**< number of elements in the #must array */
1266     uint16_t tpdf_size;              /**< number of elements in the #tpdf array */
1267 
1268     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1269     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1270     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1271 
1272     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_CONTAINER */
1273     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1274     struct lys_node *child;          /**< pointer to the first child node */
1275     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1276     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1277                                           never NULL. If there is no sibling node, pointer points to the node
1278                                           itself. In case of the first node, this pointer points to the last
1279                                           node in the list. */
1280 
1281     void *priv;                      /**< private caller's data, not used by libyang */
1282 
1283 #ifdef LY_ENABLED_CACHE
1284     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1285 #endif
1286 
1287     /* specific container's data */
1288     struct lys_when *when;           /**< when statement (optional) */
1289     struct lys_restr *must;          /**< array of must constraints */
1290     struct lys_tpdf *tpdf;           /**< array of typedefs */
1291     const char *presence;            /**< presence description, used also as a presence flag (optional) */
1292 };
1293 
1294 /**
1295  * @brief Schema choice node structure.
1296  *
1297  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when and
1298  * #dflt members.
1299  *
1300  * The choice schema node has no instance in the data tree, so the ::lys_node_choice cannot be directly referenced from
1301  * ::lyd_node#schema.
1302  */
1303 struct lys_node_choice {
1304     const char *name;                /**< node name (mandatory) */
1305     const char *dsc;                 /**< description statement (optional) */
1306     const char *ref;                 /**< reference statement (optional) */
1307     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1308     uint8_t ext_size;                /**< number of elements in #ext array */
1309     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1310 
1311     /* non compatible 32b with ::lys_node */
1312     uint8_t padding[4];              /**< padding for 32b alignment */
1313 
1314     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1315     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1316     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1317 
1318     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_CHOICE */
1319     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1320     struct lys_node *child;          /**< pointer to the first child node */
1321     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1322     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1323                                           never NULL. If there is no sibling node, pointer points to the node
1324                                           itself. In case of the first node, this pointer points to the last
1325                                           node in the list. */
1326 
1327     void *priv;                      /**< private caller's data, not used by libyang */
1328 
1329     /* specific choice's data */
1330     struct lys_when *when;           /**< when statement (optional) */
1331     struct lys_node *dflt;           /**< default case of the choice (optional) */
1332 };
1333 
1334 /**
1335  * @brief Schema leaf node structure.
1336  *
1337  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when, #type,
1338  * #units, #must_size, #must and #dflt members. In addition, the structure is compatible with the ::lys_node_leaflist
1339  * structure except the last #dflt member, which is replaced by ::lys_node_leaflist#min and ::lys_node_leaflist#max
1340  * members.
1341  *
1342  * The leaf schema node can be instantiated in the data tree, so the ::lys_node_leaf can be directly referenced from
1343  * ::lyd_node#schema.
1344  */
1345 struct lys_node_leaf {
1346     const char *name;                /**< node name (mandatory) */
1347     const char *dsc;                 /**< description statement (optional) */
1348     const char *ref;                 /**< reference statement (optional) */
1349     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1350     uint8_t ext_size;                /**< number of elements in #ext array */
1351     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1352 
1353     /* non compatible 32b with ::lys_node */
1354     uint8_t padding[3];              /**< padding for 32b alignment */
1355     uint8_t must_size;               /**< number of elements in the #must array */
1356 
1357     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1358     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1359     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1360 
1361     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_LEAF */
1362     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1363     void *child;                     /**< dummy attribute as a replacement for ::lys_node's child member */
1364     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1365     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1366                                           never NULL. If there is no sibling node, pointer points to the node
1367                                           itself. In case of the first node, this pointer points to the last
1368                                           node in the list. */
1369 
1370     void *priv;                      /**< private caller's data, not used by libyang */
1371 
1372 #ifdef LY_ENABLED_CACHE
1373     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1374 #endif
1375 
1376     /* specific leaf's data */
1377     struct lys_when *when;           /**< when statement (optional) */
1378     struct lys_restr *must;          /**< array of must constraints */
1379     struct lys_type type;            /**< YANG data type definition of the leaf (mandatory) */
1380     const char *units;               /**< units of the data type (optional) */
1381 
1382     /* to this point, struct lys_node_leaf is compatible with struct lys_node_leaflist */
1383     const char *dflt;                /**< default value of the leaf */
1384 };
1385 
1386 /**
1387  * @brief Schema leaf-list node structure.
1388  *
1389  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when, #type,
1390  * #units, #must_size, #must, #min and #max members. In addition, the structure is compatible with the ::lys_node_leaf
1391  * structure except the last #min and #max members, which are replaced by ::lys_node_leaf#dflt member.
1392  *
1393  * The leaf-list schema node can be instantiated in the data tree, so the ::lys_node_leaflist can be directly
1394  * referenced from ::lyd_node#schema.
1395  */
1396 struct lys_node_leaflist {
1397     const char *name;                /**< node name (mandatory) */
1398     const char *dsc;                 /**< description statement (optional) */
1399     const char *ref;                 /**< reference statement (optional) */
1400     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1401     uint8_t ext_size;                /**< number of elements in #ext array */
1402     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1403 
1404     /* non compatible 32b with ::lys_node */
1405     uint8_t padding[2];              /**< padding for 32b alignment */
1406     uint8_t dflt_size;               /**< number of elements in the #dflt array */
1407     uint8_t must_size;               /**< number of elements in the #must array */
1408 
1409     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1410     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1411     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1412 
1413     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_LEAFLIST */
1414     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1415     struct ly_set *backlinks;        /**< replacement for ::lys_node's child member, it is NULL except the leaf/leaflist
1416                                           is target of a leafref. In that case the set stores ::lys_node leafref objects
1417                                           with path referencing the current ::lys_node_leaf */
1418     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1419     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1420                                           never NULL. If there is no sibling node, pointer points to the node
1421                                           itself. In case of the first node, this pointer points to the last
1422                                           node in the list. */
1423 
1424     void *priv;                      /**< private caller's data, not used by libyang */
1425 
1426 #ifdef LY_ENABLED_CACHE
1427     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1428 #endif
1429 
1430     /* specific leaf-list's data */
1431     struct lys_when *when;           /**< when statement (optional) */
1432     struct lys_restr *must;          /**< array of must constraints */
1433     struct lys_type type;            /**< YANG data type definition of the leaf (mandatory) */
1434     const char *units;               /**< units of the data type (optional) */
1435 
1436     /* to this point, struct lys_node_leaflist is compatible with struct lys_node_leaf
1437      * on the other hand, the min and max are compatible with struct lys_node_list */
1438     const char **dflt;               /**< array of default value(s) of the leaflist */
1439     uint32_t min;                    /**< min-elements constraint (optional) */
1440     uint32_t max;                    /**< max-elements constraint, 0 means unbounded (optional) */
1441 };
1442 
1443 /**
1444  * @brief Schema list node structure.
1445  *
1446  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when, #min,
1447  * #max, #must_size, #tpdf_size, #keys_size, #unique_size, #must, #tpdf, #keys and #unique members.
1448  *
1449  * The list schema node can be instantiated in the data tree, so the ::lys_node_list can be directly referenced from
1450  * ::lyd_node#schema.
1451  */
1452 struct lys_node_list {
1453     const char *name;                /**< node name (mandatory) */
1454     const char *dsc;                 /**< description statement (optional) */
1455     const char *ref;                 /**< reference statement (optional) */
1456     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1457     uint8_t ext_size;                /**< number of elements in #ext array */
1458     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1459 
1460     /* non compatible 32b with ::lys_node */
1461     uint8_t must_size;               /**< number of elements in the #must array */
1462     uint8_t tpdf_size;               /**< number of elements in the #tpdf array */
1463     uint8_t keys_size;               /**< number of elements in the #keys array */
1464     uint8_t unique_size;             /**< number of elements in the #unique array (number of unique statements) */
1465 
1466     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1467     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1468     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1469 
1470     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_LIST */
1471     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1472     struct lys_node *child;          /**< pointer to the first child node */
1473     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1474     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1475                                           never NULL. If there is no sibling node, pointer points to the node
1476                                           itself. In case of the first node, this pointer points to the last
1477                                           node in the list. */
1478 
1479     void *priv;                      /**< private caller's data, not used by libyang */
1480 
1481 #ifdef LY_ENABLED_CACHE
1482     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1483 #endif
1484 
1485     /* specific list's data */
1486     struct lys_when *when;           /**< when statement (optional) */
1487     struct lys_restr *must;          /**< array of must constraints */
1488     struct lys_tpdf *tpdf;           /**< array of typedefs */
1489     struct lys_node_leaf **keys;     /**< array of pointers to the key nodes */
1490     struct lys_unique *unique;       /**< array of unique statement structures */
1491 
1492     uint32_t min;                    /**< min-elements constraint */
1493     uint32_t max;                    /**< max-elements constraint, 0 means unbounded */
1494 
1495     const char *keys_str;            /**< string defining the keys, must be stored besides the keys array since the
1496                                           keys may not be present in case the list is inside grouping */
1497 
1498 };
1499 
1500 /**
1501  * @brief Schema anydata (and anyxml) node structure.
1502  *
1503  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when, #must_size
1504  * and #must members.
1505  *
1506  * ::lys_node_anydata is terminating node in the schema tree, so the #child member value is always NULL.
1507  *
1508  * The anydata and anyxml schema nodes can be instantiated in the data tree, so the ::lys_node_anydata can be directly
1509  * referenced from ::lyd_node#schema.
1510  */
1511 struct lys_node_anydata {
1512     const char *name;                /**< node name (mandatory) */
1513     const char *dsc;                 /**< description statement (optional) */
1514     const char *ref;                 /**< reference statement (optional) */
1515     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1516     uint8_t ext_size;                /**< number of elements in #ext array */
1517     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1518 
1519     /* non compatible 32b with ::lys_node */
1520     uint8_t padding[3];              /**< padding for 32b alignment */
1521     uint8_t must_size;               /**< number of elements in the #must array */
1522 
1523     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1524     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1525     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1526 
1527     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_ANYDATA or #LYS_ANYXML */
1528     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1529     struct lys_node *child;          /**< always NULL */
1530     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1531     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1532                                           never NULL. If there is no sibling node, pointer points to the node
1533                                           itself. In case of the first node, this pointer points to the last
1534                                           node in the list. */
1535 
1536     void *priv;                      /**< private caller's data, not used by libyang */
1537 
1538 #ifdef LY_ENABLED_CACHE
1539     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1540 #endif
1541 
1542     /* specific anyxml's data */
1543     struct lys_when *when;           /**< when statement (optional) */
1544     struct lys_restr *must;          /**< array of must constraints */
1545 };
1546 
1547 /**
1548  * @brief Schema uses node structure.
1549  *
1550  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when, #grp,
1551  * #refine_size, #augment_size, #refine and #augment members.
1552  *
1553  * ::lys_node_uses is terminating node in the schema tree. However, it references data from a specific grouping so the
1554  * #child pointer points to the copy of grouping data applying specified refine and augment statements.
1555  *
1556  * The uses schema node has no instance in the data tree, so the ::lys_node_uses cannot be directly referenced from
1557  * ::lyd_node#schema.
1558  */
1559 struct lys_node_uses {
1560     const char *name;                /**< node name (mandatory) */
1561     const char *dsc;                 /**< description statement (optional) */
1562     const char *ref;                 /**< reference statement (optional) */
1563     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only LYS_STATUS_* and LYS_USESGRP
1564                                           values are allowed */
1565     uint8_t ext_size;                /**< number of elements in #ext array */
1566     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1567 
1568     /* non compatible 32b with ::lys_node */
1569     uint8_t padding[2];              /**< padding for 32b alignment */
1570     uint8_t refine_size;             /**< number of elements in the #refine array */
1571     uint8_t augment_size;            /**< number of elements in the #augment array */
1572 
1573     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1574     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1575     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1576 
1577     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_USES */
1578     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1579     struct lys_node *child;          /**< pointer to the first child node imported from the referenced grouping */
1580     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1581     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1582                                           never NULL. If there is no sibling node, pointer points to the node
1583                                           itself. In case of the first node, this pointer points to the last
1584                                           node in the list. */
1585 
1586     void *priv;                      /**< private caller's data, not used by libyang */
1587 
1588     /* specific uses's data */
1589     struct lys_when *when;           /**< when statement (optional) */
1590     struct lys_refine *refine;       /**< array of refine changes to the referred grouping */
1591     struct lys_node_augment *augment;/**< array of local augments to the referred grouping */
1592     struct lys_node_grp *grp;        /**< referred grouping definition (mandatory) */
1593 };
1594 
1595 /**
1596  * @brief Schema grouping node structure.
1597  *
1598  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #tpdf_size and
1599  * #tpdf members.
1600  *
1601  * ::lys_node_grp contains data specifications in the schema tree. However, the data does not directly form the schema
1602  * data tree. Instead, they are referenced via uses (::lys_node_uses) statement and copies of the grouping data are
1603  * actually placed into the uses nodes. Therefore, the nodes you can find under the ::lys_node_grp are not referenced
1604  * from ::lyd_node#schema.
1605  */
1606 struct lys_node_grp {
1607     const char *name;                /**< node name (mandatory) */
1608     const char *dsc;                 /**< description statement (optional) */
1609     const char *ref;                 /**< reference statement (optional) */
1610     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only LYS_STATUS_* values are allowed */
1611     uint8_t ext_size;                /**< number of elements in #ext array */
1612     uint8_t padding_iffsize;         /**< padding byte for the ::lys_node's iffeature_size */
1613 
1614     /* non compatible 32b with ::lys_node */
1615     uint16_t unres_count;            /**< internal counter for unresolved uses, should be always 0 when the module is parsed */
1616     uint16_t tpdf_size;              /**< number of elements in #tpdf array */
1617 
1618     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1619     void *padding_iff;               /**< padding pointer for the ::lys_node's iffeature pointer */
1620     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1621 
1622     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_GROUPING */
1623     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1624     struct lys_node *child;          /**< pointer to the first child node */
1625     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1626     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1627                                           never NULL. If there is no sibling node, pointer points to the node
1628                                           itself. In case of the first node, this pointer points to the last
1629                                           node in the list. */
1630 
1631     void *priv;                      /**< private caller's data, not used by libyang */
1632 
1633     /* specific grouping's data */
1634     struct lys_tpdf *tpdf;           /**< array of typedefs */
1635 };
1636 
1637 /**
1638  * @brief Schema case node structure.
1639  *
1640  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #when member.
1641  *
1642  * The case schema node has no instance in the data tree, so the ::lys_node_case cannot be directly referenced from
1643  * ::lyd_node#schema.
1644  */
1645 struct lys_node_case {
1646     const char *name;                /**< node name (mandatory) */
1647     const char *dsc;                 /**< description statement (optional) */
1648     const char *ref;                 /**< reference statement (optional) */
1649     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1650     uint8_t ext_size;                /**< number of elements in #ext array */
1651     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1652 
1653     /* non compatible 32b with ::lys_node */
1654     uint8_t padding[4];              /**< padding for 32b alignment */
1655 
1656     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1657     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1658     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1659 
1660     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_CASE */
1661     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1662     struct lys_node *child;          /**< pointer to the first child node */
1663     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1664     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1665                                           never NULL. If there is no sibling node, pointer points to the node
1666                                           itself. In case of the first node, this pointer points to the last
1667                                           node in the list. */
1668 
1669     void *priv;                      /**< private caller's data, not used by libyang */
1670 
1671     /* specific case's data */
1672     struct lys_when *when;           /**< when statement (optional) */
1673 };
1674 
1675 /**
1676  * @brief RPC input and output node structure.
1677  *
1678  * The structure is compatible with ::lys_node, but the most parts are not usable. Therefore the ::lys_node#name,
1679  * ::lys_node#dsc, ::lys_node#ref and ::lys_node#flags were replaced by empty bytes in fill arrays.
1680  * The reason to keep these useless bytes in the structure is to keep the #nodetype, #parent, #child, #next and #prev
1681  * members accessible when functions are using the object via a generic ::lyd_node structure. But note that the
1682  * ::lys_node#iffeature_size is replaced by the #tpdf_size member and ::lys_node#iffeature is replaced by the #tpdf
1683  * member.
1684  *
1685  * Note, that the inout nodes are always present in ::lys_node_rpc_action node as its input and output children
1686  * nodes. If they are not specified explicitely in the schema, they are implicitly added to serve as possible target
1687  * of augments. These implicit elements can be recognised via #LYS_IMPLICIT bit in flags member of the input/output
1688  * node.
1689  */
1690 struct lys_node_inout {
1691     const char *name;
1692     void *fill1[2];                  /**< padding for compatibility with ::lys_node - dsc and ref */
1693     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only LYS_IMPLICIT is applicable */
1694     uint8_t ext_size;                /**< number of elements in #ext array */
1695     uint8_t padding_iffsize;         /**< padding byte for the ::lys_node's iffeature_size */
1696 
1697     /* non compatible 32b with ::lys_node */
1698     uint8_t padding[1];              /**< padding for 32b alignment */
1699     uint8_t must_size;               /**< number of elements in the #must array */
1700     uint16_t tpdf_size;              /**< number of elements in the #tpdf array */
1701 
1702     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1703     void *padding_iff;               /**< padding pointer for the ::lys_node's iffeature pointer */
1704     struct lys_module *module;       /**< link to the node's data model */
1705 
1706     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_INPUT or #LYS_OUTPUT */
1707     struct lys_node *parent;         /**< pointer to the parent rpc node  */
1708     struct lys_node *child;          /**< pointer to the first child node */
1709     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1710     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1711                                           never NULL. If there is no sibling node, pointer points to the node
1712                                           itself. In case of the first node, this pointer points to the last
1713                                           node in the list. */
1714 
1715     void *priv;                      /**< private caller's data, not used by libyang */
1716 
1717     /* specific inout's data */
1718     struct lys_tpdf *tpdf;           /**< array of typedefs */
1719     struct lys_restr *must;          /**< array of must constraints */
1720 };
1721 
1722 /**
1723  * @brief Schema notification node structure.
1724  *
1725  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #tpdf_size and
1726  * #tpdf members.
1727  */
1728 struct lys_node_notif {
1729     const char *name;                /**< node name (mandatory) */
1730     const char *dsc;                 /**< description statement (optional) */
1731     const char *ref;                 /**< reference statement (optional) */
1732     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1733     uint8_t ext_size;                /**< number of elements in #ext array */
1734     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1735 
1736     /* non compatible 32b with ::lys_node */
1737     uint8_t padding[1];              /**< padding for 32b alignment */
1738     uint8_t must_size;               /**< number of elements in the #must array */
1739     uint16_t tpdf_size;              /**< number of elements in the #tpdf array */
1740 
1741     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1742     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1743     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1744 
1745     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_NOTIF */
1746     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1747     struct lys_node *child;          /**< pointer to the first child node */
1748     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1749     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1750                                           never NULL. If there is no sibling node, pointer points to the node
1751                                           itself. In case of the first node, this pointer points to the last
1752                                           node in the list. */
1753 
1754     void *priv;                      /**< private caller's data, not used by libyang */
1755 
1756 #ifdef LY_ENABLED_CACHE
1757     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1758 #endif
1759 
1760     /* specific rpc's data */
1761     struct lys_tpdf *tpdf;           /**< array of typedefs */
1762     struct lys_restr *must;          /**< array of must constraints */
1763 };
1764 
1765 /**
1766  * @brief Schema rpc/action node structure.
1767  *
1768  * Beginning of the structure is completely compatible with ::lys_node structure extending it by the #tpdf_size and
1769  * #tpdf members.
1770  *
1771  * Note, that the rpc/action node has always input and output children nodes. If they are not specified explicitly in
1772  * the schema, they are implicitly added to server as possible target of augments. These implicit elements can be
1773  * recognized via #LYS_IMPLICIT bit in flags member of the input/output node.
1774  */
1775 struct lys_node_rpc_action {
1776     const char *name;                /**< node name (mandatory) */
1777     const char *dsc;                 /**< description statement (optional) */
1778     const char *ref;                 /**< reference statement (optional) */
1779     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1780     uint8_t ext_size;                /**< number of elements in #ext array */
1781     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1782 
1783     /* non compatible 32b with ::lys_node */
1784     uint8_t padding[2];              /**< padding for 32b alignment */
1785     uint16_t tpdf_size;              /**< number of elements in the #tpdf array */
1786 
1787     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1788     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1789     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1790 
1791     LYS_NODE nodetype;               /**< type of the node (mandatory) - #LYS_RPC or #LYS_ACTION */
1792     struct lys_node *parent;         /**< pointer to the parent node, NULL in case of a top level node */
1793     struct lys_node *child;          /**< pointer to the first child node */
1794     struct lys_node *next;           /**< pointer to the next sibling node (NULL if there is no one) */
1795     struct lys_node *prev;           /**< pointer to the previous sibling node \note Note that this pointer is
1796                                           never NULL. If there is no sibling node, pointer points to the node
1797                                           itself. In case of the first node, this pointer points to the last
1798                                           node in the list. */
1799 
1800     void *priv;                      /**< private caller's data, not used by libyang */
1801 
1802 #ifdef LY_ENABLED_CACHE
1803     uint8_t hash[LYS_NODE_HASH_COUNT]; /**< schema hash required for LYB printer/parser */
1804 #endif
1805 
1806     /* specific rpc's data */
1807     struct lys_tpdf *tpdf;           /**< array of typedefs */
1808 };
1809 
1810 /**
1811  * @brief YANG augment structure (covering both possibilities - uses's substatement as well as (sub)module's substatement).
1812  *
1813  * This structure is partially interchangeable with ::lys_node structure with the following exceptions:
1814  * - ::lys_node#name member is replaced by ::lys_node_augment#target_name member
1815  * - ::lys_node_augment structure is extended by the #when and #target member
1816  *
1817  * ::lys_node_augment is not placed between all other nodes defining data node. However, it must be compatible with
1818  * ::lys_node structure since its children actually keeps the parent pointer to point to the original augment node
1819  * instead of the target node they augments (the target node is accessible via the ::lys_node_augment#target pointer).
1820  * The fact that a schema node comes from augment can be get via testing the #nodetype of its parent - the value in
1821  * ::lys_node_augment is #LYS_AUGMENT.
1822  */
1823 struct lys_node_augment {
1824     const char *target_name;         /**< schema node identifier of the node where the augment content is supposed to be
1825                                           placed (mandatory). */
1826     const char *dsc;                 /**< description statement (optional) */
1827     const char *ref;                 /**< reference statement (optional) */
1828     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) */
1829     uint8_t ext_size;                /**< number of elements in #ext array */
1830     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1831 
1832     /* non compatible 32b with ::lys_node */
1833     uint8_t padding[4];              /**< padding for 32b alignment */
1834 
1835     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1836     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1837     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1838 
1839     LYS_NODE nodetype;               /**< #LYS_AUGMENT */
1840     struct lys_node *parent;         /**< uses node or NULL in case of module's top level augment */
1841     struct lys_node *child;          /**< augmenting data \note The child here points to the data which are also
1842                                           placed as children in the target node. Children are connected within the
1843                                           child list of the target, but their parent member still points to the augment
1844                                           node (this way they can be distinguished from the original target's children).
1845                                           It is necessary to check this carefully. */
1846 
1847     /* replaces #next and #prev members of ::lys_node */
1848     struct lys_when *when;           /**< when statement (optional) */
1849     struct lys_node *target;         /**< pointer to the target node */
1850 
1851     /* again compatible members with ::lys_node */
1852     void *priv;                      /**< private caller's data, not used by libyang */
1853 };
1854 
1855 /**
1856  * @brief Container for list modifications in ::lys_refine_mod.
1857  */
1858 struct lys_refine_mod_list {
1859     uint32_t min;            /**< new min-elements value. Applicable to #LYS_LIST and #LYS_LEAFLIST target nodes */
1860     uint32_t max;            /**< new max-elements value. Applicable to #LYS_LIST and #LYS_LEAFLIST target nodes */
1861 };
1862 
1863 /**
1864  * @brief Union to hold target modification in ::lys_refine.
1865  */
1866 union lys_refine_mod {
1867     const char *presence;        /**< presence description. Applicable to #LYS_CONTAINER target node */
1868     struct lys_refine_mod_list list;  /**< container for list's attributes,
1869                                       applicable to #LYS_LIST and #LYS_LEAFLIST target nodes */
1870 };
1871 
1872 /**
1873  * @brief YANG uses's refine substatement structure, see [RFC 6020 sec. 7.12.2](http://tools.ietf.org/html/rfc6020#section-7.12.2)
1874  */
1875 struct lys_refine {
1876     const char *target_name;         /**< descendant schema node identifier of the target node to be refined (mandatory) */
1877     const char *dsc;                 /**< description statement (optional) */
1878     const char *ref;                 /**< reference statement (optional) */
1879     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only config and mandatory flags apply */
1880     uint8_t ext_size;                /**< number of elements in #ext array */
1881     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
1882 
1883     /* 32b padding for compatibility with ::lys_node */
1884     uint16_t target_type;            /**< limitations (get from specified refinements) for target node type:
1885                                           - 0 = no limitations,
1886                                           - ORed #LYS_NODE values if there are some limitations */
1887     uint8_t must_size;               /**< number of elements in the #must array */
1888     uint8_t dflt_size;               /**< number of elements in the #dflt array */
1889 
1890     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1891     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
1892     struct lys_module *module;       /**< pointer to the node's module (mandatory) */
1893 
1894     struct lys_restr *must;          /**< array of additional must restrictions to be added to the target */
1895     const char **dflt;               /**< array of new default values. Applicable to #LYS_LEAF, #LYS_LEAFLIST and
1896                                           #LYS_CHOICE target nodes, but multiple defaults are valid only in case of
1897                                           #LYS_LEAFLIST.*/
1898 
1899     union lys_refine_mod mod;        /**< mutually exclusive target modifications according to the possible target_type */
1900 };
1901 
1902 
1903 /**
1904  * @brief Possible deviation modifications, see [RFC 6020 sec. 7.18.3.2](http://tools.ietf.org/html/rfc6020#section-7.18.3.2)
1905  */
1906 typedef enum lys_deviate_type {
1907     LY_DEVIATE_NO,                   /**< not-supported */
1908     LY_DEVIATE_ADD,                  /**< add */
1909     LY_DEVIATE_RPL,                  /**< replace */
1910     LY_DEVIATE_DEL                   /**< delete */
1911 } LYS_DEVIATE_TYPE;
1912 
1913 /**
1914  * @brief YANG deviate statement structure, see [RFC 6020 sec. 7.18.3.2](http://tools.ietf.org/html/rfc6020#section-7.18.3.2)
1915  */
1916 struct lys_deviate {
1917     LYS_DEVIATE_TYPE mod;            /**< type of deviation modification */
1918 
1919     uint8_t flags;                   /**< Properties: config, mandatory */
1920     uint8_t dflt_size;               /**< Properties: default - number of elements in the #dflt array */
1921     uint8_t ext_size;                 /**< number of elements in #ext array */
1922 
1923     uint8_t min_set;                 /**< Since min can be 0, this flag says if it is default value or 0 was set */
1924     uint8_t max_set;                 /**< Since max can be 0, this flag says if it is default value or 0 (unbounded) was set */
1925     uint8_t must_size;               /**< Properties: must - number of elements in the #must array */
1926     uint8_t unique_size;             /**< Properties: unique - number of elements in the #unique array */
1927 
1928     uint32_t min;                    /**< Properties: min-elements */
1929     uint32_t max;                    /**< Properties: max-elements */
1930 
1931     struct lys_restr *must;          /**< Properties: must - array of must constraints */
1932     struct lys_unique *unique;       /**< Properties: unique - array of unique statement structures */
1933     struct lys_type *type;           /**< Properties: type - pointer to type in target, type cannot be deleted or added */
1934     const char *units;               /**< Properties: units */
1935     const char **dflt;               /**< Properties: default (both type and choice represented as string value;
1936                                                       for deviating leaf-list we need it as an array */
1937     struct lys_ext_instance **ext;    /**< array of pointers to the extension instances */
1938 };
1939 
1940 /**
1941  * @brief YANG deviation statement structure, see [RFC 6020 sec. 7.18.3](http://tools.ietf.org/html/rfc6020#section-7.18.3)
1942  */
1943 struct lys_deviation {
1944     const char *target_name;          /**< schema node identifier of the node where the deviation is supposed to be
1945                                            applied (mandatory). */
1946     const char *dsc;                  /**< description (optional) */
1947     const char *ref;                  /**< reference (optional) */
1948     struct lys_node *orig_node;       /**< original (non-deviated) node (mandatory) */
1949 
1950     uint8_t deviate_size;             /**< number of elements in the #deviate array */
1951     uint8_t ext_size;                 /**< number of elements in #ext array */
1952     struct lys_deviate *deviate;      /**< deviate information */
1953     struct lys_ext_instance **ext;    /**< array of pointers to the extension instances */
1954 };
1955 
1956 /**
1957  * @brief YANG import structure used to reference other schemas (modules).
1958  */
1959 struct lys_import {
1960     struct lys_module *module;       /**< link to the imported module (mandatory) */
1961     const char *prefix;              /**< prefix for the data from the imported schema (mandatory) */
1962     char rev[LY_REV_SIZE];           /**< revision-date of the imported module (optional) */
1963     uint8_t ext_size;                /**< number of elements in #ext array */
1964     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1965     const char *dsc;                 /**< description (optional) */
1966     const char *ref;                 /**< reference (optional) */
1967 };
1968 
1969 /**
1970  * @brief YANG include structure used to reference submodules.
1971  */
1972 struct lys_include {
1973     struct lys_submodule *submodule; /**< link to the included submodule (mandatory) */
1974     char rev[LY_REV_SIZE];           /**< revision-date of the included submodule (optional) */
1975     uint8_t ext_size;                /**< number of elements in #ext array */
1976     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1977     const char *dsc;                 /**< description (optional) */
1978     const char *ref;                 /**< reference (optional) */
1979 };
1980 
1981 /**
1982  * @brief YANG revision statement for (sub)modules
1983  */
1984 struct lys_revision {
1985     char date[LY_REV_SIZE];          /**< revision-date (mandatory) */
1986     uint8_t ext_size;                /**< number of elements in #ext array */
1987     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
1988     const char *dsc;                 /**< revision's dsc (optional) */
1989     const char *ref;                 /**< revision's reference (optional) */
1990 };
1991 
1992 /**
1993  * @brief YANG typedef structure providing information from the schema
1994  */
1995 struct lys_tpdf {
1996     const char *name;                /**< name of the newly defined type (mandatory) */
1997     const char *dsc;                 /**< description statement (optional) */
1998     const char *ref;                 /**< reference statement (optional) */
1999     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only LYS_STATUS_ and LYS_DFLTJSON values (or 0) are allowed */
2000     uint8_t ext_size;                /**< number of elements in #ext array */
2001     uint8_t padding_iffsize;         /**< padding byte for the ::lys_node's iffeature_size */
2002     uint8_t has_union_leafref;       /**< flag to mark typedefs with a leafref inside a union */
2003 
2004     /* 24b padding for compatibility with ::lys_node */
2005     uint8_t padding[3];              /**< padding for 32b alignment */
2006 
2007     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
2008     const char *units;               /**< units of the newly defined type (optional) */
2009     struct lys_module *module;       /**< pointer to the module where the data type is defined (mandatory),
2010                                           NULL in case of built-in typedefs */
2011 
2012     struct lys_type type;            /**< base type from which the typedef is derived (mandatory). In case of a special
2013                                           built-in typedef (from yang_types.c), only the base member is filled */
2014     const char *dflt;                /**< default value of the newly defined type (optional) */
2015 };
2016 
2017 /**
2018  * @brief YANG list's unique statement structure, see [RFC 6020 sec. 7.8.3](http://tools.ietf.org/html/rfc6020#section-7.8.3)
2019  */
2020 struct lys_unique {
2021     const char **expr;               /**< array of unique expressions specifying target leafs to be unique */
2022     uint8_t expr_size;               /**< size of the #expr array */
2023     uint8_t trg_type;                /**< config of the targets: 0 - not specified; 1 - config true; 2 - config false */
2024 };
2025 
2026 /**
2027  * @brief YANG feature definition structure
2028  */
2029 struct lys_feature {
2030     const char *name;                /**< feature name (mandatory) */
2031     const char *dsc;                 /**< description statement (optional) */
2032     const char *ref;                 /**< reference statement (optional) */
2033     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only LYS_STATUS_* values and
2034                                           #LYS_FENABLED value are allowed */
2035     uint8_t ext_size;                /**< number of elements in #ext array */
2036     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
2037 
2038     /* 32b padding for compatibility with ::lys_node */
2039     uint8_t padding[4];              /**< padding for 32b alignment */
2040 
2041     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
2042     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
2043     struct lys_module *module;       /**< link to the features's data model (mandatory) */
2044     struct ly_set *depfeatures;      /**< set of other features depending on this one */
2045 };
2046 
2047 /**
2048  * @brief YANG validity restriction (must, length, etc.) structure providing information from the schema
2049  */
2050 struct lys_restr {
2051     const char *expr;                /**< The restriction expression/value (mandatory);
2052                                           in case of pattern restriction, the first byte has a special meaning:
2053                                           0x06 (ACK) for regular match and 0x15 (NACK) for invert-match */
2054     const char *dsc;                 /**< description (optional) */
2055     const char *ref;                 /**< reference (optional) */
2056     const char *eapptag;             /**< error-app-tag value (optional) */
2057     const char *emsg;                /**< error-message (optional) */
2058     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
2059     uint8_t ext_size;                /**< number of elements in #ext array */
2060     uint16_t flags;                  /**< only flags #LYS_XPCONF_DEP and #LYS_XPSTATE_DEP can be specified */
2061 };
2062 
2063 /**
2064  * @brief YANG when restriction, see [RFC 6020 sec. 7.19.5](http://tools.ietf.org/html/rfc6020#section-7.19.5)
2065  */
2066 struct lys_when {
2067     const char *cond;                /**< specified condition (mandatory) */
2068     const char *dsc;                 /**< description (optional) */
2069     const char *ref;                 /**< reference (optional) */
2070     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
2071     uint8_t ext_size;                /**< number of elements in #ext array */
2072     uint16_t flags;                  /**< only flags #LYS_XPCONF_DEP and #LYS_XPSTATE_DEP can be specified */
2073 };
2074 
2075 /**
2076  * @brief Structure to hold information about identity, see  [RFC 6020 sec. 7.16](http://tools.ietf.org/html/rfc6020#section-7.16)
2077  *
2078  * First 5 members maps to ::lys_node.
2079  */
2080 struct lys_ident {
2081     const char *name;                /**< identity name (mandatory) */
2082     const char *dsc;                 /**< description statement (optional) */
2083     const char *ref;                 /**< reference statement (optional) */
2084     uint16_t flags;                  /**< [schema node flags](@ref snodeflags) - only LYS_STATUS_ values are allowed */
2085     uint8_t ext_size;                /**< number of elements in #ext array */
2086     uint8_t iffeature_size;          /**< number of elements in the #iffeature array */
2087 
2088     /* 32b padding for compatibility with ::lys_node */
2089     uint8_t padding[3];              /**< padding for 32b alignment */
2090     uint8_t base_size;               /**< number of elements in the #base array */
2091 
2092     struct lys_ext_instance **ext;   /**< array of pointers to the extension instances */
2093     struct lys_iffeature *iffeature; /**< array of if-feature expressions */
2094     struct lys_module *module;       /**< pointer to the module where the identity is defined */
2095 
2096     struct lys_ident **base;         /**< array of pointers to the base identities */
2097     struct ly_set *der;              /**< set of backlinks to the derived identities */
2098 };
2099 
2100 /**
2101  * @brief Load a schema into the specified context.
2102  *
2103  * @param[in] ctx libyang context where to process the data model.
2104  * @param[in] data The string containing the dumped data model in the specified
2105  * format.
2106  * @param[in] format Format of the input data (YANG or YIN).
2107  * @return Pointer to the data model structure or NULL on error.
2108  */
2109 const struct lys_module *lys_parse_mem(struct ly_ctx *ctx, const char *data, LYS_INFORMAT format);
2110 
2111 /**
2112  * @brief Read a schema from file descriptor into the specified context.
2113  *
2114  * \note Current implementation supports only reading data from standard (disk) file, not from sockets, pipes, etc.
2115  *
2116  * @param[in] ctx libyang context where to process the data model.
2117  * @param[in] fd File descriptor of a regular file (e.g. sockets are not supported) containing the schema
2118  *            in the specified format.
2119  * @param[in] format Format of the input data (YANG or YIN).
2120  * @return Pointer to the data model structure or NULL on error.
2121  */
2122 const struct lys_module *lys_parse_fd(struct ly_ctx *ctx, int fd, LYS_INFORMAT format);
2123 
2124 /**
2125  * @brief Load a schema into the specified context from a file.
2126  *
2127  * @param[in] ctx libyang context where to process the data model.
2128  * @param[in] path Path to the file with the model in the specified format.
2129  * @param[in] format Format of the input data (YANG or YIN).
2130  * @return Pointer to the data model structure or NULL on error.
2131  */
2132 const struct lys_module *lys_parse_path(struct ly_ctx *ctx, const char *path, LYS_INFORMAT format);
2133 
2134 /**
2135  * @brief Search for the schema file in the specified searchpaths.
2136  *
2137  * @param[in] searchpaths NULL-terminated array of paths to be searched (recursively). Current working
2138  * directory is searched automatically (but non-recursively if not in the provided list). Caller can use
2139  * result of the ly_ctx_get_searchdirs().
2140  * @param[in] cwd Flag to implicitly search also in the current working directory (non-recursively).
2141  * @param[in] name Name of the schema to find.
2142  * @param[in] revision Revision of the schema to find. If NULL, the newest found schema filepath is returned.
2143  * @param[out] localfile Mandatory output variable containing absolute path of the found schema. If no schema
2144  * complying the provided restriction is found, NULL is set.
2145  * @param[out] format Optional output variable containing expected format of the schema document according to the
2146  * file suffix.
2147  * @return EXIT_FAILURE on error, EXIT_SUCCESS otherwise (even if the file is not found, then the *localfile is NULL).
2148  */
2149 int lys_search_localfile(const char * const *searchpaths, int cwd, const char *name, const char *revision, char **localfile, LYS_INFORMAT *format);
2150 
2151 /**
2152  * @brief Get list of all the defined features in the module and its submodules.
2153  *
2154  * @param[in] module Module to explore.
2155  * @param[out] states Optional output parameter providing states of all features
2156  * returned by function in the resulting array. Indexes in both arrays corresponds
2157  * each other. Similarly to lys_feature_state(), possible values in the state array
2158  * are 1 (enabled) and 0 (disabled). Caller is supposed to free the array when it
2159  * is no more needed.
2160  * @return NULL-terminated array of all the defined features. The returned array
2161  * must be freed by the caller, do not free names in the array. Also remember
2162  * that the names will be freed with freeing the context of the module.
2163  */
2164 const char **lys_features_list(const struct lys_module *module, uint8_t **states);
2165 
2166 /**
2167  * @brief Enable specified feature in the module. In case its if-feature evaluates
2168  * to false, return an error.
2169  *
2170  * By default, when the module is loaded by libyang parser, all features are disabled.
2171  *
2172  * @param[in] module Module where the feature will be enabled.
2173  * @param[in] feature Name of the feature to enable. To enable all features at once, use asterisk character.
2174  * @return 0 on success, 1 when the feature is not defined in the specified module
2175  */
2176 int lys_features_enable(const struct lys_module *module, const char *feature);
2177 
2178 /**
2179  * @brief Disable specified feature in the module. If it causes some dependant features
2180  * to be disabled, they are also set to disabled.
2181  *
2182  * By default, when the module is loaded by libyang parser, all features are disabled.
2183  *
2184  * @param[in] module Module where the feature will be disabled.
2185  * @param[in] feature Name of the feature to disable. To disable all features at once, use asterisk character.
2186  * @return 0 on success, 1 when the feature is not defined in the specified module
2187  */
2188 int lys_features_disable(const struct lys_module *module, const char *feature);
2189 
2190 /**
2191  * @brief Enable specified feature in the module disregarding its if-features.
2192  *
2193  * @param[in] module Module where the feature will be enabled.
2194  * @param[in] feature Name of the feature to enable. To enable all features at once, use asterisk character.
2195  * @return 0 on success, 1 when the feature is not defined in the specified module
2196  */
2197 int lys_features_enable_force(const struct lys_module *module, const char *feature);
2198 
2199 /**
2200  * @brief Disable specified feature in the module disregarding dependant features.
2201  *
2202  * By default, when the module is loaded by libyang parser, all features are disabled.
2203  *
2204  * @param[in] module Module where the feature will be disabled.
2205  * @param[in] feature Name of the feature to disable. To disable all features at once, use asterisk character.
2206  * @return 0 on success, 1 when the feature is not defined in the specified module
2207  */
2208 int lys_features_disable_force(const struct lys_module *module, const char *feature);
2209 
2210 /**
2211  * @brief Get the current status of the specified feature in the module. Even if the
2212  * feature is enabled but some of its if-features evaluate to false, it is reported
2213  * as disabled.
2214  *
2215  * @param[in] module Module where the feature is defined.
2216  * @param[in] feature Name of the feature to inspect.
2217  * @return
2218  * - 1 if feature is enabled,
2219  * - 0 if feature is disabled,
2220  * - -1 in case of error (e.g. feature is not defined)
2221  */
2222 int lys_features_state(const struct lys_module *module, const char *feature);
2223 
2224 /**
2225  * @brief Check if the schema node is disabled in the schema tree, i.e. there is any disabled if-feature statement
2226  * affecting the node.
2227  *
2228  * @param[in] node Schema node to check.
2229  * @param[in] recursive - 0 to check if-feature only in the \p node schema node,
2230  * - 1 to check if-feature in all ascendant schema nodes
2231  * - 2 to check if-feature in all ascendant schema nodes until there is a node possibly having an instance in a data tree
2232  * @return - NULL if enabled,
2233  * - pointer to the node with the unsatisfied (disabling) if-feature expression.
2234  */
2235 const struct lys_node *lys_is_disabled(const struct lys_node *node, int recursive);
2236 
2237 /**
2238  * @brief Learn how the if-feature statement currently evaluates.
2239  *
2240  * @param[in] iff if-feature statement to evaluate.
2241  * @return If the statement evaluates to true, 1 is returned. 0 is returned when the statement evaluates to false.
2242  */
2243 int lys_iffeature_value(const struct lys_iffeature *iff);
2244 
2245 /**
2246  * @brief Check if the schema leaf node is used as a key for a list.
2247  *
2248  * @param[in] node Schema leaf node to check
2249  * @param[out] index Optional parameter to return position in the list's keys array.
2250  * @return NULL if the \p node is not a key, pointer to the list if the \p node is the key of this list
2251  */
2252 const struct lys_node_list *lys_is_key(const struct lys_node_leaf *node, uint8_t *index);
2253 
2254 /**
2255  * @brief Get next schema tree (sibling) node element that can be instantiated in a data tree. Returned node can
2256  * be from an augment.
2257  *
2258  * lys_getnext() is supposed to be called sequentially. In the first call, the \p last parameter is usually NULL
2259  * and function starts returning i) the first \p parent child or ii) the first top level element of the \p module.
2260  * Consequent calls suppose to provide the previously returned node as the \p last parameter and still the same
2261  * \p parent and \p module parameters.
2262  *
2263  * Without options, the function is used to traverse only the schema nodes that can be paired with corresponding
2264  * data nodes in a data tree. By setting some \p options the behaviour can be modified to the extent that
2265  * all the schema nodes are iteratively returned.
2266  *
2267  * @param[in] last Previously returned schema tree node, or NULL in case of the first call.
2268  * @param[in] parent Parent of the subtree where the function starts processing (__cannot be__ #LYS_USES, use its parent).
2269  * If it is #LYS_AUGMENT, only the children of that augment are returned.
2270  * @param[in] module In case of iterating on top level elements, the \p parent is NULL and
2271  * module must be specified (cannot be submodule).
2272  * @param[in] options ORed options LYS_GETNEXT_*.
2273  * @return Next schema tree node that can be instanciated in a data tree, NULL in case there is no such element.
2274  */
2275 const struct lys_node *lys_getnext(const struct lys_node *last, const struct lys_node *parent,
2276                                    const struct lys_module *module, int options);
2277 
2278 #define LYS_GETNEXT_WITHCHOICE   0x01 /**< lys_getnext() option to allow returning #LYS_CHOICE nodes instead of looking into them */
2279 #define LYS_GETNEXT_WITHCASE     0x02 /**< lys_getnext() option to allow returning #LYS_CASE nodes instead of looking into them */
2280 #define LYS_GETNEXT_WITHGROUPING 0x04 /**< lys_getnext() option to allow returning #LYS_GROUPING nodes instead of skipping them */
2281 #define LYS_GETNEXT_WITHINOUT    0x08 /**< lys_getnext() option to allow returning #LYS_INPUT and #LYS_OUTPUT nodes
2282                                            instead of looking into them */
2283 #define LYS_GETNEXT_WITHUSES     0x10 /**< lys_getnext() option to allow returning #LYS_USES nodes instead of looking into them */
2284 #define LYS_GETNEXT_INTOUSES     0x20 /**< lys_getnext() option to allow to go into uses, takes effect only
2285                                            with #LYS_GETNEXT_WITHUSES, otherwise it goes into uses automatically */
2286 #define LYS_GETNEXT_INTONPCONT   0x40 /**< lys_getnext() option to look into non-presence container, instead of returning container itself */
2287 #define LYS_GETNEXT_PARENTUSES   0x80 /**< lys_getnext() option to allow parent to be #LYS_USES, in which case only
2288                                            the direct children are traversed */
2289 #define LYS_GETNEXT_NOSTATECHECK 0x100 /**< lys_getnext() option to skip checking module validity (import-only, disabled) and
2290                                             relevant if-feature conditions state */
2291 
2292 /**
2293  * @brief Get next type of a union.
2294  *
2295  * @param[in] last Last returned type. NULL on first call.
2296  * @param[in] type Union type structure.
2297  * @return Next union type in order, NULL if all were returned or on error.
2298  */
2299 const struct lys_type *lys_getnext_union_type(const struct lys_type *last, const struct lys_type *type);
2300 
2301 /**
2302  * @brief Search for schema nodes matching the provided path.
2303  *
2304  * Learn more about the path format at page @ref howtoxpath.
2305  * Either \p cur_module or \p cur_node must be set.
2306  *
2307  * @param[in] cur_module Current module name.
2308  * @param[in] cur_node Current (context) schema node.
2309  * @param[in] path Schema path expression filtering the matching nodes.
2310  * @return Set of found schema nodes. In case of an error, NULL is returned.
2311  */
2312 struct ly_set *lys_find_path(const struct lys_module *cur_module, const struct lys_node *cur_node, const char *path);
2313 
2314 /**
2315  * @brief Types of context nodes, #LYXP_NODE_ROOT_CONFIG used only in when or must conditions.
2316  */
2317 enum lyxp_node_type {
2318     /* XML document roots */
2319     LYXP_NODE_ROOT,             /* access to all the data (node value first top-level node) */
2320     LYXP_NODE_ROOT_CONFIG,      /* <running> data context, no state data (node value first top-level node) */
2321 
2322     /* XML elements */
2323     LYXP_NODE_ELEM,             /* XML element (most common) */
2324     LYXP_NODE_TEXT,             /* XML text element (extremely specific use, unlikely to be ever needed) */
2325     LYXP_NODE_ATTR,             /* XML attribute (in YANG cannot happen, do not use for the context node) */
2326 
2327     LYXP_NODE_NONE              /* invalid node type, do not use */
2328 };
2329 
2330 /**
2331  * @brief Get all the partial XPath nodes (atoms) that are required for \p expr to be evaluated.
2332  *
2333  * @param[in] ctx_node Context (current) schema node. Fake roots are distinguished using \p ctx_node_type
2334  * and then this node can be any node from the module (so, for example, do not put node added by an augment from another module).
2335  * @param[in] ctx_node_type Context (current) schema node type. Most commonly is #LYXP_NODE_ELEM, but if
2336  * your context node is supposed to be the root, you can specify what kind of root it is.
2337  * @param[in] expr XPath expression to be evaluated. Must be in JSON data format (prefixes are model names). Otherwise
2338  * follows full __must__ or __when__ YANG expression syntax (see schema path @ref howtoxpath, but is not limited to that).
2339  * @param[in] options Whether to apply some evaluation restrictions #LYXP_MUST or #LYXP_WHEN.
2340  *
2341  * @return Set of atoms (schema nodes), NULL on error.
2342  */
2343 struct ly_set *lys_xpath_atomize(const struct lys_node *ctx_node, enum lyxp_node_type ctx_node_type,
2344                                  const char *expr, int options);
2345 
2346 #define LYXP_MUST 0x01 /**< lys_xpath_atomize() option to apply must statement data tree access restrictions */
2347 #define LYXP_WHEN 0x02 /**< lys_xpath_atomize() option to apply when statement data tree access restrictions */
2348 
2349 /**
2350  * @brief Call lys_xpath_atomize() on all the when and must expressions of the node. This node must be
2351  * a descendant of an input, output, or notification node. This subtree then forms the local subtree.
2352  *
2353  * @param[in] node Node to examine.
2354  * @param[in] options Bitmask of #LYXP_RECURSIVE and #LYXP_NO_LOCAL.
2355  */
2356 struct ly_set *lys_node_xpath_atomize(const struct lys_node *node, int options);
2357 
2358 #define LYXP_RECURSIVE 0x01 /**< lys_node_xpath_atomize() option to return schema node dependencies of all the expressions in the subtree */
2359 #define LYXP_NO_LOCAL 0x02  /**< lys_node_xpath_atomize() option to discard schema node dependencies from the local subtree */
2360 
2361 /**
2362  * @brief Build schema path (usable as path, see @ref howtoxpath) of the schema node.
2363  *
2364  * The path includes prefixes of all the nodes and is hence unequivocal in any context.
2365  * Options can be specified to use a different format of the path.
2366  *
2367  * @param[in] node Schema node to be processed.
2368  * @param[in] options Additional path modification options (#LYS_PATH_FIRST_PREFIX).
2369  * @return NULL on error, on success the buffer for the resulting path is allocated and caller is supposed to free it
2370  * with free().
2371  */
2372 char *lys_path(const struct lys_node *node, int options);
2373 
2374 #define LYS_PATH_FIRST_PREFIX 0x01 /**< lys_path() option for the path not to include prefixes of all the nodes,
2375  * but only for the first one that will be interpreted as the current module (more at @ref howtoxpath). This path is
2376  * less suitable for further processing but better for displaying as it is shorter. */
2377 
2378 /**
2379  * @brief Build data path (usable as path, see @ref howtoxpath) of the schema node.
2380  * @param[in] node Schema node to be processed.
2381  * @return NULL on error, on success the buffer for the resulting path is allocated and caller is supposed to free it
2382  * with free().
2383  */
2384 char *lys_data_path(const struct lys_node *node);
2385 
2386 /**
2387  * @brief Build the data path pattern of a schema node.
2388  *
2389  * For example, when @p node is a leaf in a list with key1 and key2, in a container and `'%s'` is set as
2390  * @p placeholder, the result would be `/model:container/list[key1='%s'][key2='%s']/leaf`. That can
2391  * be used as `printf(3)` format string, for example.
2392  *
2393  * @param[in] node Schema node to be processed.
2394  * @param[in] placeholder Placeholder to insert in the returned path when
2395  *                        list key values are encountered.
2396  * @return NULL on error, on success the buffer for the resulting path is
2397  *         allocated and caller is supposed to free it with free().
2398  */
2399 char *lys_data_path_pattern(const struct lys_node *node, const char *placeholder);
2400 
2401 /**
2402  * @brief Return parent node in the schema tree.
2403  *
2404  * In case of augmenting node, it returns the target tree node where the augmenting
2405  * node was placed, not the augment definition node. Function just wraps usage of the
2406  * ::lys_node#parent pointer in this special case.
2407  *
2408  * @param[in] node Child node to the returned parent node.
2409  * @return The parent node from the schema tree, NULL in case of top level nodes.
2410  */
2411 struct lys_node *lys_parent(const struct lys_node *node);
2412 
2413 /**
2414  * @brief Return main module of the schema tree node.
2415  *
2416  * In case of regular YANG module, it returns ::lys_node#module pointer,
2417  * but in case of submodule, it returns pointer to the main module.
2418  *
2419  * @param[in] node Schema tree node to be examined
2420  * @return pointer to the main module (schema structure), NULL in case of error.
2421  */
2422 struct lys_module *lys_node_module(const struct lys_node *node);
2423 
2424 /**
2425  * @brief Return main module of the module.
2426  *
2427  * In case of regular YANG module, it returns itself,
2428  * but in case of submodule, it returns pointer to the main module.
2429  *
2430  * @param[in] module Module to be examined
2431  * @return pointer to the main module (schema structure).
2432  */
2433 struct lys_module *lys_main_module(const struct lys_module *module);
2434 
2435 /**
2436  * @brief Find the implemented revision of the given module in the context.
2437  *
2438  * If there is no revision of the module implemented, the given module is returned
2439  * without any change. It is up to the caller to set the module implemented via
2440  * lys_set_implemented() when needed.
2441  *
2442  * Also note that the result can be a disabled module and the caller is supposed to decide
2443  * if it should by enabled via lys_set_enabled(). This is to avoid to try to set another
2444  * revision of the module implemented that would fail due to the disabled, but the implemented
2445  * module.
2446  *
2447  * @param[in] mod Module to be searched.
2448  * @return The implemented revision of the module if any, the given module otherwise.
2449  */
2450 struct lys_module *lys_implemented_module(const struct lys_module *mod);
2451 
2452 /**
2453  * @brief Mark imported module as "implemented".
2454  *
2455  * All the modules explicitly loaded are marked as "implemented", but in case of loading module
2456  * automatically as an import of another module, it is marked as imported and in that case it
2457  * is not allowed to load data of this module. On the other hand, the mandatory data nodes of
2458  * such a module are not required nor the (top-level) default nodes defined in this module are
2459  * created in the data trees.
2460  *
2461  * When a module is marked as "implemented" it is not allowed to set it back to "imported".
2462  *
2463  * Note that it is not possible to mark "implemented" multiple revisions of a same module within
2464  * a single context. In such a case the function fails.
2465  *
2466  * If the module is currently disabled, this function enables the module implicitly.
2467  *
2468  * @param[in] module The module to be set implemented.
2469  * @return EXIT_SUCCESS or EXIT_FAILURE
2470  */
2471 int lys_set_implemented(const struct lys_module *module);
2472 
2473 /**
2474  * @brief Disable module in its context to avoid its further usage (it will be hidden for module getters).
2475  *
2476  * The function also disables all the modules in the context that depends on the provided module to disable.
2477  * If the imported modules are not used by any other module in the context, they are also disabled. The result
2478  * of this function can be reverted by lys_set_enabled() function.
2479  *
2480  * Since the disabled modules are hidden from the common module getters, there is a special
2481  * ly_ctx_get_disabled_module_iter() to go through the disabled modules in the context.
2482  *
2483  * libyang internal modules (those present when the context is created) cannot be disabled. Any module
2484  * loaded into the context is, by default, enabled.
2485  *
2486  * @param[in] module Module to be enabled.
2487  * @return EXIT_SUCCESS or EXIT_FAILURE (in case of invalid parameter).
2488  */
2489 int lys_set_disabled(const struct lys_module *module);
2490 
2491 /**
2492  * @brief Enable previously disabled module.
2493  *
2494  * The function tries to revert previous call of the lys_set_disabled() so it checks other disabled
2495  * modules in the context depending on the specified module and if it is possible, also the other modules
2496  * are going to be enabled. Similarly, all the imported modules that were previously supposed as useless
2497  * are enabled.
2498  *
2499  * libyang internal modules (those present when the context is created) are always enabled. Any other module
2500  * loaded into the context is, by default, enabled.
2501  *
2502  * @param[in] module Module to be enabled.
2503  * @return EXIT_SUCCESS or EXIT_FAILURE (in case of invalid parameter).
2504  */
2505 int lys_set_enabled(const struct lys_module *module);
2506 
2507 /**
2508  * @brief Set a schema private pointer to a user pointer.
2509  *
2510  * @param[in] node Node, whose private field will be assigned.
2511  * @param[in] priv Arbitrary user-specified pointer.
2512  * @return previous private object of the \p node (NULL if this is the first call on the \p node). Note, that
2513  * the caller is in this case responsible (if it is necessary) for freeing the replaced private object. In case
2514  * of invalid (NULL) \p node, NULL is returned and #ly_errno is set to #LY_EINVAL.
2515  */
2516 void *lys_set_private(const struct lys_node *node, void *priv);
2517 
2518 /**
2519  * @brief Print schema tree in the specified format into a memory block.
2520  * It is up to caller to free the returned string by free().
2521  *
2522  * @param[out] strp Pointer to store the resulting dump.
2523  * @param[in] module Schema tree to print.
2524  * @param[in] format Schema output format.
2525  * @param[in] target_node Optional parameter. It specifies which particular node/subtree in the module will be printed.
2526  * Only for #LYS_OUT_INFO and #LYS_OUT_TREE formats. Use fully qualified schema path (@ref howtoxpath).
2527  * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
2528  * @param[in] options Schema output options (see @ref schemaprinterflags).
2529  * @return 0 on success, 1 on failure (#ly_errno is set).
2530  */
2531 int lys_print_mem(char **strp, const struct lys_module *module, LYS_OUTFORMAT format, const char *target_node,
2532                   int line_length, int options);
2533 
2534 /**
2535  * @brief Print schema tree in the specified format into a file descriptor.
2536  *
2537  * @param[in] module Schema tree to print.
2538  * @param[in] fd File descriptor where to print the data.
2539  * @param[in] format Schema output format.
2540  * @param[in] target_node Optional parameter. It specifies which particular node/subtree in the module will be printed.
2541  * Only for #LYS_OUT_INFO and #LYS_OUT_TREE formats. Use fully qualified schema path (@ref howtoxpath).
2542  * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE format.
2543  * @param[in] options Schema output options (see @ref schemaprinterflags).
2544  * @return 0 on success, 1 on failure (#ly_errno is set).
2545  */
2546 int lys_print_fd(int fd, const struct lys_module *module, LYS_OUTFORMAT format, const char *target_node,
2547                  int line_length, int options);
2548 
2549 /**
2550  * @brief Print schema tree in the specified format into a file stream.
2551  *
2552  * @param[in] module Schema tree to print.
2553  * @param[in] f File stream where to print the schema.
2554  * @param[in] format Schema output format.
2555  * @param[in] target_node Optional parameter. It specifies which particular node/subtree in the module will be printed.
2556  * Only for #LYS_OUT_INFO and #LYS_OUT_TREE formats. Use fully qualified schema path (@ref howtoxpath).
2557  * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
2558  * @param[in] options Schema output options (see @ref schemaprinterflags).
2559  * @return 0 on success, 1 on failure (#ly_errno is set).
2560  */
2561 int lys_print_file(FILE *f, const struct lys_module *module, LYS_OUTFORMAT format, const char *target_node,
2562                    int line_length, int options);
2563 
2564 /**
2565  * @brief Print schema tree in the specified format into a file.
2566  *
2567  * @param[in] path File where to print the schema.
2568  * @param[in] module Schema tree to print.
2569  * @param[in] format Schema output format.
2570  * @param[in] target_node Optional parameter. It specifies which particular node/subtree in the module will be printed.
2571  * Only for #LYS_OUT_INFO and #LYS_OUT_TREE formats. Use fully qualified schema path (@ref howtoxpath).
2572  * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
2573  * @param[in] options Schema output options (see @ref schemaprinterflags).
2574  * @return 0 on success, 1 on failure (#ly_errno is set).
2575  */
2576 int lys_print_path(const char *path, const struct lys_module *module, LYS_OUTFORMAT format, const char *target_node,
2577                    int line_length, int options);
2578 
2579 /**
2580  * @brief Print schema tree in the specified format using a provided callback.
2581  *
2582  * @param[in] module Schema tree to print.
2583  * @param[in] writeclb Callback function to write the data (see write(1)).
2584  * @param[in] arg Optional caller-specific argument to be passed to the \p writeclb callback.
2585  * @param[in] format Schema output format.
2586  * @param[in] target_node Optional parameter. It specifies which particular node/subtree in the module will be printed.
2587  * Only for #LYS_OUT_INFO and #LYS_OUT_TREE formats. Use fully qualified schema path (@ref howtoxpath).
2588  * @param[in] line_length Maximum characters to be printed on a line, 0 for unlimited. Only for #LYS_OUT_TREE printer.
2589  * @param[in] options Schema output options (see @ref schemaprinterflags).
2590  * @return 0 on success, 1 on failure (#ly_errno is set).
2591  */
2592 int lys_print_clb(ssize_t (*writeclb)(void *arg, const void *buf, size_t count), void *arg,
2593                   const struct lys_module *module, LYS_OUTFORMAT format, const char *target_node, int line_length, int options);
2594 
2595 /** @} */
2596 
2597 #ifdef __cplusplus
2598 }
2599 #endif
2600 
2601 #endif /* LY_TREE_SCHEMA_H_ */
2602