kea/tests/tools/perfdhcp/perf_pkt6.h

// Copyright (C) 2011  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

#ifndef __PERF_PKT6_H
#define __PERF_PKT6_H

#include <time.h>

#include <dhcp/pkt6.h>

namespace isc {
namespace perfdhcp {

/// \brief PerfPkt6 (DHCPv6 packet)
///
/// This class extends functionality of \ref isc::dhcp::Pkt6 by
/// adding ability to specify options offset in DHCP message
/// and override options' contents with new option.
/// This approach is useful when we create paket object from
/// raw template buffer from file and we want to use it as
/// a base to create test packets to be sent to DHCP server.
///
/// Some of the contents of such a template packets always
/// have to be replaced e.g. transaction id, IA_NA. Other
/// contents (options) may be changed e.g. elapsed time,
/// server id.
///
/// In order to create packet from raw template buffer
/// we have to pass this buffer along with transaction id
/// offset. Class will read transaction id from the buffer.
/// Next, in order to replace contents of selected options
/// in a template packet, we need to add these selected options
/// to packet object using addOption() method. Please note
/// that options must be of the
/// \ref isc::perfdhcp::PerfPkt6::PositionedOption type.
///
/// This class also records timestamps of last pack/unpack
/// operation on the packet. This is to track DHCP server
/// performance based on packet's send/receive duration.
///
/// \note: if you don't use template files simply use constructors
/// inherited from parent class and isc::dhcp::Option type instead
///
class PerfPkt6 : public dhcp::Pkt6 {
public:

    /// \brief Class represents position of DHCP option in a packet
    class OptionPosition {
    public:
        /// \brief Class constructor
        ///
        /// Applies default value of option position
        explicit OptionPosition() : position_(0) { };

        /// \brief Class constructor
        ///
        /// \param position position of option in DHCP packet
        explicit OptionPosition(size_t position) : position_(position)  { };

        /// \brief Returns position of DHCP option in a packet
        ///
        /// \return position of DHCP option in packet
        size_t get() const { return position_; }
    private:
        size_t position_;    ///< position of option in a packet
                               ///< Zero is default position
    };

    /// \brief DHCPv6 option at specific offset
    ///
    /// This class represents DHCPv6 option at specified
    /// offset in DHCPv6 message.
    ///
    class PositionedOption : public dhcp::Option {
    public:
        /// \brief Constructor, used to create positioned option from buffer
        ///
        ///
        /// \param u specifies universe (V4 or V6)
        /// \param type option type (0-255 for V4 and 0-65535 for V6)
        /// \param data content of the option
        /// \param position absolute position of option in a packet (zero is default)
        PositionedOption(dhcp::Option::Universe u, uint16_t type, const dhcp::OptionBuffer& data,
                         const OptionPosition& position);

        /// \brief Constructor, used to create positioned option from buffer iterators
        ///
        /// This contructor is similar to the previous one, but it does not take
        /// the whole vector<uint8_t>, but rather subset of it.
        ///
        /// \param u specifies universe (V4 or V6)
        /// \param type option type (0-255 for V4 and 0-65535 for V6)
        /// \param first iterator to the first element that should be copied
        /// \param last iterator to the next element after the last one
        ///        to be copied.
        /// \param position absolute position of option in a packet (zero is default)
        PositionedOption(dhcp::Option::Universe u, uint16_t type, dhcp::OptionBufferConstIter first,
                         dhcp::OptionBufferConstIter last, const OptionPosition& position);


        /// \brief Returns absolute position (offset) of an option in a
        /// DHCPv6 packet.
        ///
        /// \return absolute position (offset) of an option in a packet
        size_t getOptionPosition() const { return position_.get(); };

    private:
        OptionPosition position_;   ///< Absolute position of DHCPv6 option in a packet
    };

    /// Constructor, used in message transmission
    ///
    /// Creates new DHCPv6 message using provided buffer. New object
    /// will keep copy of contents of provided buffer. If buffer contains
    /// options at custom offsets (e.g. if packet was read from
    /// template file) additional information about options'
    /// offsets has to be provided - see
    /// \ref isc::perfdhcp::PositionedOption for details.
    ///
    /// Transaction id is not considered DHCP option so
    /// we pass it to constructor as extra argument. This is
    /// required if transaction id offset differs from the
    /// default one for DHCPv6 messages (ocets 2-4).
    ///
    /// \note use this constructor only in case you want to create
    /// DHCPv6 message (incoming or outgoing) from the raw buffer
    /// and you know options offsets. Options offsets are
    /// specified from perfdhcp command line by the user.
    ///
    /// \param buf pointer to a buffer of received packet content
    /// \param len size of buffer of packet content
    /// \param xid_off transaction id offset in a packet
    PerfPkt6(const uint8_t* buf,
             uint32_t len,
             const OptionPosition& transid_offset);

    /// \brief Prepare on-wire packet format and record timestamp
    ///
    /// Prepares on-wire format of packet and all its options.
    /// This method wraps dhcp::Pkt6::pack() function to
    /// update packet timestamp.
    ///
    /// \note Use this function if you don't use template files
    /// to construct DHCPv6 packets.
    ///
    /// \throw isc::Unexpected if pack and timestamp update failed
    void stampedPack();

    /// \brief Handles binary packet parsing and updates timestamp
    ///
    /// This method wraps dhcp::Pkt6::unpack() function to
    /// update packet timestamp.
    ///
    /// \note Use this function if you don't use template files
    /// and custom options offsets to construct DHCPv6 packets.
    ///
    /// \throw isc::Unexpected if function failed
    void stampedUnpack();

    /// \brief Prepares on-wire format from raw buffer
    ///
    /// The method copies user buffer to output buffer and
    /// extracts transaction id from it based on transaction id
    /// offset provided in constructor.
    /// Eventually, this method updates packet timestamp.
    ///
    /// \note: Use this method to prepare on-wire DHCPv6 message
    /// when you use template packets that require replacement
    /// of selected options contents before sending.
    ///
    /// \throw isc::Unexepected if function failed
    void stampedRawPack();

    /// \brief Handles limited binary packet parsing for packets with
    /// custom offsets of options and transaction id
    ///
    /// Function handles reception of packets that have non-default values
    /// of options or transaction id offsets. Use
    /// \ref isc::dhcp::Pkt6::addOption to specify which options to parse.
    /// Each option should be of the: isc::perfdhcp::PerfPkt6::PositionedOption
    /// type with offset value indicated.
    ///
    /// \throw isc::Unexpected if function failed
    void stampedRawUnpack();

private:

    /// \brief Updates options in the output buffer
    ///
    /// This method updates options in the output buffer
    /// with the ones provided with
    /// \ref isc::dhcp::Pkt6::addOption. It is expected
    /// that these options will be of the
    /// \ref isc::perfdhcp::PerfPkt6::PositionedOption type
    /// with their position (offset) specified.
    ///
    /// throw isc::Unexpected if options update fails
    void updateOptions();

    /// \brief Update packet timestamp with current time
    ///
    /// \throw isc::Unexpected if timestamp update failed
    void updateTimestamp();

    OptionPosition transid_offset_;  ///< transaction id offset
    timespec time_stamp_;            ///< time stamp of last pack or unpack

};

} // namespace perfdhcp
} // namespace isc

#endif // __PERF_PKT6_H