1 // Copyright (C) 2014-2021 Internet Systems Consortium, Inc. ("ISC") 2 // 3 // This Source Code Form is subject to the terms of the Mozilla Public 4 // License, v. 2.0. If a copy of the MPL was not distributed with this 5 // file, You can obtain one at http://mozilla.org/MPL/2.0/. 6 7 #ifndef CFG_OPTION_DEF_H 8 #define CFG_OPTION_DEF_H 9 10 #include <dhcp/option_definition.h> 11 #include <dhcp/option_space_container.h> 12 #include <cc/cfg_to_element.h> 13 #include <string> 14 15 namespace isc { 16 namespace dhcp { 17 18 /// @brief Represents option definitions used by the DHCP server. 19 /// 20 /// This class provides methods to add and retrieve option definitions 21 /// specified by the administrator for the DHCP server. Option definitions 22 /// specify formats of the options. This class doesn't hold information 23 /// about the data being carried by the options. 24 /// 25 /// Option definitions are grouped by option spaces. The option space is 26 /// identified by the unique name which is specified as a string. The 27 /// following names: "dhcp4" and "dhcp6" are reserved, though. They are 28 /// names of option spaces used for standard top-level DHCPv4 and DHCPv6 29 /// options respectively. 30 class CfgOptionDef : public isc::data::CfgToElement { 31 public: 32 33 /// @brief Copies this configuration to a new configuration. 34 /// 35 /// This method copies the option definitions stores in the configuration 36 /// to an object passed as parameter. There are no shared objects or 37 /// pointers between the original object and a copy. 38 /// 39 /// @param [out] new_config An object to which the configuration will be 40 /// copied. 41 void copyTo(CfgOptionDef& new_config) const; 42 43 /// @name Methods and operators used for comparing objects. 44 /// 45 //@{ 46 /// @brief Check if configuration is equal to other configuration. 47 /// 48 /// @param other An object holding configuration to compare to. 49 /// 50 /// @return true if configurations are equal, false otherwise. 51 bool equals(const CfgOptionDef& other) const; 52 53 /// @brief Equality operator. 54 /// 55 /// @param other An object holding configuration to compare to. 56 /// 57 /// @return true if configurations are equal, false otherwise. 58 bool operator==(const CfgOptionDef& other) const { 59 return (equals(other)); 60 } 61 62 /// @brief Inequality operator. 63 /// 64 /// @param other An object holding configuration to compare to. 65 /// 66 /// @return true if configurations are unequal, false otherwise. 67 bool operator!=(const CfgOptionDef& other) const { 68 return (!equals(other)); 69 } 70 71 //@} 72 73 /// @brief Add new option definition. 74 /// 75 /// @param def option definition to be added. 76 /// 77 /// @throw isc::dhcp::DuplicateOptionDefinition when the particular 78 /// option definition already exists. 79 /// @throw isc::dhcp::MalformedOptionDefinition when the pointer to 80 /// an option definition is NULL. 81 /// @throw isc::BadValue when the option space name is empty or 82 /// when trying to override the standard option (in dhcp4 or dhcp6 83 /// option space). 84 void add(const OptionDefinitionPtr& def); 85 86 /// @brief Return option definitions for particular option space. 87 /// 88 /// @param option_space option space. 89 /// 90 /// @return Pointer to the collection of option definitions for 91 /// the particular option space. The option collection is empty 92 /// if no option exists for the option space specified. 93 OptionDefContainerPtr getAll(const std::string& option_space) const; 94 95 /// @brief Return option definition for a particular option space and code. 96 /// 97 /// @param option_space option space. 98 /// @param option_code option code. 99 /// 100 /// @return An option definition or NULL pointer if option definition 101 /// has not been found. 102 OptionDefinitionPtr get(const std::string& option_space, 103 const uint16_t option_code) const; 104 105 /// @brief Return option definition for the particular option space and name. 106 /// 107 /// @param option_space option space. 108 /// @param option_name option name. 109 /// 110 /// @return An option definition or NULL pointer if option definition 111 /// has not been found. 112 OptionDefinitionPtr get(const std::string& option_space, 113 const std::string& option_name) const; 114 115 /// @brief Deletes all option definitions having a given database id. 116 /// 117 /// Note that there are cases when there will be multiple option 118 /// definitions having the same id (typically id of 0). When 119 /// configuration backend is in use it sets the unique ids from the 120 /// database. In cases when the configuration backend is not used, 121 /// the ids default to 0. Passing the id of 0 would result in 122 /// deleting all option definitions that were not added via the 123 /// database. 124 /// 125 /// @param id Identifier of the option definitions to be deleted. 126 /// 127 /// @return Number of deleted option definitions. 128 uint64_t del(const uint64_t id); 129 130 /// @brief Returns reference to container holding option definitions. getContainer()131 const OptionDefSpaceContainer& getContainer() const { 132 return (option_definitions_); 133 } 134 135 /// @brief Unparse a configuration object 136 /// 137 /// @return a pointer to unparsed configuration 138 virtual isc::data::ElementPtr toElement() const; 139 140 /// @brief Unparse a configuration object with optionally including 141 /// the metadata. 142 /// 143 /// @param include_metadata boolean value indicating if the metadata 144 /// should be included (if true) or not (if false). 145 /// 146 /// @return A pointer to the unparsed configuration. 147 isc::data::ElementPtr 148 toElementWithMetadata(const bool include_metadata) const; 149 150 /// @brief Merges specified option definitions from a configuration 151 /// into this configuration. 152 /// 153 /// This method merges the option definitions from the @c other 154 /// configuration into this configuration. The merged set of 155 /// definitions is created as follows: 156 /// 157 /// Iterator over the definitions in each name space in this configuration: 158 /// If either the definition's name or code are defined in @c other 159 /// then skip over the definition otherwise add it to @c other. 160 /// 161 /// Replace this configuration's definitions with the definitions 162 /// in @c other using @c copyTo(). 163 /// 164 /// @param other option definitions to merge in. 165 /// 166 /// @warning The merge operation affects @c other. 167 /// Therefore, the caller must not rely on the data held in the @c other 168 /// object after the call to @c merge. Also, the data held in @c other must 169 /// not be modified after the call to @c merge because it may affect the 170 /// merged configuration. 171 void merge(CfgOptionDef& other); 172 173 private: 174 175 /// @brief A collection of option definitions. 176 /// 177 /// The option definitions stored in this container can be accessed 178 /// using the option space name they belong to. 179 OptionDefSpaceContainer option_definitions_; 180 181 }; 182 183 /// @name Pointers to the @c CfgOptionDef objects. 184 //@{ 185 /// @brief Non-const pointer. 186 typedef boost::shared_ptr<CfgOptionDef> CfgOptionDefPtr; 187 188 /// @brief Const pointer. 189 typedef boost::shared_ptr<const CfgOptionDef> ConstCfgOptionDefPtr; 190 191 //@} 192 193 } 194 } 195 196 #endif // CFG_OPTION_DEF_H 197