Current File : //backups/router/usr/local/include/kea/dhcpsrv/parsers/option_data_parser.h
// Copyright (C) 2017-2023 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#ifndef OPTION_DATA_PARSER_H
#define OPTION_DATA_PARSER_H
#include <cc/data.h>
#include <cc/simple_parser.h>
#include <dhcp/option_definition.h>
#include <dhcpsrv/cfg_option.h>
#include <dhcpsrv/cfg_option_def.h>
#include <boost/shared_ptr.hpp>
#include <util/optional.h>
#include <cstdint>
#include <string>
#include <utility>
namespace isc {
namespace dhcp {
/// @brief Parser for option data value.
///
/// This parser parses configuration entries that specify value of
/// a single option. These entries include option name, option code
/// and data carried by the option. The option data can be specified
/// in one of the two available formats: binary value represented as
/// a string of hexadecimal digits or a list of comma separated values.
/// The format being used is controlled by csv-format configuration
/// parameter. When setting this value to True, the latter format is
/// used. The subsequent values in the CSV format apply to relevant
/// option data fields in the configured option. For example the
/// configuration: "data" : "192.168.2.0, 56, hello world" can be
/// used to set values for the option comprising IPv4 address,
/// integer and string data field. Note that order matters. If the
/// order of values does not match the order of data fields within
/// an option the configuration will not be accepted. If parsing
/// is successful then an instance of an option is created and
/// added to the storage provided by the calling class.
class OptionDataParser : public isc::data::SimpleParser {
public:
/// @brief Constructor.
///
/// @param address_family Address family: @c AF_INET or @c AF_INET6.
/// @param cfg_option_def Config option definitions (optional)
OptionDataParser(const uint16_t address_family,
CfgOptionDefPtr cfg_option_def = CfgOptionDefPtr());
/// @brief Virtual destructor.
virtual ~OptionDataParser() {
}
/// @brief Parses ElementPtr containing option definition
///
/// This method parses ElementPtr containing the option definition,
/// instantiates the option for it and then returns a pair
/// of option descriptor (that holds that new option) and
/// a string that specifies the option space.
///
/// Note: ElementPtr is expected to contain all fields. If your
/// ElementPtr does not have them, please use
/// @ref isc::data::SimpleParser::setDefaults to fill the missing fields
/// with default values.
///
/// @param single_option ElementPtr containing option definition
/// @return Option object wrapped in option description and an option
/// space
std::pair<OptionDescriptor, std::string>
parse(isc::data::ConstElementPtr single_option);
protected:
/// @brief Finds an option definition within an option space
///
/// Given an option space and an option code, find the corresponding
/// option definition within the option definition storage.
///
/// @param option_space name of the parameter option space
/// @param option_code option code to be used to find the option
/// definition, if the option name is unspecified.
/// @param option_name option name to be used to lookup the option
/// definition.
///
/// @return OptionDefinitionPtr of the option definition or an
/// empty OptionDefinitionPtr if not found.
/// @throw DhcpConfigError if the option space requested is not valid
/// for this server.
virtual OptionDefinitionPtr
findOptionDefinition(const std::string& option_space,
const util::Optional<uint32_t>& option_code,
const util::Optional<std::string>& option_name) const;
/// @brief Create option instance.
///
/// Creates an instance of an option and adds it to the provided
/// options storage. If the option data parsed by createOption function
/// is invalid or insufficient this function emits an exception.
///
/// If the option data is given as a string containing a hexadecimal
/// literal, then it is converted into binary format. These literals
/// may contain upper and lower case digits. They may be octets
/// delimited by colons or spaces (octets may be 1 or 2 digits)
/// If not delimited octets then they must be a continuous string of
/// digits with or without a "0x" prefix. Examples:
///
/// -# ab:cd:ef - colon delimited
/// -# ab cd ef - space delimited
/// -# 0xabcdef - 0x prefixed (no delimiters)
/// -# abcdef - no prefix or delimiters
///
/// A leading zero is assumed for odd number of digits
/// in an octet or continuous string.
///
/// @param option_data An element holding data for a single option being
/// created.
///
/// @return created option descriptor
///
/// @throw DhcpConfigError if parameters provided in the configuration
/// are invalid.
std::pair<OptionDescriptor, std::string>
createOption(isc::data::ConstElementPtr option_data);
/// @brief Retrieves parsed option code as an optional value.
///
/// @param parent A data element holding full option data configuration.
///
/// @return Option code, possibly unspecified.
/// @throw DhcpConfigError if option code is invalid.
util::Optional<uint32_t>
extractCode(data::ConstElementPtr parent) const;
/// @brief Retrieves parsed option name as an optional value.
///
/// @param parent A data element holding full option data configuration.
///
/// @return Option name, possibly unspecified.
/// @throw DhcpConfigError if option name is invalid.
util::Optional<std::string>
extractName(data::ConstElementPtr parent) const;
/// @brief Retrieves csv-format parameter as an optional value.
///
/// @return Value of the csv-format parameter, possibly unspecified.
util::Optional<bool> extractCSVFormat(data::ConstElementPtr parent) const;
/// @brief Retrieves option data as a string.
///
/// @param parent A data element holding full option data configuration.
/// @return Option data as a string. It will return empty string if
/// option data is unspecified.
util::Optional<std::string>
extractData(data::ConstElementPtr parent) const;
/// @brief Retrieves option space name.
///
/// If option space name is not specified in the configuration the
/// 'dhcp4' or 'dhcp6' option space name is returned, depending on
/// the universe specified in the parser context.
///
/// @param parent A data element holding full option data configuration.
///
/// @return Option space name.
std::string extractSpace(data::ConstElementPtr parent) const;
/// @brief Retrieves persistent/always-send parameter as an optional value.
///
/// @return Value of the persistent parameter, possibly unspecified.
util::Optional<bool> extractPersistent(data::ConstElementPtr parent) const;
/// @brief Retrieves cancelled/never-send parameter as an optional value.
///
/// @return Value of the cancelled parameter, possibly unspecified.
util::Optional<bool> extractCancelled(data::ConstElementPtr parent) const;
/// @brief Address family: @c AF_INET or @c AF_INET6.
uint16_t address_family_;
/// @brief Config option definitions
CfgOptionDefPtr cfg_option_def_;
};
/// @brief Parser for option data values within a subnet.
///
/// This parser iterates over all entries that define options
/// data for a particular subnet and creates a collection of options.
/// If parsing is successful, all these options are added to the Subnet
/// object.
class OptionDataListParser : public isc::data::SimpleParser {
public:
/// @brief Constructor.
///
/// @param address_family Address family: @c AF_INET or AF_INET6
/// @param cfg_option_def Config option definitions (optional)
OptionDataListParser(const uint16_t address_family,
CfgOptionDefPtr cfg_option_def = CfgOptionDefPtr());
/// @brief Virtual destructor.
virtual ~OptionDataListParser() {
}
/// @brief Parses a list of options, instantiates them and stores in cfg
///
/// This method expects to get a list of options in option_data_list,
/// iterates over them, creates option objects, wraps them with
/// option descriptor and stores in specified cfg.
///
/// @param cfg created options will be stored here
/// @param option_data_list configuration that describes the options
/// @param encapsulate a boolean value indicating whether or not the
/// parser should encapsulate options with suboptions. The default
/// value is true (encapsulate).
void parse(const CfgOptionPtr& cfg,
isc::data::ConstElementPtr option_data_list,
bool encapsulate = true);
protected:
/// @brief Returns an instance of the @c OptionDataListParser to
/// be used in parsing options.
///
/// This function can be overridden in the child classes to supply
/// a custom parser for option data.
///
/// @return an instance of the @c OptionDataListParser.
virtual boost::shared_ptr<OptionDataParser> createOptionDataParser() const;
/// @brief Address family: @c AF_INET or @c AF_INET6
uint16_t address_family_;
/// @brief Config option definitions
CfgOptionDefPtr cfg_option_def_;
};
} // end of namespace isc::dhcp
} // end of namespace isc
#endif // OPTION_DATA_PARSER_H
Mini Shell