The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
dict_ext.h
Go to the documentation of this file.
1#pragma once
2/*
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
16 */
17
18/** Multi-protocol AVP dictionary API
19 *
20 * @file src/lib/util/dict_ext.h
21 *
22 * @copyright 2020 The FreeRADIUS server project
23 * @copyright 2020,2024 Arran Cudbard-Bell <a.cudbardb@freeradius.org>
24 */
25RCSIDH(dict_ext_h, "$Id: acf8c1b6485223a54104b39a460a31f65a589bfe $")
26
27#include <freeradius-devel/util/dict.h>
28#include <freeradius-devel/util/ext.h>
29#include <freeradius-devel/util/hash.h>
30
31#include <limits.h>
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
39
40/** Attribute extension - Holds children for an attribute
41 *
42 * Children are possible for:
43 *
44 * #FR_TYPE_TLV, #FR_TYPE_VENDOR, #FR_TYPE_VSA, #FR_TYPE_STRUCT
45 *
46 * *or* where the parent->parent->type is
47 * #FR_TYPE_STRUCT, and "parent" is a "key"
48 * field. Note that these attributes therefore
49 * cannot have VALUEs, as the child defines their
50 * VALUE. See dict_attr_can_have_children() for details.
51 */
52typedef struct {
53 fr_hash_table_t *child_by_name; //!< Namespace at this level in the hierarchy.
54 fr_dict_attr_t const **children; //!< Children of this attribute.
56
57DIAG_OFF(attributes)
58typedef enum CC_HINT(flag_enum) {
59 FR_DICT_ATTR_REF_NONE = 0x00, //!< No ref set.
60 FR_DICT_ATTR_REF_ALIAS = 0x01, //!< The attribute is an alias for another attribute.
61 ///< Either a straight ALIAS, or a reference into another
62 ///< dictionary.
63 FR_DICT_ATTR_REF_CLONE = 0x02, //!< The attribute is a "copy" of another attribute.
64 FR_DICT_ATTR_REF_ENUM = 0x04, //!< The attribute is an enumeration value.
65 FR_DICT_ATTR_REF_KEY = 0x08, //!< it is a UNION which has a ref to a key, and children.
66 FR_DICT_ATTR_REF_UNRESOLVED = 0x10 //!< This flag is combined with the other states to indicate
67 ///< that the reference is unresolved.
69DIAG_ON(attributes)
70
71#define fr_dict_attr_ref_is_unresolved(_type) ((_type) & FR_DICT_ATTR_REF_UNRESOLVED)
72#define fr_dict_attr_ref_type(_type) ((_type) & ~FR_DICT_ATTR_REF_UNRESOLVED)
73
74/** Attribute extension - Holds a reference to an attribute in another dictionary
75 *
76 */
77typedef struct {
78 fr_dict_attr_ref_type_t type; //!< The state of the reference.
79 union {
80 fr_dict_attr_t const *ref; //!< A resolved pointer to the referenced attribute.
81 char *unresolved; //!< An unresolved reference (will need resolving later).
82 };
84
85/** Attribute extension - Cached vendor pointer
86 *
87 */
88typedef struct {
89 fr_dict_attr_t const *vendor; //!< ancestor which has type #FR_TYPE_VENDOR
91
92/** Attribute extension - Stack of dictionary attributes that describe the path back to the root of the dictionary
93 *
94 */
95typedef struct {
96 bool unused; //!< Zero length arrays are apparently GNU extensions
97 ///< and we're not allowed to have structs with a
98 ///< single variable array as its member.
99 ///< We'll likely want to store something else here
100 ///< at some point, so we just have a dummy field to
101 ///< avoid changing all the code.
102 fr_dict_attr_t const *da_stack[]; //!< Stack of dictionary attributes
104
105/** Attribute extension - Holds enumeration values
106 *
107 */
108typedef struct {
109 size_t max_name_len; //!< maximum length of a name
110 fr_hash_table_t *value_by_name; //!< Lookup an enumeration value by name
111 fr_hash_table_t *name_by_value; //!< Lookup a name by value
113
114/** Attribute extension - Holds a hash table with the names of all children of this attribute
115 *
116 */
117typedef struct {
118 fr_hash_table_t *namespace; //!< Lookup a child by name
120
121/** Enum extension - Sub-struct or union pointer
122 *
123 */
124typedef struct {
125 fr_dict_attr_t const *ref; //!< the child structure referenced by this value of key
127
128/** @name Add extension structures to attributes
129 *
130 * @{
131 */
132
133/* Retrieve an extension structure for a dictionary attribute
134 *
135 * @param[in] da to retrieve structure from.
136 * @param[in] ext to retrieve.
137 * @return
138 * - NULL if the extension wasn't found.
139 * - A pointer to the start of the extension.
140 */
141static inline void *fr_dict_attr_ext(fr_dict_attr_t const *da, fr_dict_attr_ext_t ext)
142{
143 if (!da->ext[ext]) return NULL;
144
145 return fr_ext_ptr(da, da->ext[ext], fr_dict_attr_ext_def.info[ext].has_hdr);
146}
147
148/** Return whether a da has a given extension or not
149 *
150 * @param[in] da to check for extensions.
151 * @param[in] ext to check.
152 * @return
153 * - true if the da has the specified extension.
154 * - false if the da does not have the specified extension
155 */
157{
158 return (da->ext[ext] > 0);
159}
160
161/** Return the cached da stack (if any) associated with an attribute
162 *
163 * @param[in] da to return cached da stack for.
164 * @return
165 * - NULL if no da stack available.
166 * - The cached da stack on success.
167 */
169{
171
173 if (!ext) return NULL;
174
175 return ext->da_stack;
176}
177
178/** Return the reference associated with a group type attribute
179 *
180 * @param[in] da to return the reference for.
181 * @return
182 * - NULL if no reference available.
183 * - A pointer to the attribute being referenced.
184 */
185static inline fr_dict_attr_t const *fr_dict_attr_ref(fr_dict_attr_t const *da)
186{
188
190 if (!ext) return NULL;
191
192 /*
193 * Unresolve refs aren't valid refs...
194 */
195 if (fr_dict_attr_ref_is_unresolved(ext->type)) return NULL;
196
197 /*
198 * Temporary backwards compatibility...
199 */
200 if (ext->type != FR_DICT_ATTR_REF_ALIAS) return NULL;
201
202 return ext->ref;
203}
204
205/** Return the vendor number for an attribute
206 *
207 * @param[in] da The dictionary attribute to find the
208 * vendor for.
209 * @return
210 * - 0 this isn't a vendor specific attribute.
211 * - The vendor PEN.
212 */
214{
216
217 if (da->type == FR_TYPE_VENDOR) return da->attr;
218
220 if (!ext || !ext->vendor) return 0;
221
222 return ext->vendor->attr;
223}
224
225/** Return the vendor da for an attribute
226 *
227 * @param[in] da The dictionary attribute to find the
228 * vendor for.
229 * @return
230 * - 0 this isn't a vendor specific attribute.
231 * - The vendor PEN.
232 */
234{
236
237 if (da->type == FR_TYPE_VENDOR) return da;
238
240 if (!ext) return NULL;
241
242 return ext->vendor;
243}
244
245/** @} */
246
248
249#ifdef __cplusplus
250}
251#endif
#define DIAG_ON(_x)
Definition build.h:460
#define RCSIDH(h, id)
Definition build.h:486
#define DIAG_OFF(_x)
Definition build.h:459
fr_dict_attr_ext_t
Extension identifier.
Definition dict.h:180
@ FR_DICT_ATTR_EXT_DA_STACK
Cached da stack.
Definition dict.h:187
@ FR_DICT_ATTR_EXT_REF
Attribute references another attribute and/or dictionary.
Definition dict.h:183
@ FR_DICT_ATTR_EXT_VENDOR
Cached vendor pointer.
Definition dict.h:186
fr_ext_t const fr_dict_attr_ext_def
Holds additional information about extension structures.
Definition dict_ext.c:217
size_t max_name_len
maximum length of a name
Definition dict_ext.h:109
fr_ext_t const fr_dict_enum_ext_def
Holds additional information about extension structures.
Definition dict_ext.c:283
fr_dict_attr_t const * vendor
ancestor which has type FR_TYPE_VENDOR
Definition dict_ext.h:89
fr_dict_attr_t const * ref
the child structure referenced by this value of key
Definition dict_ext.h:125
fr_dict_attr_ref_type_t type
The state of the reference.
Definition dict_ext.h:78
fr_hash_table_t * name_by_value
Lookup a name by value.
Definition dict_ext.h:111
fr_dict_attr_t const ** children
Children of this attribute.
Definition dict_ext.h:54
static void * fr_dict_attr_ext(fr_dict_attr_t const *da, fr_dict_attr_ext_t ext)
Definition dict_ext.h:141
#define fr_dict_attr_ref_is_unresolved(_type)
Definition dict_ext.h:71
fr_hash_table_t * value_by_name
Lookup an enumeration value by name.
Definition dict_ext.h:110
void fr_dict_attr_ext_debug(fr_dict_attr_t const *da)
Definition dict_ext.c:275
fr_dict_attr_t const * da_stack[]
Stack of dictionary attributes.
Definition dict_ext.h:102
static fr_dict_attr_t const * fr_dict_attr_ref(fr_dict_attr_t const *da)
Return the reference associated with a group type attribute.
Definition dict_ext.h:185
fr_hash_table_t * child_by_name
Namespace at this level in the hierarchy.
Definition dict_ext.h:53
bool unused
Zero length arrays are apparently GNU extensions and we're not allowed to have structs with a single ...
Definition dict_ext.h:96
static bool fr_dict_attr_has_ext(fr_dict_attr_t const *da, fr_dict_attr_ext_t ext)
Return whether a da has a given extension or not.
Definition dict_ext.h:156
static fr_dict_attr_t const ** fr_dict_attr_da_stack(fr_dict_attr_t const *da)
Return the cached da stack (if any) associated with an attribute.
Definition dict_ext.h:168
static fr_dict_attr_t const * fr_dict_vendor_da_by_da(fr_dict_attr_t const *da)
Return the vendor da for an attribute.
Definition dict_ext.h:233
fr_dict_attr_ref_type_t
Definition dict_ext.h:58
@ FR_DICT_ATTR_REF_ENUM
The attribute is an enumeration value.
Definition dict_ext.h:64
@ FR_DICT_ATTR_REF_KEY
it is a UNION which has a ref to a key, and children.
Definition dict_ext.h:65
@ FR_DICT_ATTR_REF_ALIAS
The attribute is an alias for another attribute.
Definition dict_ext.h:60
@ FR_DICT_ATTR_REF_CLONE
The attribute is a "copy" of another attribute.
Definition dict_ext.h:63
@ FR_DICT_ATTR_REF_UNRESOLVED
This flag is combined with the other states to indicate that the reference is unresolved.
Definition dict_ext.h:66
@ FR_DICT_ATTR_REF_NONE
No ref set.
Definition dict_ext.h:59
static uint32_t fr_dict_vendor_num_by_da(fr_dict_attr_t const *da)
Return the vendor number for an attribute.
Definition dict_ext.h:213
Attribute extension - Holds children for an attribute.
Definition dict_ext.h:52
Attribute extension - Stack of dictionary attributes that describe the path back to the root of the d...
Definition dict_ext.h:95
Attribute extension - Holds enumeration values.
Definition dict_ext.h:108
Attribute extension - Holds a hash table with the names of all children of this attribute.
Definition dict_ext.h:117
Attribute extension - Holds a reference to an attribute in another dictionary.
Definition dict_ext.h:77
Attribute extension - Cached vendor pointer.
Definition dict_ext.h:88
Enum extension - Sub-struct or union pointer.
Definition dict_ext.h:124
bool has_hdr
Additional metadata should be allocated before the extension data to record the exact length of the e...
Definition ext.h:113
static void * fr_ext_ptr(TALLOC_CTX const *chunk, size_t offset, bool has_hdr)
Return a pointer to an extension in a chunk.
Definition ext.h:150
fr_ext_info_t const * info
Additional information about each extension.
Definition ext.h:131
Structure to define a set of extensions.
Definition ext.h:126
@ FR_TYPE_VENDOR
Attribute that represents a vendor in the attribute tree.
unsigned int uint32_t