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