forked from CESNET/libyang
/
path.h
253 lines (229 loc) · 10.6 KB
/
path.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
/**
* @file path.h
* @author Michal Vasko <mvasko@cesnet.cz>
* @brief Path structure and manipulation routines.
*
* Copyright (c) 2020 CESNET, z.s.p.o.
*
* This source code is licensed under BSD 3-Clause License (the "License").
* You may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://opensource.org/licenses/BSD-3-Clause
*/
#ifndef LY_PATH_H_
#define LY_PATH_H_
#include <stddef.h>
#include <stdint.h>
#include "log.h"
#include "tree.h"
#include "tree_data.h"
struct ly_ctx;
struct lys_glob_unres;
struct lys_module;
struct lysc_ext_instance;
struct lysc_node;
struct lyxp_expr;
enum ly_path_pred_type {
LY_PATH_PREDTYPE_NONE = 0, /**< no predicate */
LY_PATH_PREDTYPE_POSITION, /**< position predicate - [2] */
LY_PATH_PREDTYPE_LIST, /**< keys predicate - [key1='val1'][key2='val2']... */
LY_PATH_PREDTYPE_LEAFLIST /**< leaflist value predicate - [.='value'] */
};
/**
* @brief Structure for simple path predicate.
*/
struct ly_path_predicate {
union {
uint64_t position; /**< position value for the position-predicate */
struct {
const struct lysc_node *key; /**< key node of the predicate, NULL in
case of a leaf-list predicate */
struct lyd_value value; /**< value representation according to the
key's type, its realtype is allocated */
};
};
};
/**
* @brief Structure for holding one segment of resolved path on schema including
* simple predicates. Is used as a [sized array](@ref sizedarrays).
*/
struct ly_path {
const struct lysc_node *node; /**< Schema node representing the path segment, first node has special meaning:
- is a top-level node - path is absolute,
- is inner node - path is relative */
struct ly_path_predicate *predicates; /**< [Sized array](@ref sizedarrays) of the path segment's predicates */
enum ly_path_pred_type pred_type; /**< Predicate type (see YANG ABNF) */
};
/**
* @defgroup path_begin_options Path begin options.
* @{
*/
#define LY_PATH_BEGIN_ABSOLUTE 0x01 /**< path must be absolute */
#define LY_PATH_BEGIN_EITHER 0x02 /**< path be be iether absolute or relative */
/** @} */
/**
* @defgroup path_lref_options Path leafref options.
* @{
*/
#define LY_PATH_LREF_FALSE 0x04 /**< path does not represent leafref */
#define LY_PATH_LREF_TRUE 0x08 /* '..' in path allowed, special leafref predicates expected (but are not compiled),
implement traversed modules */
/** @} */
/**
* @defgroup path_prefix_options Path prefix options.
* @{
*/
#define LY_PATH_PREFIX_OPTIONAL 0x10 /**< prefixes in the path are optional */
#define LY_PATH_PREFIX_MANDATORY 0x20 /**< prefixes in the path are mandatory (XML instance-identifier) */
#define LY_PATH_PREFIX_STRICT_INHERIT 0x30 /**< prefixes in the path are mandatory in case they differ from the
previous prefixes, otherwise they are prohibited (JSON instance-identifier) */
/** @} */
/**
* @defgroup path_pred_options Path predicate options.
* @{
*/
#define LY_PATH_PRED_KEYS 0x40 /* expected predicate only - [node='value']* */
#define LY_PATH_PRED_SIMPLE 0x80 /* expected predicates - [node='value']*; [.='value']; [1] */
#define LY_PATH_PRED_LEAFREF 0xC0 /* expected predicates only leafref - [node=current()/../../../node/node];
at least 1 ".." and 1 "node" after */
/** @} */
/**
* @brief Parse path into XPath token structure and perform all additional checks.
*
* @param[in] ctx libyang context.
* @param[in] ctx_node Optional context node, used for logging.
* @param[in] str_path Path to parse.
* @param[in] path_len Length of @p str_path.
* @param[in] begin Begin option (@ref path_begin_options).
* @param[in] lref Lref option (@ref path_lref_options).
* @param[in] prefix Prefix option (@ref path_prefix_options).
* @param[in] pred Predicate option (@ref path_pred_options).
* @param[out] expr Parsed path.
* @return LY_ERR value.
*/
LY_ERR ly_path_parse(const struct ly_ctx *ctx, const struct lysc_node *ctx_node, const char *str_path, size_t path_len,
uint8_t begin, uint8_t lref, uint8_t prefix, uint8_t pred, struct lyxp_expr **expr);
/**
* @brief Parse predicate into XPath token structure and perform all additional checks.
*
* @param[in] ctx libyang context.
* @param[in] cur_node Optional current (original context) node, used for logging.
* @param[in] str_path Path to parse.
* @param[in] path_len Length of @p str_path.
* @param[in] prefix Prefix option (@ref path_prefix_options).
* @param[in] pred Predicate option (@ref path_pred_options).
* @param[out] expr Parsed path.
* @return LY_ERR value.
*/
LY_ERR ly_path_parse_predicate(const struct ly_ctx *ctx, const struct lysc_node *cur_node, const char *str_path,
size_t path_len, uint8_t prefix, uint8_t pred, struct lyxp_expr **expr);
/**
* @defgroup path_oper_options Path operation options.
* @{
*/
#define LY_PATH_OPER_INPUT 0x01 /**< if any RPC/action is traversed, its input nodes are used */
#define LY_PATH_OPER_OUTPUT 0x02 /**< if any RPC/action is traversed, its output nodes are used */
/** @} */
/* lref */
/**
* @defgroup path_target_options Path target options.
* @{
*/
#define LY_PATH_TARGET_SINGLE 0x10 /**< last (target) node must identify an exact instance */
#define LY_PATH_TARGET_MANY 0x20 /**< last (target) node may identify all instances (of leaf-list/list) */
/** @} */
/**
* @brief Compile path into ly_path structure. Any predicates of a leafref are only checked, not compiled.
*
* @param[in] ctx libyang context.
* @param[in] cur_mod Current module of the path (where it was "instantiated"). Used for nodes without a prefix
* for ::LY_PREF_SCHEMA* format.
* @param[in] ctx_node Optional context node.
* @param[in] ext Extension instance containing the definition of the data being created. It is used to find the top-level
* node inside the extension instance instead of a module. Note that this is the case not only if the @p ctx_node is NULL,
* but also if the relative path starting in @p ctx_node reaches the document root via double dots.
* @param[in] expr Parsed path.
* @param[in] lref Lref option (@ref path_lref_options).
* @param[in] oper Oper option (@ref path_oper_options).
* @param[in] target Target option (@ref path_target_options).
* @param[in] format Format of the path.
* @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
* @param[in,out] unres Global unres structure for newly implemented modules, needed only if @p lref is ::LY_PATH_LREF_TRUE.
* @param[out] path Compiled path.
* @return LY_ERECOMPILE, only if @p lref is ::LY_PATH_LREF_TRUE.
* @return LY_ERR value.
*/
LY_ERR ly_path_compile(const struct ly_ctx *ctx, const struct lys_module *cur_mod, const struct lysc_node *ctx_node,
const struct lysc_ext_instance *ext, const struct lyxp_expr *expr, uint8_t lref, uint8_t oper, uint8_t target,
LY_VALUE_FORMAT format, void *prefix_data, struct lys_glob_unres *unres, struct ly_path **path);
/**
* @brief Compile predicate into ly_path_predicate structure. Only simple predicates (not leafref) are supported.
*
* @param[in] ctx libyang context.
* @param[in] cur_node Optional current (original context) node.
* @param[in] cur_mod Current module of the path (where it was "instantiated"). Used for nodes without a prefix
* for ::LY_PREF_SCHEMA* format.
* @param[in] ctx_node Context node, node for which the predicate is defined.
* @param[in] expr Parsed path.
* @param[in,out] tok_idx Index in @p expr, is adjusted for parsed tokens.
* @param[in] format Format of the path.
* @param[in] prefix_data Format-specific data for resolving any prefixes (see ::ly_resolve_prefix).
* @param[out] predicates Compiled predicates.
* @param[out] pred_type Type of the compiled predicate(s).
* @return LY_ERR value.
*/
LY_ERR ly_path_compile_predicate(const struct ly_ctx *ctx, const struct lysc_node *cur_node, const struct lys_module *cur_mod,
const struct lysc_node *ctx_node, const struct lyxp_expr *expr, uint16_t *tok_idx, LY_VALUE_FORMAT format,
void *prefix_data, struct ly_path_predicate **predicates, enum ly_path_pred_type *pred_type);
/**
* @brief Resolve at least partially the target defined by ly_path structure. Not supported for leafref!
*
* @param[in] path Path structure specifying the target.
* @param[in] start Starting node for relative paths, can be any for absolute paths.
* @param[out] path_idx Last found path segment index, can be NULL, set to 0 if not found.
* @param[out] match Last found matching node, can be NULL, set to NULL if not found.
* @return LY_ENOTFOUND if no nodes were found,
* @return LY_EINCOMPLETE if some node was found but not the last one,
* @return LY_SUCCESS when the last node in the path was found,
* @return LY_ERR on another error.
*/
LY_ERR ly_path_eval_partial(const struct ly_path *path, const struct lyd_node *start, LY_ARRAY_COUNT_TYPE *path_idx,
struct lyd_node **match);
/**
* @brief Resolve the target defined by ly_path structure. Not supported for leafref!
*
* @param[in] path Path structure specifying the target.
* @param[in] start Starting node for relative paths, can be any for absolute paths.
* @param[out] match Found matching node, can be NULL, set to NULL if not found.
* @return LY_ENOTFOUND if no nodes were found,
* @return LY_SUCCESS when the last node in the path was found,
* @return LY_ERR on another error.
*/
LY_ERR ly_path_eval(const struct ly_path *path, const struct lyd_node *start, struct lyd_node **match);
/**
* @brief Duplicate ly_path structure.
*
* @param[in] ctx libyang context.
* @param[in] path Path to duplicate.
* @param[out] dup Duplicated path.
* @return LY_ERR value.
*/
LY_ERR ly_path_dup(const struct ly_ctx *ctx, const struct ly_path *path, struct ly_path **dup);
/**
* @brief Free ly_path_predicate structure.
*
* @param[in] ctx libyang context.
* @param[in] pred_type Predicate type.
* @param[in] predicates Predicates ([sized array](@ref sizedarrays)) to free.
*/
void ly_path_predicates_free(const struct ly_ctx *ctx, enum ly_path_pred_type pred_type,
struct ly_path_predicate *predicates);
/**
* @brief Free ly_path structure.
*
* @param[in] ctx libyang context.
* @param[in] path The structure ([sized array](@ref sizedarrays)) to free.
*/
void ly_path_free(const struct ly_ctx *ctx, struct ly_path *path);
#endif /* LY_PATH_H_ */