pkt_transform.h 6.09 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
// 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 __PKT_TRANSFORM_H
#define __PKT_TRANSFORM_H

#include <dhcp/option.h>

#include "localized_option.h"

namespace isc {
namespace perfdhcp {

/// \brief Read and write raw data to DHCP packets.
///
27 28 29 30 31
/// This class provides static functions to read/write raw data from/to the
/// packet buffer. When reading data with the unpack() method, the
/// corresponding options objects are updated.  When writing to the packet
/// buffer with pack(), options objects carry input data to be written.
///
32
/// This class is used both by \ref PerfPkt4 and
33 34
/// \ref PerfPkt6 classes in case DHCP packets are created
/// from template files. In this case, some of the template
35 36 37
/// packet's options are replaced before sending it to the
/// server. Offset of specific options are provided from the
/// command line by the perfdhcp tool user, and passed in an
38 39 40 41
/// options collection.
class PktTransform {
public:

42
    /// \brief Prepares on-wire format from raw buffer.
43
    ///
44 45
    /// The method copies the input buffer and options contents
    /// to the output buffer. The input buffer must contain whole
46
    /// initial packet data. Parts of this data will be
47
    /// overriden by options data specified in an options
48 49 50
    /// collection. Such options must have their offsets within
    /// a packet specified (see \ref LocalizedOption to find out
    /// how to specify options offset).
51
    ///
52 53 54
    /// \note The specified options must fit into the size of the
    /// initial packet data. A call to this method will fail
    /// if the option's offset + its size is beyond the packet's size.
55
    ///
56 57
    /// \param universe Universe used, V4 or V6
    /// \param in_buffer Input buffer holding intial packet
58
    /// data, this can be directly read from template file
59 60 61
    /// \param options Options collection with offsets
    /// \param transid_Offset offset of transaction id in a packet,
    /// transaction ID will be written to output buffer at this
62
    /// offset
63 64
    /// \param transid Transaction ID value
    /// \param out_buffer Output buffer holding "packed" data
65
    ///
66
    /// \return false, if pack operation failed.
67 68 69 70 71 72 73
    static bool pack(const dhcp::Option::Universe universe,
                     const dhcp::OptionBuffer& in_buffer,
                     const dhcp::Option::OptionCollection& options,
                     const size_t transid_offset,
                     const uint32_t transid,
                     util::OutputBuffer& out_buffer);

74
    /// \brief Handles selective binary packet parsing.
75
    ///
76 77
    /// This method handles the parsing of packets that have non-default
    /// options or transaction ID offsets. The client class has to use
78 79
    /// \ref isc::dhcp::Pkt6::addOption to specify which options to parse.
    /// Each option should be of the \ref isc::perfdhcp::LocalizedOption
80
    /// type with the offset value specified.
81 82 83 84 85 86
    ///
    /// \param universe universe used, V4 or V6
    /// \param in_buffer input buffer to be parsed
    /// \param options options collection with options offsets
    /// \param transid_offset offset of transaction id in input buffer
    /// \param transid transaction id value read from input buffer
87
    ///
88
    /// \return false, if unpack operation failed.
89
    static bool unpack(const dhcp::Option::Universe universe,
90 91 92 93 94 95
                       const dhcp::OptionBuffer& in_buffer,
                       const dhcp::Option::OptionCollection& options,
                       const size_t transid_offset,
                       uint32_t& transid);

private:
96
    /// \brief Replaces contents of options in a buffer.
97
    ///
98
    /// The method uses a localized options collection to
99 100
    /// replace parts of packet data (e.g. data read
    /// from template file).
101 102 103 104 105
    /// This private method is called from \ref PktTransform::pack
    ///
    /// \param in_buffer input buffer holding initial packet data.
    /// \param out_buffer output buffer with "packed" options.
    /// \param options options collection with actual data and offsets.
106
    ///
107 108
    /// \throw isc::Unexpected if options update failed.
    static void packOptions(const dhcp::OptionBuffer& in_buffer,
109 110
                            const dhcp::Option::OptionCollection& options,
                            util::OutputBuffer& out_buffer);
111

112
    /// \brief Reads contents of specified options from buffer.
113 114
    ///
    /// The method reads options data from the input buffer
115 116 117
    /// and stores it in options objects. Offsets of the options
    /// must be specified (see \ref LocalizedOption to find out how to specify
    /// the option offset).
118 119
    /// This private method is called by \ref PktTransform::unpack.
    ///
120 121
    /// \note This method iterates through all options in an
    /// options collection, checks the offset of the option
122
    /// in input buffer and reads data from the buffer to
123 124
    /// update the option's buffer. If the provided options collection
    /// is empty, a call to this method will have no effect.
125
    ///
126 127
    /// \param universe universe used, V4 or V6
    /// \param in_buffer input buffer to be parsed.
128
    /// \param options oprions collection with their offsets
129
    /// in input buffer specified.
130
    ///
131
    /// \throw isc::Unexpected if options unpack failed.
132
    static void unpackOptions(const dhcp::OptionBuffer& in_buffer,
133 134 135 136 137 138 139
                              const dhcp::Option::OptionCollection& options);
};

} // namespace perfdhcp
} // namespace isc

#endif // __PKT_TRANSFORM_H