From f8d71687e1904367ba857b987fe477bd2f7a1f9a Mon Sep 17 00:00:00 2001 From: Matias Fontanini Date: Sat, 14 Sep 2013 19:01:05 -0300 Subject: [PATCH] Modified some classes' documentation. --- include/arp.h | 54 +++++++++++++++++------------- include/bootp.h | 7 ++-- include/dhcp.h | 69 +++++++++++++++++++++++++++++---------- include/dhcpv6.h | 1 - include/dns.h | 8 ++++- include/dot1q.h | 37 +++++++++++---------- include/llc.h | 6 +++- include/rsn_information.h | 6 ++-- 8 files changed, 123 insertions(+), 65 deletions(-) diff --git a/include/arp.h b/include/arp.h index 904b183..5271b12 100644 --- a/include/arp.h +++ b/include/arp.h @@ -71,10 +71,18 @@ namespace Tins { }; /** - * \brief Default constructor for ARP PDU objects. - * + * \brief Constructs an ARP object using the provided addresses. + * * ARP requests and replies can be constructed easily using - * ARP::make_arp_request/reply static functions. + * ARP::make_arp_request/reply static member functions. + * + * \sa ARP::make_arp_request + * \sa ARP::make_arp_reply + * + * \param target_ip The target IP address. + * \param sender_ip The sender IP address. + * \param target_hw The target hardware address. + * \param sender_hw The sender hardware address. */ ARP(ipaddress_type target_ip = ipaddress_type(), ipaddress_type sender_ip = ipaddress_type(), @@ -125,41 +133,42 @@ namespace Tins { ipaddress_type target_ip_addr() const { return ipaddress_type(_arp.ar_tip); } /** - * \brief Getter for the hardware address format. + * \brief Getter for the hardware address format field. * * \return The hardware address format. */ uint16_t hw_addr_format() const { return Endian::be_to_host(_arp.ar_hrd); } /** - * \brief Getter for the protocol address format. + * \brief Getter for the protocol address format field. * * \return The protocol address format. */ uint16_t prot_addr_format() const { return Endian::be_to_host(_arp.ar_pro); } /** - * \brief Getter for the hardware address length. + * \brief Getter for the hardware address length field. * * \return The hardware address length. */ uint8_t hw_addr_length() const { return _arp.ar_hln; } /** - * \brief Getter for the protocol address length. + * \brief Getter for the protocol address length field. * * \return The protocol address length. */ uint8_t prot_addr_length() const { return _arp.ar_pln; } /** - * \brief Getter for the ARP opcode. + * \brief Getter for the ARP opcode field. * * \return The ARP opcode. */ uint16_t opcode() const { return Endian::be_to_host(_arp.ar_op); } - /** \brief Getter for the header size. + /** + * \brief Getter for the header size. * \return Returns the ARP header size. * \sa PDU::header_size */ @@ -195,35 +204,35 @@ namespace Tins { void target_ip_addr(ipaddress_type new_tgt_ip_addr); /** - * \brief Setter for the hardware address format. + * \brief Setter for the hardware address format field. * * \param new_hw_addr_fmt The new hardware address format. */ void hw_addr_format(uint16_t new_hw_addr_fmt); /** - * \brief Setter for the protocol address format. + * \brief Setter for the protocol address format field. * * \param new_prot_addr_fmt The new protocol address format. */ void prot_addr_format(uint16_t new_prot_addr_fmt); /** - * \brief Setter for the hardware address length. + * \brief Setter for the hardware address length field. * * \param new_hw_addr_len The new hardware address length. */ void hw_addr_length(uint8_t new_hw_addr_len); /** - * \brief Setter for the protocol address length. + * \brief Setter for the protocol address length field. * * \param new_prot_addr_len The new protocol address length. */ void prot_addr_length(uint8_t new_prot_addr_len); /** - * \brief Setter for the ARP opcode. + * \brief Setter for the ARP opcode field. * * \param new_opcode Flag enum value of the ARP opcode to set. */ @@ -233,18 +242,18 @@ namespace Tins { * \brief Getter for the PDU's type. * \sa PDU::pdu_type */ - PDUType pdu_type() const { return PDU::ARP; } + PDUType pdu_type() const { return pdu_flag; } /** * \brief Creates an ARP Request within an EthernetII PDU. * - * Creates an ARP Request PDU and embeds it within a Layer 2 PDU ready to be - * sent. + * Creates an ARP Request PDU and embeds it inside an EthernetII + * PDU. * * \param target The target's IP address. * \param sender The sender's IP address. * \param hw_snd The sender's hardware address. - * \return Returns a EthernetII containing the ARP Request. + * \return EthernetII object containing the ARP Request. */ static EthernetII make_arp_request(ipaddress_type target, ipaddress_type sender, const hwaddress_type &hw_snd = hwaddress_type()); @@ -252,20 +261,21 @@ namespace Tins { /** * \brief Creates an ARP Reply within an EthernetII PDU. * - * Creates an ARP Reply PDU and embeds it within a Layer 2 PDU ready to be - * sent. + * Creates an ARP Reply PDU and embeds it inside an EthernetII + * PDU. * * \param target The target's IP address. * \param sender The sender's IP address. * \param hw_tgt The target's hardware address. * \param hw_snd The sender's hardware address. - * \return Returns an EthetnetII containing the ARP Replay. + * \return EthetnetII containing the ARP Replay. */ static EthernetII make_arp_reply(ipaddress_type target, ipaddress_type sender, const hwaddress_type &hw_tgt = hwaddress_type(), const hwaddress_type &hw_snd = hwaddress_type()); - /** \brief Check wether ptr points to a valid response for this PDU. + /** + * \brief Check wether ptr points to a valid response for this PDU. * * \sa PDU::matches_response * \param ptr The pointer to the buffer. diff --git a/include/bootp.h b/include/bootp.h index 9f7bd9f..02c2402 100644 --- a/include/bootp.h +++ b/include/bootp.h @@ -275,7 +275,8 @@ namespace Tins { _bootp.chaddr ); // Fill what's left with zeros - std::fill(end, _bootp.chaddr + chaddr_type::address_size, 0); + if(end < _bootp.chaddr + chaddr_type::address_size) + std::fill(end, _bootp.chaddr + chaddr_type::address_size, 0); } /** @@ -299,7 +300,7 @@ namespace Tins { /** * \brief Check wether ptr points to a valid response for this PDU. * - * This returns true, if the xid field is equal. + * This returns true if the xid field is equal. * * \sa PDU::matches_response * \param ptr The pointer to the buffer. @@ -311,7 +312,7 @@ namespace Tins { * \brief Getter for the PDU's type. * \sa PDU::pdu_type */ - PDUType pdu_type() const { return PDU::BOOTP; } + PDUType pdu_type() const { return pdu_flag; } /** * \sa PDU::clone diff --git a/include/dhcp.h b/include/dhcp.h index 0a70175..3813d78 100644 --- a/include/dhcp.h +++ b/include/dhcp.h @@ -162,12 +162,11 @@ namespace Tins { * \brief Constructs a DHCP object from a buffer. * * If there is not enough size for a BootP header, or any of - * the TLV options contain an invalid size field, then a + * the TLV options contains an invalid size field, then a * malformed_packet exception is thrown. * * \param buffer The buffer from which this PDU will be constructed. * \param total_sz The total size of the buffer. - * Subclasses might use 0 to provide their own interpretation of this field. */ DHCP(const uint8_t *buffer, uint32_t total_sz); @@ -199,13 +198,18 @@ namespace Tins { const option *search_option(OptionTypes opt) const; /** - * \brief Adds a type option the the option list. + * \brief Adds a type option to the option list. + * + * The new option is appended at the end of the list. + * * \param type The type of this DHCP PDU. */ void type(Flags type); /** - * \brief Adds an end option the the option list. + * \brief Adds an end option to the option list. + * + * The new option is appended at the end of the list. * * The END option is not added automatically. You should explicitly * add it at the end of the DHCP options for the PDU to be @@ -215,60 +219,90 @@ namespace Tins { /** * \brief Adds a server identifier option. + * + * The new option is appended at the end of the list. + * * \param ip The ip of the server. */ void server_identifier(ipaddress_type ip); /** * \brief Adds an IP address lease time option. + * + * The new option is appended at the end of the list. + * * \param time The lease time. */ void lease_time(uint32_t time); /** * \brief Adds a lease renewal time option. + * + * The new option is appended at the end of the list. + * * \param time The lease renew time. */ void renewal_time(uint32_t time); /** * \brief Adds a rebind time option. + * + * The new option is appended at the end of the list. + * * \param time The lease rebind time. */ void rebind_time(uint32_t time); /** * \brief Adds a subnet mask option. + * + * The new option is appended at the end of the list. + * * \param mask The subnet mask. */ void subnet_mask(ipaddress_type mask); /** * \brief Adds a routers option. + * + * The new option is appended at the end of the list. + * * \param routers A list of ip addresses. */ void routers(const std::list &routers); /** * \brief Adds a domain name servers option. + * + * The new option is appended at the end of the list. + * * \param dns A list of ip addresses. */ void domain_name_servers(const std::list &dns); /** * \brief Adds a broadcast address option. + * + * The new option is appended at the end of the list. + * * \param addr The broadcast address. */ void broadcast(ipaddress_type addr); /** * \brief Adds a requested address option. + * + * The new option is appended at the end of the list. + * * \param addr The requested address. */ void requested_ip(ipaddress_type addr); /** * \brief Adds a domain name option. + * + * The new option is appended at the end of the list. + * * \param name The domain name. */ void domain_name(const std::string &name); @@ -278,7 +312,7 @@ namespace Tins { /** * \brief Searchs for a type option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return uint8_t containing the type option. @@ -288,7 +322,7 @@ namespace Tins { /** * \brief Searchs for a server identifier option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return ipaddress_type Containing the server identifier. @@ -298,7 +332,7 @@ namespace Tins { /** * \brief Searchs for a lease time option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return uint32_t Containing the lease time. @@ -308,7 +342,7 @@ namespace Tins { /** * \brief Searchs for a lease renewal time option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return uint32_t Containing the renewal time. @@ -318,7 +352,7 @@ namespace Tins { /** * \brief Searchs for a rebind time option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return uint32_t Containing the rebind time. @@ -328,7 +362,7 @@ namespace Tins { /** * \brief Searchs for a subnet mask option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return ipaddress_type Containing the subnet mask. @@ -338,7 +372,7 @@ namespace Tins { /** * \brief Searchs for a routers option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return std::list Containing the routers @@ -349,7 +383,7 @@ namespace Tins { /** * \brief Searchs for a dns option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return std::list Contanining the DNS servers @@ -360,7 +394,7 @@ namespace Tins { /** * \brief Searchs for a broadcast option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return ipaddress_type Containing the broadcast address. @@ -370,7 +404,7 @@ namespace Tins { /** * \brief Searchs for a requested option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return ipaddress_type Containing the requested IP address. @@ -380,14 +414,15 @@ namespace Tins { /** * \brief Searchs for a domain name option. * - * If the option is not found, a option_not_found exception + * If the option is not found, an option_not_found exception * is thrown. * * \return std::string Containing the domain name. */ std::string domain_name() const; - /** \brief Getter for the options list. + /** + * \brief Getter for the options list. * \return The option list. */ const options_type options() const { return _options; } @@ -396,7 +431,7 @@ namespace Tins { * \brief Getter for the PDU's type. * \sa PDU::pdu_type */ - PDUType pdu_type() const { return PDU::DHCP; } + PDUType pdu_type() const { return pdu_flag; } /** * \brief Getter for the header size. diff --git a/include/dhcpv6.h b/include/dhcpv6.h index 01fa34b..4d10822 100644 --- a/include/dhcpv6.h +++ b/include/dhcpv6.h @@ -442,7 +442,6 @@ public: * \return The stored options. */ const options_type &options() const { return options_; } - ; // Setters /** diff --git a/include/dns.h b/include/dns.h index 76bd07d..9932593 100644 --- a/include/dns.h +++ b/include/dns.h @@ -558,6 +558,9 @@ namespace Tins { /** * \brief Getter for this PDU's DNS queries. + * + * This method is not thread safe. + * * \return std::list containing the queries in this * record. */ @@ -565,6 +568,9 @@ namespace Tins { /** * \brief Getter for this PDU's DNS answers + * + * This method is not thread safe. + * * \return std::list containing the answers in this * record. */ @@ -587,7 +593,7 @@ namespace Tins { } /** - * Helper function to create a resource record information + * Helper function to create a resource record information. * * \param type The type of the query. * \param qclass The class of the query. diff --git a/include/dot1q.h b/include/dot1q.h index 5019975..e3c3e96 100644 --- a/include/dot1q.h +++ b/include/dot1q.h @@ -35,6 +35,9 @@ #include "small_uint.h" namespace Tins { +/** + * Represents an IEEE 802.1q PDU. + */ class Dot1Q : public PDU { public: /** @@ -78,24 +81,24 @@ public: uint32_t trailer_size() const; /** - * \brief Getter for the priority field. - * \return The stored priority field value. + * \brief Getter for the priority field. + * \return The stored priority field value. */ small_uint<3> priority() const { return _header.priority; } /** - * \brief Getter for the cfi field. - * \return The stored cfi field value. + * \brief Getter for the Canonical Format Identifier field. + * \return The stored CFI field value. */ small_uint<1> cfi() const { return _header.cfi; } /** - * \brief Getter for the id field. - * \return The stored id field value. + * \brief Getter for the VLAN ID field. + * \return The stored VLAN ID field value. */ small_uint<12> id() const { #if TINS_IS_LITTLE_ENDIAN @@ -106,8 +109,8 @@ public: } /** - * \brief Getter for the payload type field. - * \return The stored type field value. + * \brief Getter for the payload type field. + * \return The stored type field value. */ uint16_t payload_type() const { return Endian::be_to_host(_header.type); @@ -137,31 +140,31 @@ public: // Setters /** - * \brief Setter for the priority field. - * \param new_priority The new priority field value. + * \brief Setter for the priority field. + * \param new_priority The new priority field value. */ void priority(small_uint<3> new_priority); /** - * \brief Setter for the cfi field. - * \param new_cfi The new cfi field value. + * \brief Setter for the Canonical Format Identifie field. + * \param new_cfi The new CFI field value. */ void cfi(small_uint<1> new_cfi); /** - * \brief Setter for the id field. - * \param new_id The new id field value. + * \brief Setter for the VLAN ID field. + * \param new_id The new VLAN ID field value. */ void id(small_uint<12> new_id); /** - * \brief Setter for the payload type field. - * \param new_type The new type field value. + * \brief Setter for the payload type field. + * \param new_type The new type field value. */ void payload_type(uint16_t new_type); /** - * \brief Indicates whether the appropriate padding will be + * \brief Indicates whether the appropriate padding will be * at the end of the packet. * * This flag could be disabled in case two or more contiguous Dot1Q diff --git a/include/llc.h b/include/llc.h index 815f374..37fdc13 100644 --- a/include/llc.h +++ b/include/llc.h @@ -55,6 +55,10 @@ namespace Tins { * \brief Represents the LLC global DSAP address. */ static const uint8_t GLOBAL_DSAP_ADDR; + + /** + * \brief Represents the LLC NULL address. + */ static const uint8_t NULL_ADDR; /** @@ -302,7 +306,7 @@ namespace Tins { * \brief Getter for the PDU's type. * \sa PDU::pdu_type */ - PDUType pdu_type() const { return PDU::LLC; } + PDUType pdu_type() const { return pdu_flag; } /** * \brief Delete all the information fields added. diff --git a/include/rsn_information.h b/include/rsn_information.h index 1facc1e..db7f9d4 100644 --- a/include/rsn_information.h +++ b/include/rsn_information.h @@ -74,14 +74,14 @@ namespace Tins{ typedef std::vector serialization_type; /** - * \brief Creates an instance of RSNInformation. + * \brief Constructs an RSNInformation object. * * By default, the version is set to 1. */ RSNInformation(); /** - * \brief Creates an instance of RSNInformation from a + * \brief Constructs an RSNInformation object from a * serialization_type object. * * \param buffer The buffer from which to construct this object. @@ -113,7 +113,7 @@ namespace Tins{ void add_pairwise_cypher(CypherSuites cypher); /** - * \brief Adds a akm suite. + * \brief Adds an akm suite. * \param akm The akm suite to be added. */ void add_akm_cypher(AKMSuites akm);