Commit 04b0e46c authored by Marcin Siodelski's avatar Marcin Siodelski

[1955] Reword comments in PerfPkt4 and PktTransform classes.

parent 1a0a81eb
......@@ -28,24 +28,18 @@ namespace perfdhcp {
///
/// This class extends functionality of \ref isc::dhcp::Pkt4 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::LocalizedOption type.
/// and override options' contents.
/// This is in particular useful when we create packet object using
/// template file (do not build it dynamically). Client class
/// should read data from template file and pass data to this class
/// as buffer.
/// Contents of such packet can be later partially replaced: preciselly
/// selected options and transaction id can be replaced.
/// Transaction id and its offset in template file is passed via
/// constructor.
/// In order to replace contents of options client class has to
/// create collection of \ref LocalizedOption by adding them using
/// \ref dhcp::Pkt4::addOption.
///
/// \note: if you don't use template files simply use constructors
/// inherited from parent class and isc::dhcp::Option type instead
......@@ -69,15 +63,14 @@ public:
/// \brief Constructor, used for outgoing DHCP messages.
///
/// Creates new DHCPv4 message using provided buffer.
/// Transaction id and its offset are specified through this
/// constructor so as they are stored in outgoing message
/// Transaction id and its offset are specified via this
/// constructor. Transaction id is stored in outgoing message
/// when client class calls \ref PerfPkt4::rawPack.
///
/// \note This constructor should be used only for outgoing
/// messages that are created from raw buffer (e.g. read from
/// template files).
/// messages that are created from template files.
///
/// \param buf buffer holiding contents of the message (this can
/// \param buf buffer holding contents of the message (this can
/// be directly read from template file).
/// \param len length of the data in the buffer.
/// \param transid_offset transaction id offset in outgoing message.
......@@ -89,20 +82,19 @@ public:
/// Constructor, used for incoming DHCP messages.
///
/// 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::LocalizedOption for details.
/// Creates new DHCPv4 message using provided buffer.
/// Client class may indicate which options are to be read
/// from the buffer. Such options should be added to
/// options collection using dhcp::Pkt4::addOption. Such
/// options should be of \ref LocalizedOption class.
///
/// Transaction id offset point to location of raw data where
/// Transaction id offset points to location where
/// transaction id field is stored. The transaction id will
/// be read from this location when PerfPkt4::rawUnpack is
/// called. The transid_ class member will be updated accordingly.
///
/// \note use this constructor only in case you want to create
/// incoming DHCPv6 object from the raw buffer
/// incoming DHCPv4 object from the raw buffer
/// and you know options offsets. Options offsets are
/// specified from perfdhcp command line by the user.
///
......@@ -118,13 +110,13 @@ public:
/// return transaction id offset in packet buffer
size_t getTransIdOffset() const { return transid_offset_; };
/// \brief Prepares on-wire format from raw buffer
/// \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.
/// The method copies buffer provided in constructor to
/// output buffer and replaces transaction id and selected
/// options with new data.
///
/// \note: Use this method to prepare on-wire DHCPv6 message
/// \note: Use this method to prepare on-wire DHCPv4 message
/// when you use template packets that require replacement
/// of selected options' contents before sending.
///
......@@ -134,11 +126,12 @@ public:
/// \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
/// Function handles parsing of packets that have custom offsets
/// of options or transaction id. Use
/// \ref isc::dhcp::Pkt4::addOption to specify which options to parse.
/// Each option should be of the: isc::perfdhcp::LocalizedOption
/// type with offset value indicated.
/// Options should be of the: isc::perfdhcp::LocalizedOption
/// type with offset values provided. Each added option will
/// be updated with actual data read from the binary packet buffer.
///
/// \return false, if unpack operation failed.
bool rawUnpack();
......
......@@ -28,7 +28,7 @@ namespace perfdhcp {
/// data from packet buffer and write raw data to packet
/// buffer. When reading data with unpack() method, the
/// corresponding options objects are updated.
/// When writting to the packet buffer with pack() nethod,
/// When writing to the packet buffer with pack(),
/// options objects carry input data to be written.
/// This class is used both by \ref PerfPkt4 and
/// \ref PerfPkt6 classes in case DHCP packets are created
......@@ -37,29 +37,22 @@ namespace perfdhcp {
/// server. Offset of specific options are provided from
/// command line by perfdhcp tool user and passed in
/// options collection.
/// This class also provide mechanism to read some data
/// from incoming packet buffer and update options
/// in options collection with these data.
/// It is assumed either in case of writting or reading
/// that all options have to be added to options collection
/// and their offset have to be specified in buffer
/// (\see LocalizedOption).
class PktTransform {
public:
/// \brief Prepares on-wire format from raw buffer
/// \brief Prepares on-wire format from raw buffer.
///
/// The method copies input buffer and options contents
/// to output buffer. Input buffer must contain whole
/// initial packet data. Parts of this data will be
/// overriden by options data specified in options
/// collection. Such options must have their offsets in
/// a packet specified (\see LocalizedOption to find out how
/// to specify options offset).
/// collection. Such options must have their offsets within
/// a packet specified (see \ref LocalizedOption to find out
/// how to specify options offset).
///
/// \note Specified options must fit into size of the
/// initial packet data. Call to this function will fail
/// if option's offset + its size is out of bounds.
/// if option's offset + its size is beyond packet's size.
///
/// \param universe universe used, V4 or V6
/// \param in_buffer input buffer holiding intial packet
......@@ -79,16 +72,13 @@ public:
const uint32_t transid,
util::OutputBuffer& out_buffer);
/// \brief Handles limited binary packet parsing for packets with
/// custom offsets of options and transaction id.
/// \brief Handles selective binary packet parsing.
///
/// Function handles parsing of packet that have non-default values
/// of options or transaction id offsets. Use
/// Function handles parsing of packets that have non-default
/// options or transaction id offsets. Client class has to use
/// \ref isc::dhcp::Pkt6::addOption to specify which options to parse.
/// Each option should be of the \ref isc::perfdhcp::LocalizedOption
/// type with offset value indicated.
/// Transaction id offset is specified as separate argument and
/// is used to read transaction id value from buffer.
/// type with offset value specified.
///
/// \param universe universe used, V4 or V6
/// \param in_buffer input buffer to be parsed
......@@ -103,11 +93,11 @@ public:
uint32_t& transid);
private:
/// \brief Replaces options contents of options in a buffer
/// \brief Replaces contents of options in a buffer.
///
/// The method uses localized options collection added to
/// replace parts of initial packet data (e.g. read from
/// template file).
/// The method uses localized options collection to
/// replace parts of packet data (e.g. data read
/// from template file).
/// This private method is called from \ref PktTransform::pack
///
/// \param in_buffer input buffer holding initial packet data.
......@@ -118,12 +108,12 @@ private:
const dhcp::Option::OptionCollection& options,
util::OutputBuffer& out_buffer);
/// \brief Reads contents of specified options from buffer
/// \brief Reads contents of specified options from buffer.
///
/// The method reads options data from the input buffer
/// and stores read data in options objects. Options
/// must have their offsets in a buffer specified
/// (\see LocalizedOption to find out how to specify
/// and stores it in options objects. Offsets of options
/// must be specified.
/// (see \ref LocalizedOption to find out how to specify
/// option offset).
/// This private method is called by \ref PktTransform::unpack.
///
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment