Commit be57f66a authored by Stephen Morris's avatar Stephen Morris

[1955] Miscellaneous corrections to comments.

parent 53dfacdd
......@@ -26,24 +26,24 @@ namespace perfdhcp {
/// \brief PerfPkt4 (DHCPv4 packet)
///
/// This class extends functionality of \ref isc::dhcp::Pkt4 by
/// adding ability to specify options offset in DHCP message
/// 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
/// This class extends the functionality of \ref isc::dhcp::Pkt4 by adding the
/// ability to specify an options offset in the DHCP message and to override
/// options' contents. This is particularly useful when we create a packet
/// object using a template file (i.e. do not build it dynamically). The client
/// class should read data from the template file and pass it to this class in
/// a buffer.
///
/// The contents of such a packet can be later partially replaced, notably the
/// selected options and the transaction ID. (The transaction ID and its
/// offset in the template file are passed via the constructor.)
///
/// In order to replace contents of the options, the client class has to
/// create a collection of \ref LocalizedOption, adding them using
/// \ref dhcp::Pkt4::addOption.
///
/// \note: if you don't use template files simply use constructors
/// \note If you don't use template files simply use constructors
/// inherited from parent class and isc::dhcp::Option type instead
///
class PerfPkt4 : public dhcp::Pkt4 {
public:
......@@ -52,7 +52,7 @@ public:
/// \brief Constructor, used for outgoing and incoming messages
///
/// This constructor initializes transaction id and
/// This constructor initializes the transaction ID and
/// transaction id offset of the packet with default
/// values.
///
......@@ -62,10 +62,10 @@ public:
/// \brief Constructor, used for outgoing DHCP messages.
///
/// Creates new DHCPv4 message using provided buffer.
/// Transaction id and its offset are specified via this
/// constructor. Transaction id is stored in outgoing message
/// when client class calls \ref PerfPkt4::rawPack.
/// Creates new DHCPv4 message using the provided buffer. The
/// transaction ID and its offset are specified via this
/// constructor. The transaction ID is stored in the outgoing message
/// when the client class calls \ref PerfPkt4::rawPack.
///
/// \note This constructor should be used only for outgoing
/// messages that are created from template files.
......@@ -82,21 +82,21 @@ public:
/// Constructor, used for incoming DHCP messages.
///
/// 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
/// Creates new DHCPv4 message using the provided buffer.
/// The client class may indicate which options are to be read
/// from the buffer. Such options should be added to the
/// options collection using \ref dhcp::Pkt4::addOption: these
/// options should be of \ref LocalizedOption class.
///
/// 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
/// The transaction ID offset points to the location where the
/// transaction ID field is stored. The transaction ID will
/// be read from this location when \ref PerfPkt4::rawUnpack is
/// called. The transid_ class member will be updated accordingly.
///
/// \note use this constructor only in case you want to create
/// incoming DHCPv4 object from the raw buffer
/// and you know options offsets. Options offsets are
/// specified from perfdhcp command line by the user.
/// \note Use this constructor only in the case where you want to create
/// an incoming DHCPv4 object from the raw buffer
/// and you know the options offsets. The options offsets are
/// specified on the perfdhcp command line by the user.
///
/// \param buf pointer to a buffer of received packet content.
/// \param len size of buffer of packet content.
......@@ -107,33 +107,33 @@ public:
/// \brief Returns transaction id offset in packet buffer
///
/// return transaction id offset in packet buffer
/// \return Transaction ID offset in packet buffer
size_t getTransIdOffset() const { return transid_offset_; };
/// \brief Prepares on-wire format from raw buffer.
///
/// The method copies buffer provided in constructor to
/// output buffer and replaces transaction id and selected
/// The method copies the buffer provided in the constructor to the
/// output buffer and replaces the transaction ID and selected
/// options with new data.
///
/// \note: Use this method to prepare on-wire DHCPv4 message
/// \note Use this method to prepare an on-wire DHCPv4 message
/// when you use template packets that require replacement
/// of selected options' contents before sending.
///
/// \return false, id pack operation failed.
/// \return false ID pack operation failed.
bool rawPack();
/// \brief Handles limited binary packet parsing for packets with
/// custom offsets of options and transaction id
/// custom offsets of options and transaction ID
///
/// Function handles parsing of packets that have custom offsets
/// of options or transaction id. Use
/// This method handles the parsing of packets that have custom offsets
/// of options or transaction ID. Use
/// \ref isc::dhcp::Pkt4::addOption to specify which options to parse.
/// Options should be of the: isc::perfdhcp::LocalizedOption
/// Options should be of the \ref 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.
/// \return false If unpack operation failed.
bool rawUnpack();
private:
......
......@@ -26,24 +26,24 @@ 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.
/// 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::Pkt6::addOption.
/// This class extends the functionality of \ref isc::dhcp::Pkt6 by
/// adding the ability to specify an options offset in the DHCP message
/// and so override the options' contents. This is particularly useful when we
/// create a packet object using a template file (i.e. do not build it
/// dynamically). The client class should read the data from the template file
/// and pass it to this class as a buffer.
///
/// The contents of such packet can be later partially replaced: in particular,
/// selected options and the transaction ID can be altered. (The transaction
/// ID and its offset in the template file is passed via the constructor.)
///
/// \note: if you don't use template files simply use constructors
/// inherited from parent class and isc::dhcp::Option type instead
/// In order to replace the contents of options, the client class has to
/// create a collection of \ref LocalizedOption by adding them using
/// \ref dhcp::Pkt6::addOption.
///
/// \note If you don't use template files, simply use constructors
/// inherited from parent class and the \ref isc::dhcp::Option type instead.
class PerfPkt6 : public dhcp::Pkt6 {
public:
......@@ -52,8 +52,8 @@ public:
/// \brief Constructor, used for outgoing and incoming messages
///
/// This constructor initializes transaction id and
/// transaction id offset of the packet with default
/// This constructor initializes the transaction ID and the
/// transaction ID offset of the packet with default
/// values.
///
/// \param buf buffer holding contents of the message.
......@@ -62,9 +62,9 @@ public:
/// \brief Constructor, used for outgoing DHCP messages.
///
/// Creates new DHCPv6 message using provided buffer.
/// Transaction id and its offset are specified via this
/// constructor. Transaction id is stored in outgoing message
/// Creates a new DHCPv6 message using the provided buffer.
/// The transaction ID and its offset are specified via this
/// constructor. The transaction ID is stored in outgoing message
/// when client class calls \ref PerfPkt6::rawPack.
///
/// \note This constructor should be used only for outgoing
......@@ -82,21 +82,21 @@ public:
/// Constructor, used for incoming DHCP messages.
///
/// Creates new DHCPv6 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
/// Creates a new DHCPv6 message using the provided buffer. The
/// client class may indicate which options are to be read
/// from the buffer. Such options should be added to the
/// options collection using \ref dhcp::Pkt4::addOption. The
/// options should be of \ref LocalizedOption class.
///
/// 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
/// The transaction ID offset points to location where the
/// transaction ID field is stored. The transaction ID will
/// be read from this location when \ref PerfPkt4::rawUnpack is
/// called. The transid_ class member will be updated accordingly.
///
/// \note use this constructor only in case you want to create
/// \note Use this constructor only in the case where you want to create
/// incoming DHCPv4 object from the raw buffer
/// and you know options offsets. Options offsets are
/// specified from perfdhcp command line by the user.
/// and you know the options offsets. Options offsets are
/// specified on the perfdhcp command line by the user.
///
/// \param buf pointer to a buffer of received packet content.
/// \param len size of buffer of packet content.
......@@ -107,33 +107,33 @@ public:
/// \brief Returns transaction id offset in packet buffer
///
/// return transaction id offset in packet buffer
/// \return Transaction ID offset in the 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 buffer provided in constructor to
/// output buffer and replaces transaction id and selected
/// The method copies the buffer provided in constructor to the
/// output buffer and replaces the transaction ID and selected
/// options with new data.
///
/// \note: Use this method to prepare on-wire DHCPv6 message
/// \note Use this method to prepare an on-wire DHCPv6 message
/// when you use template packets that require replacement
/// of selected options' contents before sending.
///
/// \return false, id pack operation failed.
/// \return false ID pack operation failed.
bool rawPack();
/// \brief Handles limited binary packet parsing for packets with
/// custom offsets of options and transaction id
///
/// Function handles parsing of packets that have custom offsets
/// of options or transaction id. Use
/// This methoid handles the parsing of packets that have custom offsets
/// of options or transaction ID. Use
/// \ref isc::dhcp::Pkt4::addOption to specify which options to parse.
/// Options should be of the: isc::perfdhcp::LocalizedOption
/// Options should be of the \ref 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.
/// \return false if unpack operation failed.
bool rawUnpack();
private:
......
......@@ -105,7 +105,7 @@ PktTransform::unpack(const Option::Universe universe,
& 0xFFFFFF;
} else {
transid = ((in_buffer[transid_offset] << 24) +
(in_buffer[transid_offset +1 ] << 16) +
(in_buffer[transid_offset + 1] << 16) +
(in_buffer[transid_offset + 2] << 8) +
(in_buffer[transid_offset + 3]));
}
......
......@@ -24,45 +24,44 @@ namespace perfdhcp {
/// \brief Read and write raw data to DHCP packets.
///
/// This class provides static functions to read raw
/// data from packet buffer and write raw data to packet
/// buffer. When reading data with unpack() method, the
/// corresponding options objects are updated.
/// When writing to the packet buffer with pack(),
/// options objects carry input data to be written.
/// 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.
///
/// This class is used both by \ref PerfPkt4 and
/// \ref PerfPkt6 classes in case DHCP packets are created
/// from template files. In this case, some of the template
/// packet's options are replaced before sending it to
/// server. Offset of specific options are provided from
/// command line by perfdhcp tool user and passed in
/// 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
/// options collection.
class PktTransform {
public:
/// \brief Prepares on-wire format from raw buffer.
///
/// The method copies input buffer and options contents
/// to output buffer. Input buffer must contain whole
/// The method copies the input buffer and options contents
/// to the output buffer. The input buffer must contain whole
/// initial packet data. Parts of this data will be
/// overriden by options data specified in options
/// overriden by options data specified in an options
/// 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 beyond packet's size.
/// \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.
///
/// \param universe universe used, V4 or V6
/// \param in_buffer input buffer holiding intial packet
/// \param universe Universe used, V4 or V6
/// \param in_buffer Input buffer holding intial packet
/// data, this can be directly read from template file
/// \param options options collection with offsets
/// \param transid_offset offset of transaction id in a packet,
/// transatcion id will be written to output buffer at this
/// \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
/// offset
/// \param transid transaction id value
/// \param out_buffer output buffer holding "packed" data
/// \param transid Transaction ID value
/// \param out_buffer Output buffer holding "packed" data
///
/// \return false, if pack operation failed.
static bool pack(const dhcp::Option::Universe universe,
......@@ -74,17 +73,18 @@ public:
/// \brief Handles selective binary packet parsing.
///
/// Function handles parsing of packets that have non-default
/// options or transaction id offsets. Client class has to use
/// This method handles the parsing of packets that have non-default
/// options or transaction ID offsets. The 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 specified.
/// type with the offset value specified.
///
/// \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
///
/// \return false, if unpack operation failed.
static bool unpack(const dhcp::Option::Universe universe,
const dhcp::OptionBuffer& in_buffer,
......@@ -95,7 +95,7 @@ public:
private:
/// \brief Replaces contents of options in a buffer.
///
/// The method uses localized options collection to
/// The method uses a 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
......@@ -103,6 +103,7 @@ private:
/// \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.
///
/// \throw isc::Unexpected if options update failed.
static void packOptions(const dhcp::OptionBuffer& in_buffer,
const dhcp::Option::OptionCollection& options,
......@@ -111,22 +112,22 @@ private:
/// \brief Reads contents of specified options from buffer.
///
/// The method reads options data from the input buffer
/// and stores it in options objects. Offsets of options
/// must be specified.
/// (see \ref LocalizedOption to find out how to specify
/// option offset).
/// 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).
/// This private method is called by \ref PktTransform::unpack.
///
/// \note This method iterates through all options in
/// options collection, checks offset of the option
/// \note This method iterates through all options in an
/// options collection, checks the offset of the option
/// in input buffer and reads data from the buffer to
/// update option's buffer. If provided options collection
/// is empty, call to this function will have no effect.
/// update the option's buffer. If the provided options collection
/// is empty, a call to this method will have no effect.
///
/// \param universe universe used, V4 or V6
/// \param in_buffer input buffer to be parsed.
/// \param options oprions collection with their offsets
/// in input buffer specified.
///
/// \throw isc::Unexpected if options unpack failed.
static void unpackOptions(const dhcp::OptionBuffer& in_buffer,
const dhcp::Option::OptionCollection& options);
......
......@@ -35,16 +35,16 @@ typedef PerfPkt4::LocalizedOptionPtr LocalizedOptionPtr;
namespace {
// a dummy MAC address, padded with 0s
// A dummy MAC address, padded with 0s
const uint8_t dummyChaddr[16] = {0, 1, 2, 3, 4, 5, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0 };
// let's use some creative test content here (128 chars + \0)
// Let's use some creative test content here (128 chars + \0)
const uint8_t dummyFile[] = "Lorem ipsum dolor sit amet, consectetur "
"adipiscing elit. Proin mollis placerat metus, at "
"lacinia orci ornare vitae. Mauris amet.";
// yet another type of test content (64 chars + \0)
// Yet another type of test content (64 chars + \0)
const uint8_t dummySname[] = "Lorem ipsum dolor sit amet, consectetur "
"adipiscing elit posuere.";
......@@ -88,8 +88,7 @@ public:
// If this is a first call to this function. Initialize
// remaining data.
if (buf.size() == sizeof(hdr))
{
if (buf.size() == sizeof(hdr)) {
// Append the large header fields.
std::copy(dummyChaddr, dummyChaddr + Pkt4::MAX_CHADDR_LEN,
......@@ -116,7 +115,7 @@ TEST_F(PerfPkt4Test, Constructor) {
// Initialize some dummy payload.
uint8_t data[250];
for (int i = 0; i < 250; i++) {
data[i]=i;
data[i] = i;
}
// Test constructor to be used for incoming messages.
......@@ -251,10 +250,10 @@ TEST_F(PerfPkt4Test, InvalidOptions) {
// It will not match because option is shifted by on byte.
ASSERT_FALSE(pkt1->rawUnpack());
// Crete another packet.
// Create another packet.
boost::scoped_ptr<PerfPkt4> pkt2(new PerfPkt4(&buf[0], buf.size()));
// Create DHO_DHCP_MESSAGE_TYPE option that has wrong offset.
// Create DHO_DHCP_MESSAGE_TYPE option that has the wrong offset.
// With this offset, option goes beyond packet size (268).
LocalizedOptionPtr opt_msg_type(new LocalizedOption(Option::V4,
DHO_DHCP_MESSAGE_TYPE,
......@@ -351,7 +350,7 @@ TEST_F(PerfPkt4Test, UnpackTransactionId) {
in_data.size(),
270));
cout << "Testing unpack of transaction id at invalid offset."
cout << "Testing unpack of transaction id at invalid offset. "
<< "This may produce spurious errors." << endl;
// Unpack is supposed to fail because transaction id is at
......
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