/src/freeradius-server/src/freeradius-devel/util/dict_ext.h

Source
#pragma once
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 */

/** Multi-protocol AVP dictionary API
 *
 * @file src/lib/util/dict_ext.h
 *
 * @copyright 2020 The FreeRADIUS server project
 * @copyright 2020,2024 Arran Cudbard-Bell <a.cudbardb@freeradius.org>
 */
RCSIDH(dict_ext_h, "$Id: d409cbf1a830e224856b508c4a34211e9a5e6aa9 $")

#include <freeradius-devel/util/dict.h>
#include <freeradius-devel/util/ext.h>
#include <freeradius-devel/util/hash.h>

#include <limits.h>

#ifdef __cplusplus
extern "C" {
#endif

extern fr_ext_t const fr_dict_attr_ext_def;
extern fr_ext_t const fr_dict_enum_ext_def;

/** Attribute extension - Holds children for an attribute
 *
 * Children are possible for:
 *
 * #FR_TYPE_TLV, #FR_TYPE_VENDOR, #FR_TYPE_VSA, #FR_TYPE_STRUCT
 *
 * *or* where the parent->parent->type is
 * #FR_TYPE_STRUCT, and "parent" is a "key"
 * field.  Note that these attributes therefore
 * cannot have VALUEs, as the child defines their
 * VALUE.  See dict_attr_can_have_children() for details.
 */
typedef struct {
  fr_dict_attr_t const  **children;     //!< Children of this attribute.
} fr_dict_attr_ext_children_t;

DIAG_OFF(attributes)
typedef enum CC_HINT(flag_enum) {
  FR_DICT_ATTR_REF_NONE   = 0x00,     //!< No ref set.
  FR_DICT_ATTR_REF_ALIAS    = 0x01,     //!< The attribute is an alias for another attribute.
                ///< Either a straight ALIAS, or a pointer from FR_TYPE_GROUP
                ///< into another dictionary.
  FR_DICT_ATTR_REF_CLONE    = 0x02,     //!< The attribute is a "copy" of another attribute.
  FR_DICT_ATTR_REF_ENUM   = 0x04,     //!< The attribute is an enumeration value.
  FR_DICT_ATTR_REF_KEY    = 0x08,     //!< it is a UNION which has a ref to a key, and children.
  FR_DICT_ATTR_REF_ROOT   = 0x10,     //!< only for FR_TYPE_ATTR, point to the default root for enums
  FR_DICT_ATTR_REF_UNRESOLVED = 0x8000          //!< This flag is combined with the other states to indicate
                ///< that the reference is unresolved.
} fr_dict_attr_ref_type_t;
DIAG_ON(attributes)

#define fr_dict_attr_ref_is_unresolved(_type) ((_type) & FR_DICT_ATTR_REF_UNRESOLVED)
#define fr_dict_attr_ref_type(_type)    ((_type) & ~FR_DICT_ATTR_REF_UNRESOLVED)

/** Attribute extension - Holds a reference to an attribute in another dictionary
 *
 */
typedef struct {
  fr_dict_attr_ref_type_t type;       //!< The state of the reference.
  union {
    fr_dict_attr_t const  *ref;     //!< A resolved pointer to the referenced attribute.
    char      *unresolved;    //!< An unresolved reference (will need resolving later).
  };
} fr_dict_attr_ext_ref_t;

/** Attribute extension - Cached vendor pointer
 *
 */
typedef struct {
  fr_dict_attr_t const  *vendor;      //!< ancestor which has type #FR_TYPE_VENDOR
} fr_dict_attr_ext_vendor_t;

/** Attribute extension - Holds enumeration values
 *
 */
typedef struct {
  size_t      max_name_len;     //!< maximum length of a name
  fr_hash_table_t   *value_by_name;     //!< Lookup an enumeration value by name
  fr_hash_table_t   *name_by_value;     //!< Lookup a name by value
} fr_dict_attr_ext_enumv_t;

/** Attribute extension - Holds a hash table with the names of all children of this attribute
 *
 */
typedef struct {
  fr_hash_table_t   *namespace;     //!< Lookup a child by name
} fr_dict_attr_ext_namespace_t;

/** @name Add extension structures to attributes
 *
 * @{
 */

/* Retrieve an extension structure for a dictionary attribute
 *
 * @param[in] da  to retrieve structure from.
 * @param[in] ext to retrieve.
 * @return
 *  - NULL if the extension wasn't found.
 *  - A pointer to the start of the extension.
 */
static inline void *fr_dict_attr_ext(fr_dict_attr_t const *da, fr_dict_attr_ext_t ext)
{
  if (!da->ext[ext]) return NULL;

  return fr_ext_ptr(da, da->ext[ext], fr_dict_attr_ext_def.info[ext].has_hdr);
}

/** Return whether a da has a given extension or not
 *
 * @param[in] da  to check for extensions.
 * @param[in] ext to check.
 * @return
 *      - true if the da has the specified extension.
 *  - false if the da does not have the specified extension
 */
static inline bool fr_dict_attr_has_ext(fr_dict_attr_t const *da, fr_dict_attr_ext_t ext)
{
  return (da->ext[ext] > 0);
}

/** Return the reference associated with a group type attribute
 *
 * @param[in] da  to return the reference for.
 * @return
 *  - NULL if no reference available.
 *  - A pointer to the attribute being referenced.
 */
static inline fr_dict_attr_t const *fr_dict_attr_ref(fr_dict_attr_t const *da)
{
  fr_dict_attr_ext_ref_t *ext;

  ext = fr_dict_attr_ext(da, FR_DICT_ATTR_EXT_REF);
  if (!ext) return NULL;

  /*
   *  Unresolve refs aren't valid refs...
   */
  if (fr_dict_attr_ref_is_unresolved(ext->type)) return NULL;

  /*
   *  Temporary backwards compatibility...
   */
  if (ext->type != FR_DICT_ATTR_REF_ALIAS) return NULL;

  return ext->ref;
}

/** Return the vendor number for an attribute
 *
 * @param[in] da    The dictionary attribute to find the
 *        vendor for.
 * @return
 *  - 0 this isn't a vendor specific attribute.
 *  - The vendor PEN.
 */
static inline uint32_t fr_dict_vendor_num_by_da(fr_dict_attr_t const *da)
{
  fr_dict_attr_ext_vendor_t *ext;

  if (da->type == FR_TYPE_VENDOR) return da->attr;

  ext = fr_dict_attr_ext(da, FR_DICT_ATTR_EXT_VENDOR);
  if (!ext || !ext->vendor) return 0;

  return ext->vendor->attr;
}

/** Return the vendor da for an attribute
 *
 * @param[in] da    The dictionary attribute to find the
 *        vendor for.
 * @return
 *  - 0 this isn't a vendor specific attribute.
 *  - The vendor PEN.
 */
static inline fr_dict_attr_t const *fr_dict_vendor_da_by_da(fr_dict_attr_t const *da)
{
  fr_dict_attr_ext_vendor_t *ext;

  if (da->type == FR_TYPE_VENDOR) return da;

  ext = fr_dict_attr_ext(da, FR_DICT_ATTR_EXT_VENDOR);
  if (!ext) return NULL;

  return ext->vendor;
}

/* Retrieve an extension structure for a dictionary enum
 *
 * @param[in] enumv to retrieve structure from.
 * @param[in] ext to retrieve.
 * @return
 *  - NULL if the extension wasn't found.
 *  - A pointer to the start of the extension.
 */
static inline void *fr_dict_enum_ext(fr_dict_enum_value_t const *enumv, fr_dict_enum_ext_t ext)
{
  if (!enumv->ext[ext]) return NULL;

  return fr_ext_ptr(enumv, enumv->ext[ext], fr_dict_enum_ext_def.info[ext].has_hdr);
}

/** Return the attribute reference associated with an enum
 *
 * @param[in] enumv to return the reference for.
 * @return
 *  - NULL if no reference available.
 *  - A pointer to the attribute being referenced.
 */
static inline fr_dict_attr_t const *fr_dict_enum_attr_ref(fr_dict_enum_value_t const *enumv)
{
  fr_dict_enum_ext_attr_ref_t const *ref;

  ref = fr_dict_enum_ext(enumv, FR_DICT_ENUM_EXT_ATTR_REF);
  if (!ref) return NULL;

  return ref->da;
}


/** @} */

void fr_dict_attr_ext_debug(fr_dict_attr_t const *da);

#ifdef __cplusplus
}
#endif

Coverage Report

Created: 2026-05-11 06:44