blob: d0a9cedb46b7b367f858529c8dd44f18843f3c82 [file] [log] [blame]
Radek Krejcie7b95092019-05-15 11:03:07 +02001/**
2 * @file tree.h
3 * @author Radek Krejci <rkrejci@cesnet.cz>
4 * @brief libyang geenric macros and functions to work with YANG schema or data trees.
5 *
6 * Copyright (c) 2019 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_H_
16#define LY_TREE_H_
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/**
Radek Krejci327de162019-06-14 12:52:07 +020023 * @brief Types of the different schema and data paths.
24 */
25typedef enum {
26 LY_PATH_LOG /**< Descriptive path format used in log messages */
27} LY_PATH_TYPE;
28
29/**
Radek Krejcie7b95092019-05-15 11:03:07 +020030 * @brief Macro selector for other LY_ARRAY_* macros, do not use directly!
31 */
32#define LY_ARRAY_SELECT(_1, _2, NAME, ...) NAME
33
34/**
35 * @brief Helper macro to go through sized-arrays with a pointer iterator.
36 *
37 * Use with opening curly bracket (`{`).
38 *
39 * @param[in] ARRAY Array to go through
40 * @param[in] TYPE Type of the records in the ARRAY
41 * @param[out] ITER Iterating pointer to the item being processed in each loop
42 */
43#define LY_ARRAY_FOR_ITER(ARRAY, TYPE, ITER) \
44 for (ITER = ARRAY; \
45 (ARRAY) && ((void*)ITER - (void*)ARRAY)/(sizeof(TYPE)) < (*((uint32_t*)(ARRAY) - 1)); \
46 ITER = (void*)((TYPE*)ITER + 1))
47
48/**
49 * @brief Helper macro to go through sized-arrays with a numeric iterator.
50 *
51 * Use with opening curly bracket (`{`).
52 *
53 * To access an item with the INDEX value, use always LY_ARRAY_INDEX macro!
54 *
55 * @param[in] ARRAY Array to go through
56 * @param[out] INDEX Iterating index of the item being processed in each loop
57 */
58#define LY_ARRAY_FOR_INDEX(ARRAY, INDEX) \
59 for (INDEX = 0; \
60 ARRAY && INDEX < (*((uint32_t*)(ARRAY) - 1)); \
61 ++INDEX)
62
63/**
64 * @defgroup schematree Schema Tree
65 * @{
66 *
67 * Data structures and functions to manipulate and access schema tree.
68 */
69
70/**
71 * @brief Get a number of records in the ARRAY.
72 *
73 * Does not check if array exists!
74 */
75#define LY_ARRAY_SIZE(ARRAY) (*((uint32_t*)(ARRAY) - 1))
76
77/**
78 * @brief Sized-array iterator (for-loop).
79 *
80 * Use with opening curly bracket (`{`).
81 *
82 * There are 2 variants:
83 *
84 * LY_ARRAY_FOR(ARRAY, TYPE, ITER)
85 *
86 * Where ARRAY is a sized-array to go through, TYPE is the type of the items in the ARRAY and ITER is a pointer variable
87 * providing the items of the ARRAY in the loops. This functionality is provided by LY_ARRAY_FOR_ITER macro
88 *
89 * LY_ARRAY_FOR(ARRAY, INDEX)
90 *
91 * The ARRAY is again a sized-array to go through, the INDEX is a variable (unsigned integer) for storing iterating ARRAY's index
92 * to access the items of ARRAY in the loops. This functionality is provided by LY_ARRAY_FOR_INDEX macro.
93 */
94#define LY_ARRAY_FOR(ARRAY, ...) LY_ARRAY_SELECT(__VA_ARGS__, LY_ARRAY_FOR_ITER, LY_ARRAY_FOR_INDEX)(ARRAY, __VA_ARGS__)
95
96/**
97 * @brief Macro to iterate via all sibling elements without affecting the list itself
98 *
99 * Works for all types of nodes despite it is data or schema tree, but all the
100 * parameters must be pointers to the same type.
101 *
102 * Use with opening curly bracket (`{`). All parameters must be of the same type.
103 *
104 * @param START Pointer to the starting element.
105 * @param ELEM Iterator.
106 */
107#define LY_LIST_FOR(START, ELEM) \
108 for ((ELEM) = (START); \
109 (ELEM); \
110 (ELEM) = (ELEM)->next)
111
112/**
113 * @brief Macro to iterate via all sibling elements allowing to modify the list itself (e.g. removing elements)
114 *
115 * Use with opening curly bracket (`{`). All parameters must be of the same type.
116 *
117 * @param START Pointer to the starting element.
118 * @param NEXT Temporary storage to allow removing of the current iterator content.
119 * @param ELEM Iterator.
120 */
121#define LY_LIST_FOR_SAFE(START, NEXT, ELEM) \
122 for ((ELEM) = (START); \
123 (ELEM) ? (NEXT = (ELEM)->next, 1) : 0; \
124 (ELEM) = (NEXT))
125
126/**
127 * @brief YANG built-in types
128 */
129typedef enum
130{
131 LY_TYPE_UNKNOWN = 0, /**< Unknown type */
132 LY_TYPE_BINARY, /**< Any binary data ([RFC 6020 sec 9.8](http://tools.ietf.org/html/rfc6020#section-9.8)) */
133 LY_TYPE_UINT8, /**< 8-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
134 LY_TYPE_UINT16, /**< 16-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
135 LY_TYPE_UINT32, /**< 32-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
136 LY_TYPE_UINT64, /**< 64-bit unsigned integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
137 LY_TYPE_STRING, /**< Human-readable string ([RFC 6020 sec 9.4](http://tools.ietf.org/html/rfc6020#section-9.4)) */
138 LY_TYPE_BITS, /**< A set of bits or flags ([RFC 6020 sec 9.7](http://tools.ietf.org/html/rfc6020#section-9.7)) */
139 LY_TYPE_BOOL, /**< "true" or "false" ([RFC 6020 sec 9.5](http://tools.ietf.org/html/rfc6020#section-9.5)) */
140 LY_TYPE_DEC64, /**< 64-bit signed decimal number ([RFC 6020 sec 9.3](http://tools.ietf.org/html/rfc6020#section-9.3))*/
141 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)) */
142 LY_TYPE_ENUM, /**< Enumerated strings ([RFC 6020 sec 9.6](http://tools.ietf.org/html/rfc6020#section-9.6)) */
143 LY_TYPE_IDENT, /**< A reference to an abstract identity ([RFC 6020 sec 9.10](http://tools.ietf.org/html/rfc6020#section-9.10)) */
144 LY_TYPE_INST, /**< References a data tree node ([RFC 6020 sec 9.13](http://tools.ietf.org/html/rfc6020#section-9.13)) */
145 LY_TYPE_LEAFREF, /**< A reference to a leaf instance ([RFC 6020 sec 9.9](http://tools.ietf.org/html/rfc6020#section-9.9))*/
146 LY_TYPE_UNION, /**< Choice of member types ([RFC 6020 sec 9.12](http://tools.ietf.org/html/rfc6020#section-9.12)) */
147 LY_TYPE_INT8, /**< 8-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
148 LY_TYPE_INT16, /**< 16-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
149 LY_TYPE_INT32, /**< 32-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
150 LY_TYPE_INT64, /**< 64-bit signed integer ([RFC 6020 sec 9.2](http://tools.ietf.org/html/rfc6020#section-9.2)) */
151} LY_DATA_TYPE;
152#define LY_DATA_TYPE_COUNT 20 /**< Number of different types */
153
154/**
155 * @brief Stringified YANG built-in data types
156 */
157extern const char* ly_data_type2str[LY_DATA_TYPE_COUNT];
158
Radek Krejci084289f2019-07-09 17:35:30 +0200159/**
Radek Krejci13a57b62019-07-19 13:04:09 +0200160 * @brief Callback provided by the data/schema parsers to type plugins to resolve (format-specific) mapping between prefixes used
161 * in the value strings to the YANG schemas.
Radek Krejci084289f2019-07-09 17:35:30 +0200162 *
Radek Krejci13a57b62019-07-19 13:04:09 +0200163 * Reverse function to ly_clb_get_prefix.
164 *
165 * XML uses XML namespaces, JSON uses schema names as prefixes, YIN/YANG uses prefixes of the imports.
Radek Krejci084289f2019-07-09 17:35:30 +0200166 *
167 * @param[in] ctx libyang context to find the schema.
168 * @param[in] prefix Prefix found in the value string
169 * @param[in] prefix_len Length of the @p prefix.
170 * @param[in] private Internal data needed by the callback.
171 * @return Pointer to the YANG schema identified by the provided prefix or NULL if no mapping found.
172 */
173typedef const struct lys_module *(*ly_clb_resolve_prefix)(struct ly_ctx *ctx, const char *prefix, size_t prefix_len, void *private);
174
Radek Krejci13a57b62019-07-19 13:04:09 +0200175/**
176 * @brief Callback provided by the data/schema printers to type plugins to resolve (format-specific) mapping between YANG module of a data object
177 * to prefixes used in the value strings.
178 *
179 * Reverse function to ly_clb_resolve_prefix.
180 *
181 * XML uses XML namespaces, JSON uses schema names as prefixes, YIN/YANG uses prefixes of the imports.
182 *
183 * @param[in] mod YANG module of the object.
184 * @param[in] private Internal data needed by the callback.
185 * @return String representing prefix for the object of the given YANG module @p mod.
186 */
187typedef const char *(*ly_clb_get_prefix)(const struct lys_module *mod, void *private);
188
Radek Krejcie7b95092019-05-15 11:03:07 +0200189/** @} */
190
191#ifdef __cplusplus
192}
193#endif
194
195#endif /* LY_TREE_H_ */