From f81ced259b2aea3cfc4a779c4ec1678a0aa1a0b7 Mon Sep 17 00:00:00 2001 From: Dimitar Krastev Date: Tue, 10 Dec 2024 18:11:30 +0200 Subject: [PATCH] Reformat Common++ documentation to use triple slash. (#1647) * Reformatted Common++ to use triple slash /// instead of /** for documentation. * Fixed potentially undefined `size_t`. * Fixed string include. * Reverted std::size_t to size_t. --- Common++/header/GeneralUtils.h | 80 ++- Common++/header/IpAddress.h | 804 ++++++++++---------------- Common++/header/IpAddressUtils.h | 114 ++-- Common++/header/IpUtils.h | 99 ++-- Common++/header/LRUList.h | 75 +-- Common++/header/Logger.h | 146 ++--- Common++/header/MacAddress.h | 128 ++-- Common++/header/OUILookup.h | 50 +- Common++/header/PcapPlusPlusVersion.h | 38 +- Common++/header/PointerVector.h | 245 +++----- Common++/header/SystemUtils.h | 343 ++++------- Common++/header/TablePrinter.h | 64 +- Common++/src/SystemUtils.cpp | 7 +- 13 files changed, 803 insertions(+), 1390 deletions(-) diff --git a/Common++/header/GeneralUtils.h b/Common++/header/GeneralUtils.h index acb4d93589..316ee22913 100644 --- a/Common++/header/GeneralUtils.h +++ b/Common++/header/GeneralUtils.h @@ -6,56 +6,46 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * Convert a byte array into a string of hex characters. For example: for the array { 0xaa, 0x2b, 0x10 } the string - * "aa2b10" will be returned - * @param[in] byteArr A byte array - * @param[in] byteArrSize The size of the byte array [in bytes] - * @param[in] stringSizeLimit An optional parameter that enables to limit the returned string size. If set to a - * positive integer value the returned string size will be equal or less than this value. If the string - * representation of the whole array is longer than this size then only part of the array will be read. The default - * value is -1 which means no string size limitation - * @return A string of hex characters representing the byte array - */ + /// Convert a byte array into a string of hex characters. For example: for the array { 0xaa, 0x2b, 0x10 } the string + /// "aa2b10" will be returned + /// @param[in] byteArr A byte array + /// @param[in] byteArrSize The size of the byte array [in bytes] + /// @param[in] stringSizeLimit An optional parameter that enables to limit the returned string size. If set to a + /// positive integer value the returned string size will be equal or less than this value. If the string + /// representation of the whole array is longer than this size then only part of the array will be read. The default + /// value is -1 which means no string size limitation + /// @return A string of hex characters representing the byte array std::string byteArrayToHexString(const uint8_t* byteArr, size_t byteArrSize, int stringSizeLimit = -1); - /** - * Convert a string of hex characters into a byte array. For example: for the string "aa2b10" an array of values - * { 0xaa, 0x2b, 0x10 } will be returned - * @param[in] hexString A string of hex characters - * @param[out] resultByteArr A pre-allocated byte array where the result will be written to - * @param[in] resultByteArrSize The size of the pre-allocated byte array - * @return The size of the result array. If the string represents an array that is longer than the pre-allocated - * size (resultByteArrSize) then the result array will contain only the part of the string that managed to fit into - * the array, and the returned size will be resultByteArrSize. However if the string represents an array that is - * shorter than the pre-allocated size then some of the cells will remain empty and contain zeros, and the returned - * size will be the part of the array that contain data. If the input is an illegal hex string 0 will be returned. - * Illegal hex string means odd number of characters or a string that contains non-hex characters - */ + /// Convert a string of hex characters into a byte array. For example: for the string "aa2b10" an array of values + /// { 0xaa, 0x2b, 0x10 } will be returned + /// @param[in] hexString A string of hex characters + /// @param[out] resultByteArr A pre-allocated byte array where the result will be written to + /// @param[in] resultByteArrSize The size of the pre-allocated byte array + /// @return The size of the result array. If the string represents an array that is longer than the pre-allocated + /// size (resultByteArrSize) then the result array will contain only the part of the string that managed to fit into + /// the array, and the returned size will be resultByteArrSize. However if the string represents an array that is + /// shorter than the pre-allocated size then some of the cells will remain empty and contain zeros, and the returned + /// size will be the part of the array that contain data. If the input is an illegal hex string 0 will be returned. + /// Illegal hex string means odd number of characters or a string that contains non-hex characters size_t hexStringToByteArray(const std::string& hexString, uint8_t* resultByteArr, size_t resultByteArrSize); - /** - * This is a cross platform version of memmem (https://man7.org/linux/man-pages/man3/memmem.3.html) which is not - * supported on all platforms. - * @param[in] haystack A pointer to the buffer to be searched - * @param[in] haystackLen Length of the haystack buffer - * @param[in] needle A pointer to a buffer that will be searched for - * @param[in] needleLen Length of the needle buffer - * @return A pointer to the beginning of the substring, or nullptr if the substring is not found - */ + /// This is a cross platform version of memmem (https://man7.org/linux/man-pages/man3/memmem.3.html) which is not + /// supported on all platforms. + /// @param[in] haystack A pointer to the buffer to be searched + /// @param[in] haystackLen Length of the haystack buffer + /// @param[in] needle A pointer to a buffer that will be searched for + /// @param[in] needleLen Length of the needle buffer + /// @return A pointer to the beginning of the substring, or nullptr if the substring is not found char* cross_platform_memmem(const char* haystack, size_t haystackLen, const char* needle, size_t needleLen); - /** - * Calculates alignment. - * @param[in] number Given number - * @return The aligned number - */ + /// Calculates alignment. + /// @param[in] number Given number + /// @return The aligned number template static int align(int number) { // Only works for alignment with power of 2 @@ -65,10 +55,8 @@ namespace pcpp return (number + mask) & ~mask; } - /** - * A template class to calculate enum class hash - * @tparam EnumClass - */ + /// A template class to calculate enum class hash + /// @tparam EnumClass template ::value, bool>::type = false> struct EnumClassHash { diff --git a/Common++/header/IpAddress.h b/Common++/header/IpAddress.h index a156e8aace..6cafb2ed7d 100644 --- a/Common++/header/IpAddress.h +++ b/Common++/header/IpAddress.h @@ -10,10 +10,8 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { @@ -24,97 +22,70 @@ namespace pcpp // The implementation of the classes is based on document N4771 "Working Draft, C++ Extensions for Networking" // http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/n4771.pdf - /** - * @class IPv4Address - * Represents an IPv4 address (of type XXX.XXX.XXX.XXX) - */ + /// @class IPv4Address + /// Represents an IPv4 address (of type XXX.XXX.XXX.XXX) class IPv4Address { public: - /** - * A default constructor that creates an instance of the class with the zero-initialized address - */ + /// A default constructor that creates an instance of the class with the zero-initialized address IPv4Address() = default; - /** - * A constructor that creates an instance of the class out of 4-byte integer value. - * @param[in] addrAsInt The address as 4-byte integer in network byte order - */ + /// A constructor that creates an instance of the class out of 4-byte integer value. + /// @param[in] addrAsInt The address as 4-byte integer in network byte order IPv4Address(const uint32_t addrAsInt) { memcpy(m_Bytes.data(), &addrAsInt, sizeof(addrAsInt)); } - /** - * A constructor that creates an instance of the class out of 4-byte array. - * @param[in] bytes The address as 4-byte array in network byte order - */ + /// A constructor that creates an instance of the class out of 4-byte array. + /// @param[in] bytes The address as 4-byte array in network byte order IPv4Address(const uint8_t bytes[4]) { memcpy(m_Bytes.data(), bytes, 4 * sizeof(uint8_t)); } - /** - * A constructor that creates an instance of the class out of a 4-byte standard array. - * @param[in] bytes The address as 4-byte standard array in network byte order - */ + /// A constructor that creates an instance of the class out of a 4-byte standard array. + /// @param[in] bytes The address as 4-byte standard array in network byte order IPv4Address(const std::array& bytes) : m_Bytes(bytes) {} - /** - * A constructor that creates an instance of the class out of std::string value. - * - * @param[in] addrAsString The std::string representation of the address - * @throws std::invalid_argument The provided string does not represent a valid IPv4 address. - */ + /// A constructor that creates an instance of the class out of std::string value. + /// @param[in] addrAsString The std::string representation of the address + /// @throws std::invalid_argument The provided string does not represent a valid IPv4 address. IPv4Address(const std::string& addrAsString); - /** - * @return A 4-byte integer in network byte order representing the IPv4 address - */ + /// @return A 4-byte integer in network byte order representing the IPv4 address inline uint32_t toInt() const; - /** - * @return A non-owning pointer to 4-byte C-style array representing the IPv4 address - */ + /// @return A non-owning pointer to 4-byte C-style array representing the IPv4 address const uint8_t* toBytes() const { return m_Bytes.data(); } - /** - * @return A reference to a 4-byte standard array representing the IPv4 address - */ + /// @return A reference to a 4-byte standard array representing the IPv4 address const std::array& toByteArray() const { return m_Bytes; } - /** - * @return A string representation of the address - */ + /// @return A string representation of the address std::string toString() const; - /** - * @return True if an address is multicast, false otherwise. - */ + /// @return True if an address is multicast, false otherwise. bool isMulticast() const; - /** - * Overload of the equal-to operator - * @param[in] rhs The object to compare with - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @param[in] rhs The object to compare with + /// @return True if the addresses are equal, false otherwise bool operator==(const IPv4Address& rhs) const { return toInt() == rhs.toInt(); } - /** - * Overload of the less-than operator - * @param[in] rhs The object to compare with - * @return True if the address value is lower than the other address value, false otherwise - */ + /// Overload of the less-than operator + /// @param[in] rhs The object to compare with + /// @return True if the address value is lower than the other address value, false otherwise bool operator<(const IPv4Address& rhs) const { uint32_t intVal = toInt(); @@ -127,54 +98,42 @@ namespace pcpp return intVal < rhsIntVal; } - /** - * Overload of the not-equal-to operator - * @param[in] rhs The object to compare with - * @return True if the addresses are not equal, false otherwise - */ + /// Overload of the not-equal-to operator + /// @param[in] rhs The object to compare with + /// @return True if the addresses are not equal, false otherwise bool operator!=(const IPv4Address& rhs) const { return !(*this == rhs); } - /** - * Checks whether the address matches a network. - * @param network An IPv4Network network - * @return True if the address matches the network or false otherwise - */ + /// Checks whether the address matches a network. + /// @param network An IPv4Network network + /// @return True if the address matches the network or false otherwise bool matchNetwork(const IPv4Network& network) const; - /** - * Checks whether the address matches a network. - * For example: this method will return true for address 10.1.1.9 and network which is one of: - * 10.1.1.1/24, 10.1.1.1/255.255.255.0 - * Another example: this method will return false for address 11.1.1.9 and network which is one of: - * 10.1.1.1/16, 10.1.1.1/255.255.0.0 - * @param[in] network A string in one of these formats: - * - X.X.X.X/Y where X.X.X.X is a valid IP address and Y is a number between 0 and 32 - * - X.X.X.X/Y.Y.Y.Y where X.X.X.X is a valid IP address and Y.Y.Y.Y is a valid netmask - * @return True if the address matches the network or false if it doesn't or if the network is invalid - */ + /// Checks whether the address matches a network. + /// For example: this method will return true for address 10.1.1.9 and network which is one of: + /// 10.1.1.1/24, 10.1.1.1/255.255.255.0 + /// Another example: this method will return false for address 11.1.1.9 and network which is one of: + /// 10.1.1.1/16, 10.1.1.1/255.255.0.0 + /// @param[in] network A string in one of these formats: + /// - X.X.X.X/Y where X.X.X.X is a valid IP address and Y is a number between 0 and 32 + /// - X.X.X.X/Y.Y.Y.Y where X.X.X.X is a valid IP address and Y.Y.Y.Y is a valid netmask + /// @return True if the address matches the network or false if it doesn't or if the network is invalid bool matchNetwork(const std::string& network) const; - /** - * A static method that checks whether a string represents a valid IPv4 address - * @param[in] addrAsString The std::string representation of the address - * @return True if the address is valid, false otherwise - */ + /// A static method that checks whether a string represents a valid IPv4 address + /// @param[in] addrAsString The std::string representation of the address + /// @return True if the address is valid, false otherwise static bool isValidIPv4Address(const std::string& addrAsString); - /** - * A static value representing a zero value of IPv4 address, meaning address of value "0.0.0.0". - */ + /// A static value representing a zero value of IPv4 address, meaning address of value "0.0.0.0". static const IPv4Address Zero; - /** - * A static values representing the lower and upper bound of IPv4 multicast ranges. The bounds are inclusive. - * MulticastRangeLowerBound is initialized to "224.0.0.0". - * MulticastRangeUpperBound is initialized to "239.255.255.255". - * In order to check whether the address is a multicast address the isMulticast method can be used. - */ + /// A static values representing the lower and upper bound of IPv4 multicast ranges. The bounds are inclusive. + /// MulticastRangeLowerBound is initialized to "224.0.0.0". + /// MulticastRangeUpperBound is initialized to "239.255.255.255". + /// In order to check whether the address is a multicast address the isMulticast method can be used. static const IPv4Address MulticastRangeLowerBound; static const IPv4Address MulticastRangeUpperBound; @@ -191,317 +150,235 @@ namespace pcpp return addr; } - /** - * @class IPv6Address - * Represents an IPv6 address (of type xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx). - */ + /// @class IPv6Address + /// Represents an IPv6 address (of type xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx). class IPv6Address { public: - /** - * A default constructor that creates an instance of the class with the zero-initialized address. - */ + /// A default constructor that creates an instance of the class with the zero-initialized address. IPv6Address() = default; - /** - * A constructor that creates an instance of the class out of 16-byte array. - * @param[in] bytes The address as 16-byte array in network byte order - */ + /// A constructor that creates an instance of the class out of 16-byte array. + /// @param[in] bytes The address as 16-byte array in network byte order IPv6Address(const uint8_t bytes[16]) { memcpy(m_Bytes.data(), bytes, 16 * sizeof(uint8_t)); } - /** - * A constructor that creates an instance of the class out of a 16-byte standard array. - * @param[in] bytes The address as 16-byte standard array in network byte order - */ + /// A constructor that creates an instance of the class out of a 16-byte standard array. + /// @param[in] bytes The address as 16-byte standard array in network byte order IPv6Address(const std::array& bytes) : m_Bytes(bytes) {} - /** - * A constructor that creates an instance of the class out of std::string value. - * - * @param[in] addrAsString The std::string representation of the address - * @throws std::invalid_argument The provided string does not represent a valid IPv6 address. - */ + /// A constructor that creates an instance of the class out of std::string value. + /// @param[in] addrAsString The std::string representation of the address + /// @throws std::invalid_argument The provided string does not represent a valid IPv6 address. IPv6Address(const std::string& addrAsString); - /** - * Returns a view of the IPv6 address as a 16-byte raw C-style array - * @return A non-owning pointer to 16-byte array representing the IPv6 address - */ + /// Returns a view of the IPv6 address as a 16-byte raw C-style array + /// @return A non-owning pointer to 16-byte array representing the IPv6 address const uint8_t* toBytes() const { return m_Bytes.data(); } - /** - * Returns a view of the IPv6 address as a std::array of bytes - * @return A reference to a 16-byte standard array representing the IPv6 address - */ + /// Returns a view of the IPv6 address as a std::array of bytes + /// @return A reference to a 16-byte standard array representing the IPv6 address const std::array& toByteArray() const { return m_Bytes; } - /** - * Returns a std::string representation of the address - * @return A string representation of the address - */ + /// Returns a std::string representation of the address + /// @return A string representation of the address std::string toString() const; - /** - * Determine whether the address is a multicast address - * @return True if an address is multicast - */ + /// Determine whether the address is a multicast address + /// @return True if an address is multicast bool isMulticast() const; - /** - * Overload of the equal-to operator - * @param[in] rhs The object to compare with - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @param[in] rhs The object to compare with + /// @return True if the addresses are equal, false otherwise bool operator==(const IPv6Address& rhs) const { return memcmp(toBytes(), rhs.toBytes(), sizeof(m_Bytes)) == 0; } - /** - * Overload of the less-than operator - * @param[in] rhs The object to compare with - * @return True if the address value is lower than the other address value, false otherwise - */ + /// Overload of the less-than operator + /// @param[in] rhs The object to compare with + /// @return True if the address value is lower than the other address value, false otherwise bool operator<(const IPv6Address& rhs) const { return memcmp(toBytes(), rhs.toBytes(), sizeof(m_Bytes)) < 0; } - /** - * Overload of the not-equal-to operator - * @param[in] rhs The object to compare with - * @return True if the addresses are not equal, false otherwise - */ + /// Overload of the not-equal-to operator + /// @param[in] rhs The object to compare with + /// @return True if the addresses are not equal, false otherwise bool operator!=(const IPv6Address& rhs) const { return !(*this == rhs); } - /** - * Allocates a byte array and copies address value into it. Array deallocation is user responsibility - * @param[in] arr A pointer to where array will be allocated - * @param[out] length Returns the length in bytes of the array that was allocated - */ + /// Allocates a byte array and copies address value into it. Array deallocation is user responsibility + /// @param[in] arr A pointer to where array will be allocated + /// @param[out] length Returns the length in bytes of the array that was allocated void copyTo(uint8_t** arr, size_t& length) const; - /** - * Gets a pointer to an already allocated byte array and copies the address value to it. - * This method assumes array allocated size is at least 16 (the size of an IPv6 address) - * @param[in] arr A pointer to the array which address will be copied to - */ + /// Gets a pointer to an already allocated byte array and copies the address value to it. + /// This method assumes array allocated size is at least 16 (the size of an IPv6 address) + /// @param[in] arr A pointer to the array which address will be copied to void copyTo(uint8_t* arr) const { memcpy(arr, m_Bytes.data(), m_Bytes.size() * sizeof(uint8_t)); } - /** - * Checks whether the address matches a network. - * @param network An IPv6Network network - * @return True if the address matches the network or false otherwise - */ + /// Checks whether the address matches a network. + /// @param network An IPv6Network network + /// @return True if the address matches the network or false otherwise bool matchNetwork(const IPv6Network& network) const; - /** - * Checks whether the address matches a network. - * For example: this method will return true for address d6e5:83dc:0c58:bc5d:1449:5898:: and network - * which is one of: - * d6e5:83dc:0c58:bc5d::/64, d6e5:83dc:0c58:bc5d::/ffff:ffff:ffff:ffff:: - * Another example: this method will return false for address d6e5:83dc:: and network which is one of: - * d6e5:83dc:0c58:bc5d::/64, d6e5:83dc:0c58:bc5d::/ffff:ffff:ffff:ffff:: - * @param[in] network A string in one of these formats: - * - IPV6_ADDRESS/Y where IPV6_ADDRESS is a valid IPv6 address and Y is a number between 0 and 128 - * - IPV6_ADDRESS/IPV6_NETMASK where IPV6_ADDRESS is a valid IPv6 address and IPV6_NETMASK is a valid - * IPv6 netmask - * @return True if the address matches the network or false if it doesn't or if the network is invalid - */ + /// Checks whether the address matches a network. + /// For example: this method will return true for address d6e5:83dc:0c58:bc5d:1449:5898:: and network + /// which is one of: + /// d6e5:83dc:0c58:bc5d::/64, d6e5:83dc:0c58:bc5d::/ffff:ffff:ffff:ffff:: + /// Another example: this method will return false for address d6e5:83dc:: and network which is one of: + /// d6e5:83dc:0c58:bc5d::/64, d6e5:83dc:0c58:bc5d::/ffff:ffff:ffff:ffff:: + /// @param[in] network A string in one of these formats: + /// - IPV6_ADDRESS/Y where IPV6_ADDRESS is a valid IPv6 address and Y is a number between 0 and 128 + /// - IPV6_ADDRESS/IPV6_NETMASK where IPV6_ADDRESS is a valid IPv6 address and IPV6_NETMASK is a valid + /// IPv6 netmask + /// @return True if the address matches the network or false if it doesn't or if the network is invalid bool matchNetwork(const std::string& network) const; - /** - * A static method that checks whether a string represents a valid IPv6 address - * @param[in] addrAsString The std::string representation of the address - * @return True if the address is valid, false otherwise - */ + /// A static method that checks whether a string represents a valid IPv6 address + /// @param[in] addrAsString The std::string representation of the address + /// @return True if the address is valid, false otherwise static bool isValidIPv6Address(const std::string& addrAsString); - /** - * A static value representing a zero value of IPv6 address, meaning address of value - * "0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0". - */ + /// A static value representing a zero value of IPv6 address, meaning address of value + /// "0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0". static const IPv6Address Zero; - /** - * A static value representing the lower bound of IPv6 multicast ranges. The bound is inclusive. - * MulticastRangeLowerBound is initialized to "ff00:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0". - * In order to check whether the address is a multicast address the isMulticast method can be used. - */ + /// A static value representing the lower bound of IPv6 multicast ranges. The bound is inclusive. + /// MulticastRangeLowerBound is initialized to "ff00:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0". + /// In order to check whether the address is a multicast address the isMulticast method can be used. static const IPv6Address MulticastRangeLowerBound; private: std::array m_Bytes = { 0 }; }; // class IPv6Address - /** - * @class IPAddress - * The class is a version-independent representation for an IP address - */ + /// @class IPAddress + /// The class is a version-independent representation for an IP address class IPAddress { public: - /** - * An enum representing the address type: IPv4 or IPv6 - */ + /// An enum representing the address type: IPv4 or IPv6 enum AddressType { - /** - * IPv4 address type - */ + /// IPv4 address type IPv4AddressType, - /** - * IPv6 address type - */ + /// IPv6 address type IPv6AddressType }; - /** - * A default constructor that creates an instance of the class with unspecified IPv4 address - */ + /// A default constructor that creates an instance of the class with unspecified IPv4 address IPAddress() : m_Type(IPv4AddressType) {} - /** - * A constructor that creates an instance of the class out of IPv4Address. - * @param[in] addr A const reference to instance of IPv4Address - */ + /// A constructor that creates an instance of the class out of IPv4Address. + /// @param[in] addr A const reference to instance of IPv4Address IPAddress(const IPv4Address& addr) : m_Type(IPv4AddressType), m_IPv4(addr) {} - /** - * A constructor that creates an instance of the class out of IPv6Address. - * @param[in] addr A const reference to instance of IPv6Address - */ + /// A constructor that creates an instance of the class out of IPv6Address. + /// @param[in] addr A const reference to instance of IPv6Address IPAddress(const IPv6Address& addr) : m_Type(IPv6AddressType), m_IPv6(addr) {} - /** - * A constructor that creates an instance of the class out of std::string value - * - * @param[in] addrAsString The std::string representation of the address - * @throws std::invalid_argument The provided string does not represent a valid IPv4 or IPv6 address. - */ + /// A constructor that creates an instance of the class out of std::string value + /// @param[in] addrAsString The std::string representation of the address + /// @throws std::invalid_argument The provided string does not represent a valid IPv4 or IPv6 address. IPAddress(const std::string& addrAsString); - /** - * Overload of an assignment operator. - * @param[in] addr A const reference to instance of IPv4Address - * @return A reference to the assignee - */ + /// Overload of an assignment operator. + /// @param[in] addr A const reference to instance of IPv4Address + /// @return A reference to the assignee inline IPAddress& operator=(const IPv4Address& addr); - /** - * Overload of an assignment operator. - * @param[in] addr A const reference to instance of IPv6Address - * @return A reference to the assignee - */ + /// Overload of an assignment operator. + /// @param[in] addr A const reference to instance of IPv6Address + /// @return A reference to the assignee inline IPAddress& operator=(const IPv6Address& addr); - /** - * Gets the address type: IPv4 or IPv6 - * @return The address type - */ + /// Gets the address type: IPv4 or IPv6 + /// @return The address type AddressType getType() const { return static_cast(m_Type); } - /** - * Returns a std::string representation of the address - * @return A string representation of the address - */ + /// Returns a std::string representation of the address + /// @return A string representation of the address std::string toString() const { return (getType() == IPv4AddressType) ? m_IPv4.toString() : m_IPv6.toString(); } - /** - * @return Determine whether the object contains an IP version 4 address - */ + /// @return Determine whether the object contains an IP version 4 address bool isIPv4() const { return getType() == IPv4AddressType; } - /** - * @return Determine whether the object contains an IP version 6 address - */ + /// @return Determine whether the object contains an IP version 6 address bool isIPv6() const { return getType() == IPv6AddressType; } - /** - * Determine whether the address is a multicast address - * @return True if an address is multicast - */ + /// Determine whether the address is a multicast address + /// @return True if an address is multicast bool isMulticast() const { return (getType() == IPv4AddressType) ? m_IPv4.isMulticast() : m_IPv6.isMulticast(); } - /** - * Get a reference to IPv4 address instance - * @return The const reference to IPv4Address instance - */ + /// Get a reference to IPv4 address instance + /// @return The const reference to IPv4Address instance const IPv4Address& getIPv4() const { return m_IPv4; } - /** - * Get a reference to IPv6 address instance - * @return The const reference to IPv6Address instance - */ + /// Get a reference to IPv6 address instance + /// @return The const reference to IPv6Address instance const IPv6Address& getIPv6() const { return m_IPv6; } - /** - * @return True if the address is zero, false otherwise - */ + /// @return True if the address is zero, false otherwise bool isZero() const { return (getType() == IPv4AddressType) ? m_IPv4 == IPv4Address::Zero : m_IPv6 == IPv6Address::Zero; } - /** - * Overload of the equal-to operator - * @param[in] rhs The object to compare with - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @param[in] rhs The object to compare with + /// @return True if the addresses are equal, false otherwise inline bool operator==(const IPAddress& rhs) const; - /** - * Overload of the less-than operator - * @param[in] rhs The object to compare with - * @return True if the address value is lower than the other address value, false otherwise - */ + /// Overload of the less-than operator + /// @param[in] rhs The object to compare with + /// @return True if the address value is lower than the other address value, false otherwise inline bool operator<(const IPAddress& rhs) const; - /** - * Overload of the not-equal-to operator - * @param[in] rhs The object to compare with - * @return True if the addresses are not equal, false otherwise - */ + /// Overload of the not-equal-to operator + /// @param[in] rhs The object to compare with + /// @return True if the addresses are not equal, false otherwise bool operator!=(const IPAddress& rhs) const { return !(*this == rhs); @@ -548,112 +425,83 @@ namespace pcpp return *this; } - /** - * @class IPv4Network - * A class representing IPv4 network definition - */ + /// @class IPv4Network + /// A class representing IPv4 network definition class IPv4Network { public: - /** - * A constructor that creates an instance of the class out of an address and a full prefix length, - * essentially making a network of consisting of only 1 address. - * - * @param address An address representing the network prefix. - */ + /// A constructor that creates an instance of the class out of an address and a full prefix length, + /// essentially making a network of consisting of only 1 address. + /// @param address An address representing the network prefix. explicit IPv4Network(const IPv4Address& address) : IPv4Network(address, 32u) {} - /** - * A constructor that creates an instance of the class out of an address representing the network prefix - * and a prefix length - * @param address An address representing the network prefix. If the address is invalid std::invalid_argument - * exception is thrown - * @param prefixLen A number between 0 and 32 representing the prefix length. - * @throws std::invalid_argument Prefix length is out of acceptable range. - */ + /// A constructor that creates an instance of the class out of an address representing the network prefix + /// and a prefix length + /// @param address An address representing the network prefix. If the address is invalid std::invalid_argument + /// exception is thrown + /// @param prefixLen A number between 0 and 32 representing the prefix length. + /// @throws std::invalid_argument Prefix length is out of acceptable range. IPv4Network(const IPv4Address& address, uint8_t prefixLen); - /** - * A constructor that creates an instance of the class out of an address representing the network prefix - * and a netmask - * @param address An address representing the network prefix. If the address is invalid std::invalid_argument - * exception is thrown - * @param netmask A string representing a netmask in the format of X.X.X.X, for example: 255.255.0.0. - * Please notice that netmasks that start with zeros are invalid, for example: 0.0.255.255. The only netmask - * starting with zeros that is valid is 0.0.0.0. - * @throws std::invalid_argument The provided netmask is invalid. - */ + /// A constructor that creates an instance of the class out of an address representing the network prefix + /// and a netmask + /// @param address An address representing the network prefix. If the address is invalid std::invalid_argument + /// exception is thrown + /// @param netmask A string representing a netmask in the format of X.X.X.X, for example: 255.255.0.0. + /// Please notice that netmasks that start with zeros are invalid, for example: 0.0.255.255. The only netmask + /// starting with zeros that is valid is 0.0.0.0. + /// @throws std::invalid_argument The provided netmask is invalid. IPv4Network(const IPv4Address& address, const std::string& netmask); - /** - * A constructor that creates an instance of the class out of a string representing the network prefix and - * a prefix length or a netmask - * @param addressAndNetmask A string in one of these formats: - * - X.X.X.X/Y where X.X.X.X is a valid IPv4 address representing the network prefix and Y is a number between - * 0 and 32 representing the network prefix - * - X.X.X.X/Y.Y.Y.Y where X.X.X.X is a valid IPv4 address representing the network prefix and Y.Y.Y.Y is - * a valid netmask - * @throws std::invalid_argument The provided string does not represent a valid address and netmask format. - */ + /// A constructor that creates an instance of the class out of a string representing the network prefix and + /// a prefix length or a netmask + /// @param addressAndNetmask A string in one of these formats: + /// - X.X.X.X/Y where X.X.X.X is a valid IPv4 address representing the network prefix and Y is a number between + /// 0 and 32 representing the network prefix + /// - X.X.X.X/Y.Y.Y.Y where X.X.X.X is a valid IPv4 address representing the network prefix and Y.Y.Y.Y is + /// a valid netmask + /// @throws std::invalid_argument The provided string does not represent a valid address and netmask format. IPv4Network(const std::string& addressAndNetmask); - /** - * @return The prefix length, for example: the prefix length of 10.10.10.10/255.0.0.0 is 8 - */ + /// @return The prefix length, for example: the prefix length of 10.10.10.10/255.0.0.0 is 8 uint8_t getPrefixLen() const; - /** - * @return The netmask, for example: the netmask of 10.10.10.10/8 is 255.0.0.0 - */ + /// @return The netmask, for example: the netmask of 10.10.10.10/8 is 255.0.0.0 std::string getNetmask() const { return IPv4Address(m_Mask).toString(); } - /** - * @return The network prefix, for example: the network prefix of 10.10.10.10/16 is 10.10.0.0 - */ + /// @return The network prefix, for example: the network prefix of 10.10.10.10/16 is 10.10.0.0 IPv4Address getNetworkPrefix() const { return IPv4Address(m_NetworkPrefix); } - /** - * @return The lowest non-reserved IPv4 address in this network, for example: the lowest address - * in 10.10.10.10/16 is 10.10.0.1 - */ + /// @return The lowest non-reserved IPv4 address in this network, for example: the lowest address + /// in 10.10.10.10/16 is 10.10.0.1 IPv4Address getLowestAddress() const; - /** - * @return The highest non-reserved IPv4 address in this network, for example: the highest address - * in 10.10.10.10/16 is 10.10.255.254 - */ + /// @return The highest non-reserved IPv4 address in this network, for example: the highest address + /// in 10.10.10.10/16 is 10.10.255.254 IPv4Address getHighestAddress() const; - /** - * @return The number of addresses in this network including reserved addresses, for example: - * the number of addresses in 10.10.0.0/24 is 256 - */ + /// @return The number of addresses in this network including reserved addresses, for example: + /// the number of addresses in 10.10.0.0/24 is 256 uint64_t getTotalAddressCount() const; - /** - * @param address An IPv4 address - * @return True is the address belongs to the network, false otherwise or if the address isn't valid - */ + /// @param address An IPv4 address + /// @return True is the address belongs to the network, false otherwise or if the address isn't valid bool includes(const IPv4Address& address) const; - /** - * @param network An IPv4 network - * @return True is the input network is completely included within this network, false otherwise, for example: - * 10.10.10.10/16 includes 10.10.10.10/24 but doesn't include 10.10.10.10/8 - */ + /// @param network An IPv4 network + /// @return True is the input network is completely included within this network, false otherwise, for example: + /// 10.10.10.10/16 includes 10.10.10.10/24 but doesn't include 10.10.10.10/8 bool includes(const IPv4Network& network) const; - /** - * @return A string representation of the network in a format of NETWORK_PREFIX/PREFIX_LEN, for example: - * 192.168.0.0/16 - */ + /// @return A string representation of the network in a format of NETWORK_PREFIX/PREFIX_LEN, for example: + /// 192.168.0.0/16 std::string toString() const; private: @@ -665,112 +513,83 @@ namespace pcpp void initFromAddressAndNetmask(const IPv4Address& address, const IPv4Address& netmaskAddress); }; - /** - * @class IPv6Network - * A class representing IPv6 network definition - */ + /// @class IPv6Network + /// A class representing IPv6 network definition class IPv6Network { public: - /** - * A constructor that creates an instance of the class out of an address and a full prefix length, - * essentially making a network of consisting of only 1 address. - * - * @param address An address representing the network prefix. - */ + /// A constructor that creates an instance of the class out of an address and a full prefix length, + /// essentially making a network of consisting of only 1 address. + /// @param address An address representing the network prefix. explicit IPv6Network(const IPv6Address& address) : IPv6Network(address, 128u) {} - /** - * A constructor that creates an instance of the class out of an address representing the network prefix - * and a prefix length - * @param address An address representing the network prefix. If the address is invalid std::invalid_argument - * exception is thrown - * @param prefixLen A number between 0 and 128 representing the prefix length. - * @throws std::invalid_argument Prefix length is out of acceptable range. - */ + /// A constructor that creates an instance of the class out of an address representing the network prefix + /// and a prefix length + /// @param address An address representing the network prefix. If the address is invalid std::invalid_argument + /// exception is thrown + /// @param prefixLen A number between 0 and 128 representing the prefix length. + /// @throws std::invalid_argument Prefix length is out of acceptable range. IPv6Network(const IPv6Address& address, uint8_t prefixLen); - /** - * A constructor that creates an instance of the class out of an address representing the network prefix - * and a netmask - * @param address An address representing the network prefix. If the address is invalid std::invalid_argument - * exception is thrown - * @param netmask A string representing a netmask in valid IPv6 format, for example: ffff:ffff::. - * Please notice that netmasks that start with zeros are invalid, for example: 0:ffff::. The only netmask - * starting with zeros that is valid is all zeros (::). - * @throws std::invalid_argument The provided netmask is invalid. - */ + /// A constructor that creates an instance of the class out of an address representing the network prefix + /// and a netmask + /// @param address An address representing the network prefix. If the address is invalid std::invalid_argument + /// exception is thrown + /// @param netmask A string representing a netmask in valid IPv6 format, for example: ffff:ffff::. + /// Please notice that netmasks that start with zeros are invalid, for example: 0:ffff::. The only netmask + /// starting with zeros that is valid is all zeros (::). + /// @throws std::invalid_argument The provided netmask is invalid. IPv6Network(const IPv6Address& address, const std::string& netmask); - /** - * A constructor that creates an instance of the class out of a string representing the network prefix and - * a prefix length or a netmask - * @param addressAndNetmask A string in one of these formats: - * - IPV6_ADDRESS/Y where IPV6_ADDRESS is a valid IPv6 address representing the network prefix and Y is - * a number between 0 and 128 representing the network prefix - * - IPV6_ADDRESS/IPV6_NETMASK where IPV6_ADDRESS is a valid IPv6 address representing the network prefix - * and IPV6_NETMASK is a valid IPv6 netmask - * @throws std::invalid_argument The provided string does not represent a valid address and netmask format. - */ + /// A constructor that creates an instance of the class out of a string representing the network prefix and + /// a prefix length or a netmask + /// @param addressAndNetmask A string in one of these formats: + /// - IPV6_ADDRESS/Y where IPV6_ADDRESS is a valid IPv6 address representing the network prefix and Y is + /// a number between 0 and 128 representing the network prefix + /// - IPV6_ADDRESS/IPV6_NETMASK where IPV6_ADDRESS is a valid IPv6 address representing the network prefix + /// and IPV6_NETMASK is a valid IPv6 netmask + /// @throws std::invalid_argument The provided string does not represent a valid address and netmask format. IPv6Network(const std::string& addressAndNetmask); - /** - * @return The prefix length, for example: the prefix length of 3546::/ffff:: is 16 - */ + /// @return The prefix length, for example: the prefix length of 3546::/ffff:: is 16 uint8_t getPrefixLen() const; - /** - * @return The netmask, for example: the netmask of 3546::/16 is ffff:: - */ + /// @return The netmask, for example: the netmask of 3546::/16 is ffff:: std::string getNetmask() const { return IPv6Address(m_Mask).toString(); } - /** - * @return The network prefix, for example: the network prefix of 3546:f321::/16 is 3546:: - */ + /// @return The network prefix, for example: the network prefix of 3546:f321::/16 is 3546:: IPv6Address getNetworkPrefix() const { return IPv6Address(m_NetworkPrefix); } - /** - * @return The lowest non-reserved IPv6 address in this network, for example: the lowest address in 3546::/16 is - * 3546::1 - */ + /// @return The lowest non-reserved IPv6 address in this network, for example: the lowest address in 3546::/16 + /// is 3546::1 IPv6Address getLowestAddress() const; - /** - * @return The highest IPv6 address in this network, for example: the highest address in 3546::/16 is - * 3546:ffff:ffff:ffff:ffff:ffff:ffff:ffff - */ + /// @return The highest IPv6 address in this network, for example: the highest address in 3546::/16 is + /// 3546:ffff:ffff:ffff:ffff:ffff:ffff:ffff IPv6Address getHighestAddress() const; - /** - * @return The number of addresses in this network, for example: the number of addresses in 16ff::/120 is 256. - * If the number of addresses exceeds the size of uint64_t a std::out_of_range exception is thrown - */ + /// @return The number of addresses in this network, for example: the number of addresses in 16ff::/120 is 256. + /// If the number of addresses exceeds the size of uint64_t a std::out_of_range exception is thrown uint64_t getTotalAddressCount() const; - /** - * @param address An IPv6 address - * @return True is the address belongs to the network, false otherwise or if the address isn't valid - */ + /// @param address An IPv6 address + /// @return True is the address belongs to the network, false otherwise or if the address isn't valid bool includes(const IPv6Address& address) const; - /** - * @param network An IPv6 network - * @return True is the input network is completely included within this network, false otherwise, for example: - * 3546::/64 includes 3546::/120 but doesn't include 3546::/16 - */ + /// @param network An IPv6 network + /// @return True is the input network is completely included within this network, false otherwise, for example: + /// 3546::/64 includes 3546::/120 but doesn't include 3546::/16 bool includes(const IPv6Network& network) const; - /** - * @return A string representation of the network in a format of NETWORK_PREFIX/PREFIX_LEN, for example: - * fda7:9f81:6c23:275::/64 - */ + /// @return A string representation of the network in a format of NETWORK_PREFIX/PREFIX_LEN, for example: + /// fda7:9f81:6c23:275::/64 std::string toString() const; private: @@ -782,31 +601,24 @@ namespace pcpp void initFromAddressAndNetmask(const IPv6Address& address, const IPv6Address& netmaskAddress); }; - /** - * @class IPNetwork - * A class representing version independent IP network definition, both IPv4 and IPv6 are included - */ + /// @class IPNetwork + /// A class representing version independent IP network definition, both IPv4 and IPv6 are included class IPNetwork { public: - /** - * A constructor that creates an instance of the class out of an IP address and a full prefix length, - * essentially making a network of consisting of only 1 address. - * - * @param address An address representing the network prefix. - */ + /// A constructor that creates an instance of the class out of an IP address and a full prefix length, + /// essentially making a network of consisting of only 1 address. + /// @param address An address representing the network prefix. explicit IPNetwork(const IPAddress& address) : IPNetwork(address, address.isIPv4() ? 32u : 128u) {} - /** - * A constructor that creates an instance of the class out of an address representing the network prefix - * and a prefix length - * @param address An address representing the network prefix. If the address is invalid std::invalid_argument - * exception is thrown - * @param prefixLen A number representing the prefix length. Allowed ranges are 0 - 32 for IPv4 networks and 0 - - * 128 for IPv6 networks. - * @throws std::invalid_argument Prefix length is out of acceptable range. - */ + /// A constructor that creates an instance of the class out of an address representing the network prefix + /// and a prefix length + /// @param address An address representing the network prefix. If the address is invalid std::invalid_argument + /// exception is thrown + /// @param prefixLen A number representing the prefix length. Allowed ranges are 0 - 32 for IPv4 networks and 0 + /// - 128 for IPv6 networks. + /// @throws std::invalid_argument Prefix length is out of acceptable range. IPNetwork(const IPAddress& address, uint8_t prefixLen) { if (address.isIPv4()) @@ -819,17 +631,15 @@ namespace pcpp } } - /** - * A constructor that creates an instance of the class out of an address representing the network prefix - * and a netmask - * @param address An address representing the network prefix. If the address is invalid std::invalid_argument - * exception is thrown - * @param netmask A string representing a netmask in valid format, for example: ffff:ffff:: for IPv6 networks - * or 255.255.0.0 for IPv4 networks. - * Please notice that netmasks that start with zeros are invalid, for example: 0:ffff:: or 0.255.255.255. - * The only netmask starting with zeros that is valid is all zeros (:: or 0.0.0.0). - * @throws std::invalid_argument The provided netmask is invalid. - */ + /// A constructor that creates an instance of the class out of an address representing the network prefix + /// and a netmask + /// @param address An address representing the network prefix. If the address is invalid std::invalid_argument + /// exception is thrown + /// @param netmask A string representing a netmask in valid format, for example: ffff:ffff:: for IPv6 networks + /// or 255.255.0.0 for IPv4 networks. + /// Please notice that netmasks that start with zeros are invalid, for example: 0:ffff:: or 0.255.255.255. + /// The only netmask starting with zeros that is valid is all zeros (:: or 0.0.0.0). + /// @throws std::invalid_argument The provided netmask is invalid. IPNetwork(const IPAddress& address, const std::string& netmask) { if (address.isIPv4()) @@ -842,16 +652,14 @@ namespace pcpp } } - /** - * A constructor that creates an instance of the class out of a string representing the network prefix and - * a prefix length or a netmask - * @param addressAndNetmask A string in one of these formats: - * - IP_ADDRESS/Y where IP_ADDRESS is a valid IP address representing the network prefix and Y is - * a number representing the network prefix - * - IP_ADDRESS/NETMASK where IP_ADDRESS is a valid IP address representing the network prefix and NETMASK - * is a valid netmask for this type of network (IPv4 or IPv6 network) - * @throws std::invalid_argument The provided string does not represent a valid address and netmask format. - */ + /// A constructor that creates an instance of the class out of a string representing the network prefix and + /// a prefix length or a netmask + /// @param addressAndNetmask A string in one of these formats: + /// - IP_ADDRESS/Y where IP_ADDRESS is a valid IP address representing the network prefix and Y is + /// a number representing the network prefix + /// - IP_ADDRESS/NETMASK where IP_ADDRESS is a valid IP address representing the network prefix and NETMASK + /// is a valid netmask for this type of network (IPv4 or IPv6 network) + /// @throws std::invalid_argument The provided string does not represent a valid address and netmask format. IPNetwork(const std::string& addressAndNetmask) { try @@ -864,10 +672,8 @@ namespace pcpp } } - /** - * A copy c'tor for this class - * @param other The instance to copy from - */ + /// A copy c'tor for this class + /// @param other The instance to copy from IPNetwork(const IPNetwork& other) { if (other.m_IPv4Network) @@ -881,11 +687,9 @@ namespace pcpp } } - /** - * Overload of an assignment operator. - * @param[in] other An instance of IPNetwork to assign - * @return A reference to the assignee - */ + /// Overload of an assignment operator. + /// @param[in] other An instance of IPNetwork to assign + /// @return A reference to the assignee IPNetwork& operator=(const IPNetwork& other) { if (other.isIPv4Network()) @@ -898,11 +702,9 @@ namespace pcpp } } - /** - * Overload of an assignment operator. - * @param[in] other An instance of IPv4Network to assign - * @return A reference to the assignee - */ + /// Overload of an assignment operator. + /// @param[in] other An instance of IPv4Network to assign + /// @return A reference to the assignee IPNetwork& operator=(const IPv4Network& other) { if (m_IPv4Network) @@ -920,11 +722,9 @@ namespace pcpp return *this; } - /** - * Overload of an assignment operator. - * @param[in] other An instance of IPv6Network to assign - * @return A reference to the assignee - */ + /// Overload of an assignment operator. + /// @param[in] other An instance of IPv6Network to assign + /// @return A reference to the assignee IPNetwork& operator=(const IPv6Network& other) { if (m_IPv4Network) @@ -942,85 +742,67 @@ namespace pcpp return *this; } - /** - * @return The prefix length, for example: the prefix length of 3546::/ffff:: is 16, the prefix length of - * 10.10.10.10/255.0.0.0 is 8 - */ + /// @return The prefix length, for example: the prefix length of 3546::/ffff:: is 16, the prefix length of + /// 10.10.10.10/255.0.0.0 is 8 uint8_t getPrefixLen() const { return (m_IPv4Network != nullptr ? m_IPv4Network->getPrefixLen() : m_IPv6Network->getPrefixLen()); } - /** - * @return The netmask, for example: the netmask of 3546::/16 is ffff::, the netmask of 10.10.10.10/8 is - * 255.0.0.0 - */ + /// @return The netmask, for example: the netmask of 3546::/16 is ffff::, the netmask of 10.10.10.10/8 is + /// 255.0.0.0 std::string getNetmask() const { return (m_IPv4Network != nullptr ? m_IPv4Network->getNetmask() : m_IPv6Network->getNetmask()); } - /** - * @return The network prefix, for example: the network prefix of 3546:f321::/16 is 3546::, the network prefix - * of 10.10.10.10/16 is 10.10.0.0 - */ + /// @return The network prefix, for example: the network prefix of 3546:f321::/16 is 3546::, the network prefix + /// of 10.10.10.10/16 is 10.10.0.0 IPAddress getNetworkPrefix() const { return (m_IPv4Network != nullptr ? IPAddress(m_IPv4Network->getNetworkPrefix()) : IPAddress(m_IPv6Network->getNetworkPrefix())); } - /** - * @return The lowest non-reserved IP address in this network, for example: the lowest address in 3546::/16 is - * 3546::1, the lowest address in 10.10.10.10/16 is 10.10.0.1 - */ + /// @return The lowest non-reserved IP address in this network, for example: the lowest address in 3546::/16 is + /// 3546::1, the lowest address in 10.10.10.10/16 is 10.10.0.1 IPAddress getLowestAddress() const { return (m_IPv4Network != nullptr ? IPAddress(m_IPv4Network->getLowestAddress()) : IPAddress(m_IPv6Network->getLowestAddress())); } - /** - * @return The highest non-reserved IP address in this network, for example: the highest address in 3546::/16 is - * 3546:ffff:ffff:ffff:ffff:ffff:ffff:ffff, the highest address in 10.10.10.10/16 is 10.10.255.254 - */ + /// @return The highest non-reserved IP address in this network, for example: the highest address in 3546::/16 + /// is 3546:ffff:ffff:ffff:ffff:ffff:ffff:ffff, the highest address in 10.10.10.10/16 is 10.10.255.254 IPAddress getHighestAddress() const { return (m_IPv4Network != nullptr ? IPAddress(m_IPv4Network->getHighestAddress()) : IPAddress(m_IPv6Network->getHighestAddress())); } - /** - * @return The number of addresses in this network, for example: the number of addresses in 16ff::/120 is 256, - * the number of addresses in 10.10.0.0/24 is 256. If the number of addresses exceeds the size of uint64_t - * a std::out_of_range exception is thrown - */ + /// @return The number of addresses in this network, for example: the number of addresses in 16ff::/120 is 256, + /// the number of addresses in 10.10.0.0/24 is 256. If the number of addresses exceeds the size of uint64_t + /// a std::out_of_range exception is thrown uint64_t getTotalAddressCount() const { return (m_IPv4Network != nullptr ? m_IPv4Network->getTotalAddressCount() : m_IPv6Network->getTotalAddressCount()); } - /** - * @return True if this is an IPv4 network, false otherwise - */ + /// @return True if this is an IPv4 network, false otherwise bool isIPv4Network() const { return m_IPv4Network != nullptr; } - /** - * @return True if this is an IPv6 network, false otherwise - */ + /// @return True if this is an IPv6 network, false otherwise bool isIPv6Network() const { return m_IPv6Network != nullptr; } - /** - * @param address An IP address - * @return True is the address belongs to the network, false otherwise or if the address isn't valid - */ + /// @param address An IP address + /// @return True is the address belongs to the network, false otherwise or if the address isn't valid bool includes(const IPAddress& address) const { if (m_IPv4Network != nullptr) @@ -1043,10 +825,8 @@ namespace pcpp } } - /** - * @param network An IP network - * @return True is the input network is completely included within this network, false otherwise - */ + /// @param network An IP network + /// @return True is the input network is completely included within this network, false otherwise bool includes(const IPNetwork& network) const { if (m_IPv4Network != nullptr) @@ -1069,10 +849,8 @@ namespace pcpp } } - /** - * @return A string representation of the network in a format of NETWORK_PREFIX/PREFIX_LEN, for example: - * fda7:9f81:6c23:275::/64 or 192.168.0.0/16 - */ + /// @return A string representation of the network in a format of NETWORK_PREFIX/PREFIX_LEN, for example: + /// fda7:9f81:6c23:275::/64 or 192.168.0.0/16 std::string toString() const { return (m_IPv4Network != nullptr ? m_IPv4Network->toString() : m_IPv6Network->toString()); diff --git a/Common++/header/IpAddressUtils.h b/Common++/header/IpAddressUtils.h index a7b6ac7041..209264dfd9 100644 --- a/Common++/header/IpAddressUtils.h +++ b/Common++/header/IpAddressUtils.h @@ -6,10 +6,8 @@ struct in_addr; struct in6_addr; -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { // Forward declarations @@ -17,121 +15,101 @@ namespace pcpp class IPv6Address; class IPAddress; - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise bool operator==(const IPv4Address& lhs, const in_addr& rhs); - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const IPv4Address& lhs, const in_addr& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise inline bool operator==(const in_addr& lhs, const IPv4Address& rhs) { return rhs == lhs; } - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const in_addr& lhs, const IPv4Address& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise bool operator==(const IPv6Address& lhs, const in6_addr& rhs); - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const IPv6Address& lhs, const in6_addr& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise inline bool operator==(const in6_addr& lhs, const IPv6Address& rhs) { return rhs == lhs; } - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const in6_addr& lhs, const IPv6Address& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise bool operator==(const IPAddress& lhs, const in_addr& rhs); - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const IPAddress& lhs, const in_addr& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise inline bool operator==(const in_addr& lhs, const IPAddress& rhs) { return rhs == lhs; } - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const in_addr& lhs, const IPAddress& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise bool operator==(const IPAddress& lhs, const in6_addr& rhs); - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const IPAddress& lhs, const in6_addr& rhs) { return !(lhs == rhs); } - /** - * Overload of the equal-to operator - * @return True if the addresses are equal, false otherwise - */ + + /// Overload of the equal-to operator + /// @return True if the addresses are equal, false otherwise inline bool operator==(const in6_addr& lhs, const IPAddress& rhs) { return rhs == lhs; } - /** - * Overload of the not-equal-to operator - * @return True if the addresses differ, false otherwise - */ + + /// Overload of the not-equal-to operator + /// @return True if the addresses differ, false otherwise inline bool operator!=(const in6_addr& lhs, const IPAddress& rhs) { return !(lhs == rhs); diff --git a/Common++/header/IpUtils.h b/Common++/header/IpUtils.h index 2cf9f7a00f..6dadfb5028 100644 --- a/Common++/header/IpUtils.h +++ b/Common++/header/IpUtils.h @@ -25,83 +25,66 @@ // We use "__MINGW64_VERSION_MAJOR" and not __MINGW64__ to detect MinGW-w64 compiler // because the second one is not defined for MinGW-w64 in 32bits mode #if defined(_WIN32) && !defined(_MSC_VER) && (!defined(__MINGW64_VERSION_MAJOR) || (__MINGW64_VERSION_MAJOR < 8)) -/** - * Convert a network format address to presentation format. - * @param[in] af Address family, can be either AF_INET (IPv4) or AF_INET6 (IPv6) - * @param[in] src Network address structure, can be either in_addr (IPv4) or in6_addr (IPv6) - * @param[out] dst Network address string representation - * @param[in] size 'dst' Maximum size - * @return pointer to presentation format address ('dst'), or nullptr (see errno). - */ + +/// Convert a network format address to presentation format. +/// @param[in] af Address family, can be either AF_INET (IPv4) or AF_INET6 (IPv6) +/// @param[in] src Network address structure, can be either in_addr (IPv4) or in6_addr (IPv6) +/// @param[out] dst Network address string representation +/// @param[in] size 'dst' Maximum size +/// @return pointer to presentation format address ('dst'), or nullptr (see errno). const char* inet_ntop(int af, const void* src, char* dst, size_t size); -/** - * Convert from presentation format (which usually means ASCII printable) - * to network format (which is usually some kind of binary format). - * @param[in] af Address family, can be either AF_INET (IPv4) or AF_INET6 (IPv6) - * @param[in] src Network address string representation - * @param[out] dst Network address structure result, can be either in_addr (IPv4) or in6_addr (IPv6) - * @return - * 1 if the address was valid for the specified address family; - * 0 if the address wasn't valid ('dst' is untouched in this case); - * -1 if some other error occurred ('dst' is untouched in this case, too) - */ +/// Convert from presentation format (which usually means ASCII printable) +/// to network format (which is usually some kind of binary format). +/// @param[in] af Address family, can be either AF_INET (IPv4) or AF_INET6 (IPv6) +/// @param[in] src Network address string representation +/// @param[out] dst Network address structure result, can be either in_addr (IPv4) or in6_addr (IPv6) +/// @return +/// 1 if the address was valid for the specified address family; +/// 0 if the address wasn't valid ('dst' is untouched in this case); +/// -1 if some other error occurred ('dst' is untouched in this case, too) int inet_pton(int af, const char* src, void* dst); #endif -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { namespace internal { - /** - * Extract IPv4 address from sockaddr - * @param[in] sa - input sockaddr - * @return Address in in_addr format - * @throws std::invalid_argument Sockaddr family is not AF_INET or sockaddr is nullptr. - */ + /// Extract IPv4 address from sockaddr + /// @param[in] sa - input sockaddr + /// @return Address in in_addr format + /// @throws std::invalid_argument Sockaddr family is not AF_INET or sockaddr is nullptr. in_addr* sockaddr2in_addr(sockaddr* sa); - /** - * Attempt to extract IPv4 address from sockaddr - * @param[in] sa - input sockaddr - * @return Pointer to address in in_addr format or nullptr if extraction fails. - */ + /// Attempt to extract IPv4 address from sockaddr + /// @param[in] sa - input sockaddr + /// @return Pointer to address in in_addr format or nullptr if extraction fails. in_addr* try_sockaddr2in_addr(sockaddr* sa); - /** - * Extract IPv6 address from sockaddr - * @param[in] sa - input sockaddr - * @return Address in in6_addr format - * @throws std::invalid_argument Sockaddr family is not AF_INET6 or sockaddr is nullptr. - */ + /// Extract IPv6 address from sockaddr + /// @param[in] sa - input sockaddr + /// @return Address in in6_addr format + /// @throws std::invalid_argument Sockaddr family is not AF_INET6 or sockaddr is nullptr. in6_addr* sockaddr2in6_addr(sockaddr* sa); - /** - * Attempt to extract IPv6 address from sockaddr - * @param[in] sa - input sockaddr - * @return Pointer to address in in6_addr format or nullptr if extraction fails. - */ + /// Attempt to extract IPv6 address from sockaddr + /// @param[in] sa - input sockaddr + /// @return Pointer to address in in6_addr format or nullptr if extraction fails. in6_addr* try_sockaddr2in6_addr(sockaddr* sa); - /** - * Converts a sockaddr format address to its string representation - * @param[in] sa Address in sockaddr format - * @param[out] resultString String representation of the address - * @param[in] resultBufLen Length of the result buffer. - * @throws std::invalid_argument Sockaddr family is not AF_INET or AF_INET6, sockaddr is nullptr or the result - * str buffer is insufficient. - */ + /// Converts a sockaddr format address to its string representation + /// @param[in] sa Address in sockaddr format + /// @param[out] resultString String representation of the address + /// @param[in] resultBufLen Length of the result buffer. + /// @throws std::invalid_argument Sockaddr family is not AF_INET or AF_INET6, sockaddr is nullptr or the result + /// str buffer is insufficient. void sockaddr2string(sockaddr const* sa, char* resultString, size_t resultBufLen); - /** - * Convert a in_addr format address to 32bit representation - * @param[in] inAddr Address in in_addr format - * @return Address in 32bit format - */ + /// Convert a in_addr format address to 32bit representation + /// @param[in] inAddr Address in in_addr format + /// @return Address in 32bit format uint32_t in_addr2int(in_addr inAddr); } // namespace internal } // namespace pcpp diff --git a/Common++/header/LRUList.h b/Common++/header/LRUList.h index a900c8413a..81bc6db3a7 100644 --- a/Common++/header/LRUList.h +++ b/Common++/header/LRUList.h @@ -1,6 +1,7 @@ #pragma once #include +#include #include #if __cplusplus > 199711L || _MSC_VER >= 1800 @@ -9,47 +10,39 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * @class LRUList - * A template class that implements a LRU cache with limited size. Each time the user puts an element it goes to - * head of the list as the most recently used element (if the element was already in the list it advances to the - * head of the list). The last element in the list is the one least recently used and will be pulled out of the list - * if it reaches its max size and a new element comes in. All actions on this LRU list are O(1) - */ + /// @class LRUList + /// A template class that implements a LRU cache with limited size. Each time the user puts an element it goes to + /// head of the list as the most recently used element (if the element was already in the list it advances to the + /// head of the list). The last element in the list is the one least recently used and will be pulled out of the + /// list if it reaches its max size and a new element comes in. All actions on this LRU list are O(1) template class LRUList { public: typedef typename std::list::iterator ListIterator; typedef typename std::unordered_map::iterator MapIterator; - /** - * A c'tor for this class - * @param[in] maxSize The max size this list can go - */ - explicit LRUList(size_t maxSize) + /// A c'tor for this class + /// @param[in] maxSize The max size this list can go + explicit LRUList(std::size_t maxSize) { m_MaxSize = maxSize; } - /** - * Puts an element in the list. This element will be inserted (or advanced if it already exists) to the head of - * the list as the most recently used element. If the list already reached its max size and the element is new - * this method will remove the least recently used element and return a value in deletedValue. Method complexity - * is O(log(getSize())). This is a optimized version of the method T* put(const T&). - * @param[in] element The element to insert or to advance to the head of the list (if already exists) - * @param[out] deletedValue The value of deleted element if a pointer is not nullptr. This parameter is - * optional. - * @return 0 if the list didn't reach its max size, 1 otherwise. In case the list already reached its max size - * and deletedValue is not nullptr the value of deleted element is copied into the place the deletedValue points - * to. - */ + /// Puts an element in the list. This element will be inserted (or advanced if it already exists) to the head of + /// the list as the most recently used element. If the list already reached its max size and the element is new + /// this method will remove the least recently used element and return a value in deletedValue. Method + /// complexity is O(log(getSize())). This is a optimized version of the method T* put(const T&). + /// @param[in] element The element to insert or to advance to the head of the list (if already exists) + /// @param[out] deletedValue The value of deleted element if a pointer is not nullptr. This parameter is + /// optional. + /// @return 0 if the list didn't reach its max size, 1 otherwise. In case the list already reached its max size + /// and deletedValue is not nullptr the value of deleted element is copied into the place the deletedValue + /// points to. int put(const T& element, T* deletedValue = nullptr) { m_CacheItemsList.push_front(element); @@ -83,28 +76,22 @@ namespace pcpp return 0; } - /** - * Get the most recently used element (the one at the beginning of the list) - * @return The most recently used element - */ + /// Get the most recently used element (the one at the beginning of the list) + /// @return The most recently used element const T& getMRUElement() const { return m_CacheItemsList.front(); } - /** - * Get the least recently used element (the one at the end of the list) - * @return The least recently used element - */ + /// Get the least recently used element (the one at the end of the list) + /// @return The least recently used element const T& getLRUElement() const { return m_CacheItemsList.back(); } - /** - * Erase an element from the list. If element isn't found in the list nothing happens - * @param[in] element The element to erase - */ + /// Erase an element from the list. If element isn't found in the list nothing happens + /// @param[in] element The element to erase void eraseElement(const T& element) { MapIterator iter = m_CacheItemsMap.find(element); @@ -115,17 +102,13 @@ namespace pcpp m_CacheItemsMap.erase(iter); } - /** - * @return The max size of this list as determined in the c'tor - */ + /// @return The max size of this list as determined in the c'tor size_t getMaxSize() const { return m_MaxSize; } - /** - * @return The number of elements currently in this list - */ + /// @return The number of elements currently in this list size_t getSize() const { return m_CacheItemsMap.size(); diff --git a/Common++/header/Logger.h b/Common++/header/Logger.h index fafe6a9e37..49d05ef759 100644 --- a/Common++/header/Logger.h +++ b/Common++/header/Logger.h @@ -42,16 +42,12 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * An enum representing all PcapPlusPlus modules - */ + /// An enum representing all PcapPlusPlus modules enum LogModule { UndefinedLogModule, @@ -117,32 +113,28 @@ namespace pcpp NumOfLogModules }; - /** - * @class Logger - * PcapPlusPlus logger manager. - * PcapPlusPlus uses this logger to output both error and debug logs. - * There are currently 3 log levels: Logger#Error, Logger#Info and Logger#Debug. - * - * PcapPlusPlus is divided into modules (described in #LogModule enum). The user can set the log level got each - * module or to all modules at once. The default is Logger#Info which outputs only error messages. Changing log - * level for modules can be done dynamically while the application is running. - * - * The logger also exposes a method to retrieve the last error log message. - * - * Logs are printed to console by default in a certain format. The user can set a different print function to change - * the format or to print to other media (such as files, etc.). - * - * PcapPlusPlus logger is a singleton which can be reached from anywhere in the code. - * - * Note: Logger#Info level logs are currently only used in DPDK devices to set DPDK log level to RTE_LOG_NOTICE. - */ + /// @class Logger + /// PcapPlusPlus logger manager. + /// PcapPlusPlus uses this logger to output both error and debug logs. + /// There are currently 3 log levels: Logger#Error, Logger#Info and Logger#Debug. + /// + /// PcapPlusPlus is divided into modules (described in #LogModule enum). The user can set the log level got each + /// module or to all modules at once. The default is Logger#Info which outputs only error messages. Changing log + /// level for modules can be done dynamically while the application is running. + /// + /// The logger also exposes a method to retrieve the last error log message. + /// + /// Logs are printed to console by default in a certain format. The user can set a different print function to + /// change the format or to print to other media (such as files, etc.). + /// + /// PcapPlusPlus logger is a singleton which can be reached from anywhere in the code. + /// + /// Note: Logger#Info level logs are currently only used in DPDK devices to set DPDK log level to RTE_LOG_NOTICE. class Logger { public: - /** - * An enum representing the log level. Currently 3 log levels are supported: Error, Info and Debug. Info is the - * default log level - */ + /// An enum representing the log level. Currently 3 log levels are supported: Error, Info and Debug. Info is the + /// default log level enum LogLevel { Error, ///< Error log level @@ -150,110 +142,86 @@ namespace pcpp Debug ///< Debug log level }; - /** - * @typedef LogPrinter - * Log printer callback. Used for printing the logs in a custom way. - * @param[in] logLevel The log level for this log message - * @param[in] logMessage The log message - * @param[in] file The source file in PcapPlusPlus code the log message is coming from - * @param[in] method The method in PcapPlusPlus code the log message is coming from - * @param[in] line The line in PcapPlusPlus code the log message is coming from - */ + /// @typedef LogPrinter + /// Log printer callback. Used for printing the logs in a custom way. + /// @param[in] logLevel The log level for this log message + /// @param[in] logMessage The log message + /// @param[in] file The source file in PcapPlusPlus code the log message is coming from + /// @param[in] method The method in PcapPlusPlus code the log message is coming from + /// @param[in] line The line in PcapPlusPlus code the log message is coming from typedef void (*LogPrinter)(LogLevel logLevel, const std::string& logMessage, const std::string& file, const std::string& method, const int line); - /** - * A static method for converting the log level enum to a string. - * @param[in] logLevel A log level enum - * @return The log level as a string - */ + /// A static method for converting the log level enum to a string. + /// @param[in] logLevel A log level enum + /// @return The log level as a string static std::string logLevelAsString(LogLevel logLevel); - /** - * Get the log level for a certain module - * @param[in] module PcapPlusPlus module - * @return The log level set for this module - */ + /// Get the log level for a certain module + /// @param[in] module PcapPlusPlus module + /// @return The log level set for this module LogLevel getLogLevel(LogModule module) { return m_LogModulesArray[module]; } - /** - * Set the log level for a certain PcapPlusPlus module - * @param[in] module PcapPlusPlus module - * @param[in] level The log level to set the module to - */ + /// Set the log level for a certain PcapPlusPlus module + /// @param[in] module PcapPlusPlus module + /// @param[in] level The log level to set the module to void setLogLevel(LogModule module, LogLevel level) { m_LogModulesArray[module] = level; } - /** - * Check whether a certain module is set to debug log level - * @param[in] module PcapPlusPlus module - * @return True if this module log level is "debug". False otherwise - */ + /// Check whether a certain module is set to debug log level + /// @param[in] module PcapPlusPlus module + /// @return True if this module log level is "debug". False otherwise bool isDebugEnabled(LogModule module) const { return m_LogModulesArray[module] == Debug; } - /** - * Set all PcapPlusPlus modules to a certain log level - * @param[in] level The log level to set all modules to - */ + /// Set all PcapPlusPlus modules to a certain log level + /// @param[in] level The log level to set all modules to void setAllModulesToLogLevel(LogLevel level) { for (int i = 1; i < NumOfLogModules; i++) m_LogModulesArray[i] = level; } - /** - * Set a custom log printer. - * @param[in] printer A log printer function that will be called for every log message - */ + /// Set a custom log printer. + /// @param[in] printer A log printer function that will be called for every log message void setLogPrinter(LogPrinter printer) { m_LogPrinter = printer; } - /** - * Set the log printer back to the default printer - */ + /// Set the log printer back to the default printer void resetLogPrinter() { m_LogPrinter = &defaultLogPrinter; } - /** - * @return Get the last error message - */ + /// @return Get the last error message std::string getLastError() { return m_LastError; } - /** - * Suppress logs in all PcapPlusPlus modules - */ + /// Suppress logs in all PcapPlusPlus modules void suppressLogs() { m_LogsEnabled = false; } - /** - * Enable logs in all PcapPlusPlus modules - */ + /// Enable logs in all PcapPlusPlus modules void enableLogs() { m_LogsEnabled = true; } - /** - * Get an indication if logs are currently enabled. - * @return True if logs are currently enabled, false otherwise - */ + /// Get an indication if logs are currently enabled. + /// @return True if logs are currently enabled, false otherwise bool logsEnabled() const { return m_LogsEnabled; @@ -267,17 +235,13 @@ namespace pcpp std::ostringstream* internalCreateLogStream(); - /** - * An internal method to print log messages. Shouldn't be used externally. - */ + /// An internal method to print log messages. Shouldn't be used externally. void internalPrintLogMessage(std::ostringstream* logStream, Logger::LogLevel logLevel, const char* file, const char* method, int line); - /** - * Get access to Logger singleton - * @todo: make this singleton thread-safe/ - * @return a pointer to the Logger singleton - **/ + /// Get access to Logger singleton + /// @todo: make this singleton thread-safe/ + /// @return a pointer to the Logger singleton static Logger& getInstance() { static Logger instance; diff --git a/Common++/header/MacAddress.h b/Common++/header/MacAddress.h index 8b59f7d53c..6e0834b013 100644 --- a/Common++/header/MacAddress.h +++ b/Common++/header/MacAddress.h @@ -10,62 +10,48 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * @class MacAddress - * Represents L2 MAC addresses. Can be constructed from string or a series of 6 byte octets - */ + /// @class MacAddress + /// Represents L2 MAC addresses. Can be constructed from string or a series of 6 byte octets class MacAddress { public: - /** - * Default constructor for this class. - * Initializes the address as 00:00:00:00:00:00. - */ + /// Default constructor for this class. + /// Initializes the address as 00:00:00:00:00:00. MacAddress() = default; - /** - * A constructor that creates an instance of the class out of a byte array. - * The byte array length should be 6 (as MAC address is 6-byte long), and the remaining bytes are ignored. - * If the byte array is invalid, the constructor throws an exception. - * @param[in] addr A pointer to the byte array containing 6 bytes representing the MAC address - */ + /// A constructor that creates an instance of the class out of a byte array. + /// The byte array length should be 6 (as MAC address is 6-byte long), and the remaining bytes are ignored. + /// If the byte array is invalid, the constructor throws an exception. + /// @param[in] addr A pointer to the byte array containing 6 bytes representing the MAC address explicit MacAddress(const uint8_t* addr) { memcpy(m_Address, addr, sizeof(m_Address)); } - /** - * A constructor that creates an instance of the class out of a std::string. - * If the string doesn't represent a valid MAC address, the constructor throws an exception. - * @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00" - */ + /// A constructor that creates an instance of the class out of a std::string. + /// If the string doesn't represent a valid MAC address, the constructor throws an exception. + /// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00" explicit MacAddress(const std::string& addr); - /** - * A template constructor that creates an instance of the class out of a string convertible to std::string. - * If the string doesn't represent a valid MAC address, the constructor throws an exception. - * @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00" - */ + /// A template constructor that creates an instance of the class out of a string convertible to std::string. + /// If the string doesn't represent a valid MAC address, the constructor throws an exception. + /// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00" template ::value>::type> MacAddress(const T& addr) : MacAddress(static_cast(addr)) {} - /** - * A constructor that creates an instance of 6 bytes representing the MAC address - * @param[in] firstOctet Represent the first octet in the address - * @param[in] secondOctet Represent the second octet in the address - * @param[in] thirdOctet Represent the third octet in the address - * @param[in] fourthOctet Represent the fourth octet in the address - * @param[in] fifthOctet Represent the fifth octet in the address - * @param[in] sixthOctet Represent the sixth octet in the address - */ + /// A constructor that creates an instance of 6 bytes representing the MAC address + /// @param[in] firstOctet Represent the first octet in the address + /// @param[in] secondOctet Represent the second octet in the address + /// @param[in] thirdOctet Represent the third octet in the address + /// @param[in] fourthOctet Represent the fourth octet in the address + /// @param[in] fifthOctet Represent the fifth octet in the address + /// @param[in] sixthOctet Represent the sixth octet in the address inline MacAddress(uint8_t firstOctet, uint8_t secondOctet, uint8_t thirdOctet, uint8_t fourthOctet, uint8_t fifthOctet, uint8_t sixthOctet) { @@ -77,12 +63,10 @@ namespace pcpp m_Address[5] = sixthOctet; } - /** - * A constructor that creates an instance out of the initializer list. - * The byte list length should be 6 (as MAC address is 6-byte long). - * If the list is invalid, the constructor throws an exception. - * @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address - */ + /// A constructor that creates an instance out of the initializer list. + /// The byte list length should be 6 (as MAC address is 6-byte long). + /// If the list is invalid, the constructor throws an exception. + /// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address MacAddress(std::initializer_list octets) { if (octets.size() != sizeof(m_Address)) @@ -92,32 +76,26 @@ namespace pcpp std::copy(octets.begin(), octets.end(), std::begin(m_Address)); } - /** - * Overload of the comparison operator. - * @param[in] other The object to compare with - * @return True if addresses are equal, false otherwise - */ + /// Overload of the comparison operator. + /// @param[in] other The object to compare with + /// @return True if addresses are equal, false otherwise bool operator==(const MacAddress& other) const { return memcmp(m_Address, other.m_Address, sizeof(m_Address)) == 0; } - /** - * Overload of the not-equal operator - * @param[in] other The object to compare with - * @return True if addresses are not equal, false otherwise - */ + /// Overload of the not-equal operator + /// @param[in] other The object to compare with + /// @return True if addresses are not equal, false otherwise bool operator!=(const MacAddress& other) const { return !operator==(other); } - /** - * Overload of the assignment operator. - * If the list is invalid, the constructor throws an exception. - * @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address, the - * length of the list must be equal to 6 - */ + /// Overload of the assignment operator. + /// If the list is invalid, the constructor throws an exception. + /// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address, + /// the length of the list must be equal to 6 MacAddress& operator=(std::initializer_list octets) { if (octets.size() != sizeof(m_Address)) @@ -129,45 +107,35 @@ namespace pcpp return *this; } - /** - * Returns the pointer to raw data - * @return The pointer to raw data - */ + /// Returns the pointer to raw data + /// @return The pointer to raw data const uint8_t* getRawData() const { return m_Address; } - /** - * Returns a std::string representation of the address - * @return A string representation of the address - */ + /// Returns a std::string representation of the address + /// @return A string representation of the address std::string toString() const; - /** - * Allocates a byte array of length 6 and copies address value into it. Array deallocation is user - * responsibility - * @param[in] arr A pointer to where array will be allocated - */ + /// Allocates a byte array of length 6 and copies address value into it. Array deallocation is user + /// responsibility + /// @param[in] arr A pointer to where array will be allocated void copyTo(uint8_t** arr) const { *arr = new uint8_t[sizeof(m_Address)]; memcpy(*arr, m_Address, sizeof(m_Address)); } - /** - * Gets a pointer to an already allocated byte array and copies the address value to it. - * This method assumes array allocated size is at least 6 (the size of a MAC address) - * @param[in] arr A pointer to the array which address will be copied to - */ + /// Gets a pointer to an already allocated byte array and copies the address value to it. + /// This method assumes array allocated size is at least 6 (the size of a MAC address) + /// @param[in] arr A pointer to the array which address will be copied to void copyTo(uint8_t* arr) const { memcpy(arr, m_Address, sizeof(m_Address)); } - /** - * A static value representing a zero value of MAC address, meaning address of value "00:00:00:00:00:00" - */ + /// A static value representing a zero value of MAC address, meaning address of value "00:00:00:00:00:00" static MacAddress Zero; private: diff --git a/Common++/header/OUILookup.h b/Common++/header/OUILookup.h index fb49ac236d..20ac58d56f 100644 --- a/Common++/header/OUILookup.h +++ b/Common++/header/OUILookup.h @@ -7,27 +7,21 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * @class OUILookup - * Provides vendor name matching functionality from MAC addresses. It uses an internal database to define name of - * the vendor. The class itself should be initialized by using initOUIDatabaseFromJson() otherwise all requests will - * return "Unknown" as vendor. The class itself currently does not support on-fly modifying the database but anyone - * who wants to add/modify/remove entries, should modify 3rdParty/OUILookup/PCPP_OUIDatabase.json file and call to - * initOUIDatabaseFromJson() function to renew the internal data. - */ + /// @class OUILookup + /// Provides vendor name matching functionality from MAC addresses. It uses an internal database to define name of + /// the vendor. The class itself should be initialized by using initOUIDatabaseFromJson() otherwise all requests + /// will return "Unknown" as vendor. The class itself currently does not support on-fly modifying the database but + /// anyone who wants to add/modify/remove entries, should modify 3rdParty/OUILookup/PCPP_OUIDatabase.json file and + /// call to initOUIDatabaseFromJson() function to renew the internal data. class OUILookup { private: - /** - * MAC addresses with mask values. For example for a MAC address "XX:XX:XX:XX:X0:00/36" the first element will - * be 36, and the second element will be unsigned integer equivalent of "XX:XX:XX:XX:X0:00" and vendor name. - */ + /// MAC addresses with mask values. For example for a MAC address "XX:XX:XX:XX:X0:00/36" the first element will + /// be 36, and the second element will be unsigned integer equivalent of "XX:XX:XX:XX:X0:00" and vendor name. struct MaskedFilter { int mask; @@ -41,10 +35,8 @@ namespace pcpp std::vector maskedFilter; }; - /** - * MAC addresses with only first three octets. The first element is unsigned integer equivalent of "XX:XX:XX" - * formatted MAC address - */ + /// MAC addresses with only first three octets. The first element is unsigned integer equivalent of "XX:XX:XX" + /// formatted MAC address typedef std::unordered_map OUIVendorMap; /// Internal vendor list for MAC addresses @@ -53,19 +45,15 @@ namespace pcpp template int64_t internalParser(T& jsonData); public: - /** - * Initialise internal OUI database from a JSON file - * @param[in] path Path to OUI database. The database itself is located at - * 3rdParty/OUILookup/PCPP_OUIDatabase.json - * @return Returns the number of total vendors, negative on errors - */ + /// Initialise internal OUI database from a JSON file + /// @param[in] path Path to OUI database. The database itself is located at + /// 3rdParty/OUILookup/PCPP_OUIDatabase.json + /// @return Returns the number of total vendors, negative on errors int64_t initOUIDatabaseFromJson(const std::string& path = ""); - /** - * Returns the vendor of the MAC address. OUI database should be initialized with initOUIDatabaseFromJson() - * @param[in] addr MAC address to search - * @return Vendor name - */ + /// Returns the vendor of the MAC address. OUI database should be initialized with initOUIDatabaseFromJson() + /// @param[in] addr MAC address to search + /// @return Vendor name std::string getVendorName(const pcpp::MacAddress& addr); }; } // namespace pcpp diff --git a/Common++/header/PcapPlusPlusVersion.h b/Common++/header/PcapPlusPlusVersion.h index 0e47016610..a4d5ca2b51 100644 --- a/Common++/header/PcapPlusPlusVersion.h +++ b/Common++/header/PcapPlusPlusVersion.h @@ -4,10 +4,8 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { #define PCAPPLUSPLUS_VERSION "24.09+" @@ -15,28 +13,22 @@ namespace pcpp #define PCAPPLUSPLUS_VERSION_FULL "v" PCAPPLUSPLUS_VERSION " (" PCAPPLUSPLUS_VERSION_OFFICIAL ")" - /** - * @return PcapPlusPlus current version, e.g: 23.09. Notice that for non-official releases (which were pulled from - * GitHub) the version will end with a '+'. For example: '23.09+' means non-official release but '23.09' means - * official release - */ + /// @return PcapPlusPlus current version, e.g: 23.09. Notice that for non-official releases (which were pulled from + /// GitHub) the version will end with a '+'. For example: '23.09+' means non-official release but '23.09' means + /// official release inline std::string getPcapPlusPlusVersion() { return PCAPPLUSPLUS_VERSION; } - /** - * @return PcapPlusPlus long version string which includes the version and info whether it's an official or - * non-official release. For example: "v23.09+ (non-official release)" or "v23.09 (official release)" - */ + /// @return PcapPlusPlus long version string which includes the version and info whether it's an official or + /// non-official release. For example: "v23.09+ (non-official release)" or "v23.09 (official release)" inline std::string getPcapPlusPlusVersionFull() { return PCAPPLUSPLUS_VERSION_FULL; } - /** - * @return The build date and time in a format of "Mmm dd yyyy hh:mm:ss" - */ + /// @return The build date and time in a format of "Mmm dd yyyy hh:mm:ss" #ifdef PCAPPP_BUILD_REPRODUCIBLE inline std::string getBuildDateTime() { @@ -49,20 +41,14 @@ namespace pcpp } #endif - /** - * @return The Git commit (revision) the binaries are built from - */ + /// @return The Git commit (revision) the binaries are built from std::string getGitCommit(); - /** - * @return The Git branch the binaries are built from - */ + /// @return The Git branch the binaries are built from std::string getGitBranch(); - /** - * @return Git branch and commit the binaries are built from. - * Aggregates data from getGitCommit() and getGitBranch() - */ + /// @return Git branch and commit the binaries are built from. + /// Aggregates data from getGitCommit() and getGitBranch() std::string getGitInfo(); } // namespace pcpp diff --git a/Common++/header/PointerVector.h b/Common++/header/PointerVector.h index 342ad62e0b..be2a072c56 100644 --- a/Common++/header/PointerVector.h +++ b/Common++/header/PointerVector.h @@ -12,19 +12,15 @@ /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { namespace internal { - /** - * @brief A helper struct to facilitate the creation of a copy of an object. - * @tparam T The type of object to copy. - * @tparam Enable Helper parameter for SFINAE. - */ + /// @brief A helper struct to facilitate the creation of a copy of an object. + /// @tparam T The type of object to copy. + /// @tparam Enable Helper parameter for SFINAE. template struct Copier { std::unique_ptr operator()(const T& obj) const @@ -33,10 +29,8 @@ namespace pcpp } }; - /** - * @brief A specialization of Copier to facilitate the safe copying of polymorphic objects via clone() method. - * @tparam T The type of object to copy. - */ + /// @brief A specialization of Copier to facilitate the safe copying of polymorphic objects via clone() method. + /// @tparam T The type of object to copy. template struct Copier::value>::type> { std::unique_ptr operator()(const T& obj) const @@ -47,65 +41,49 @@ namespace pcpp }; } // namespace internal - /** - * @class PointerVector - * A template class for representing a std::vector of pointers. Once (a pointer to) an element is added to this - * vector, the element responsibility moves to the vector, meaning the PointerVector will free the object once it's - * removed from the vector This class wraps std::vector and adds the capability of freeing objects once they're - * removed from it - */ + /// @class PointerVector + /// A template class for representing a std::vector of pointers. Once (a pointer to) an element is added to this + /// vector, the element responsibility moves to the vector, meaning the PointerVector will free the object once it's + /// removed from the vector This class wraps std::vector and adds the capability of freeing objects once they're + /// removed from it template class PointerVector { public: - /** - * Iterator object that is used for iterating all elements in the vector - */ + /// Iterator object that is used for iterating all elements in the vector using VectorIterator = typename std::vector::iterator; - /** - * Const iterator object that is used for iterating all elements in a constant vector - */ + /// Const iterator object that is used for iterating all elements in a constant vector using ConstVectorIterator = typename std::vector::const_iterator; - /** - * A constructor that create an empty instance of this object - */ + /// A constructor that create an empty instance of this object PointerVector() {} - /** - * Copies the vector along with all elements inside it. - * All elements inside the copied vector are duplicates and the originals remain unchanged. - * @param[in] other The vector to copy from. - * @remarks As the vector is copied via deep copy, all pointers obtained from the copied vector - * reference the duplicates and not the originals. - */ + /// Copies the vector along with all elements inside it. + /// All elements inside the copied vector are duplicates and the originals remain unchanged. + /// @param[in] other The vector to copy from. + /// @remarks As the vector is copied via deep copy, all pointers obtained from the copied vector + /// reference the duplicates and not the originals. PointerVector(const PointerVector& other) : m_Vector(deepCopyUnsafe(other.m_Vector)) {} - /** - * Move constructor. All elements along with their ownership is transferred to the new vector. - * @param[in] other The vector to move from. - */ + /// Move constructor. All elements along with their ownership is transferred to the new vector. + /// @param[in] other The vector to move from. PointerVector(PointerVector&& other) noexcept : m_Vector(std::move(other.m_Vector)) { other.m_Vector.clear(); } - /** - * A destructor for this class. The destructor frees all elements that are binded to the vector - */ + /// A destructor for this class. The destructor frees all elements that are binded to the vector ~PointerVector() { freeVectorUnsafe(m_Vector); } - /** - * A copy assignment operator. Replaces the contents with a copy of the contents of other. - * See copy constructor for more information on the specific copy procedure. - * @param[in] other The vector to copy from. - * @return A reference to the current object. - */ + /// A copy assignment operator. Replaces the contents with a copy of the contents of other. + /// See copy constructor for more information on the specific copy procedure. + /// @param[in] other The vector to copy from. + /// @return A reference to the current object. PointerVector& operator=(const PointerVector& other) { // Saves a copy of the old pointer to defer cleanup. @@ -125,12 +103,10 @@ namespace pcpp return *this; } - /** - * A move assignment operator. Replaces the contents with those of other via move semantics. - * The other vector is left empty. - * @param[in] other The vector to move from. - * @return A reference to the current object. - */ + /// A move assignment operator. Replaces the contents with those of other via move semantics. + /// The other vector is left empty. + /// @param[in] other The vector to move from. + /// @return A reference to the current object. PointerVector& operator=(PointerVector&& other) noexcept { // Releases all current elements. @@ -142,26 +118,21 @@ namespace pcpp return *this; } - /** - * Clears all elements of the vector while freeing them - */ + /// Clears all elements of the vector while freeing them void clear() { freeVectorUnsafe(m_Vector); m_Vector.clear(); } - /** - * Adding a nullptr to the vector is not allowed. - */ + /// Adding a nullptr to the vector is not allowed. void pushBack(std::nullptr_t element, bool freeElementOnError = true) = delete; - /** - * Add a new (pointer to an) element to the vector - * @param[in] element A pointer to an element to assume ownership of. - * @param[in] freeElementOnError If set to true, the element is freed if an exception is thrown during the push. - * @throws std::invalid_argument The provided pointer is a nullptr. - */ + /// Add a new (pointer to an) element to the vector + /// @param[in] element A pointer to an element to assume ownership of. + /// @param[in] freeElementOnError If set to true, the element is freed if an exception is thrown during the + /// push. + /// @throws std::invalid_argument The provided pointer is a nullptr. void pushBack(T* element, bool freeElementOnError = true) { if (element == nullptr) @@ -183,12 +154,10 @@ namespace pcpp } } - /** - * Add a new element to the vector that has been managed by an unique pointer. - * @param[in] element A unique pointer holding an element. - * @throws std::invalid_argument The provided pointer is a nullptr. - * @remarks If pushBack throws the element is freed immediately. - */ + /// Add a new element to the vector that has been managed by an unique pointer. + /// @param[in] element A unique pointer holding an element. + /// @throws std::invalid_argument The provided pointer is a nullptr. + /// @remarks If pushBack throws the element is freed immediately. void pushBack(std::unique_ptr element) { if (!element) @@ -203,103 +172,81 @@ namespace pcpp element.release(); } - /** - * Get the first element of the vector - * @return An iterator object pointing to the first element of the vector - */ + /// Get the first element of the vector + /// @return An iterator object pointing to the first element of the vector VectorIterator begin() { return m_Vector.begin(); } - /** - * Get the first element of a constant vector - * @return A const iterator object pointing to the first element of the vector - */ + /// Get the first element of a constant vector + /// @return A const iterator object pointing to the first element of the vector ConstVectorIterator begin() const { return m_Vector.begin(); } - /** - * Get the last element of the vector - * @return An iterator object pointing to the last element of the vector - */ + /// Get the last element of the vector + /// @return An iterator object pointing to the last element of the vector VectorIterator end() { return m_Vector.end(); } - /** - * Get the last element of a constant vector - * @return A const iterator object pointing to the last element of the vector - */ + /// Get the last element of a constant vector + /// @return A const iterator object pointing to the last element of the vector ConstVectorIterator end() const { return m_Vector.end(); } - /** - * Get number of elements in the vector - * @return The number of elements in the vector - */ + /// Get number of elements in the vector + /// @return The number of elements in the vector size_t size() const { return m_Vector.size(); } - /** - * @return A pointer of the first element in the vector - */ + /// @return A pointer of the first element in the vector T* front() { return m_Vector.front(); } - /** - * @return A pointer to the first element in the vector - */ + /// @return A pointer to the first element in the vector T const* front() const { return m_Vector.front(); } - /** - * @return A pointer to the last element in the vector - */ + /// @return A pointer to the last element in the vector T* back() { return m_Vector.back(); } - /* - * @return A pointer to the last element in the vector. - */ + /// @return A pointer to the last element in the vector. T const* back() const { return m_Vector.back(); } - /** - * Removes from the vector a single element (position). Once the element is erased, it's also freed - * @param[in] position The position of the element to erase - * @return An iterator pointing to the new location of the element that followed the last element erased by the - * function call - */ + /// Removes from the vector a single element (position). Once the element is erased, it's also freed + /// @param[in] position The position of the element to erase + /// @return An iterator pointing to the new location of the element that followed the last element erased by the + /// function call VectorIterator erase(VectorIterator position) { delete (*position); return m_Vector.erase(position); } - /** - * Remove an element from the vector without freeing it - * @param[in, out] position The position of the element to remove from the vector. - * The iterator is shifted to the following element after the removal is completed. - * @return A pointer to the element which is no longer managed by the vector. It's user responsibility to free - * it - * @deprecated Deprecated in favor of 'getAndDetach' as that function provides memory safety. - */ + /// Remove an element from the vector without freeing it + /// @param[in, out] position The position of the element to remove from the vector. + /// The iterator is shifted to the following element after the removal is completed. + /// @return A pointer to the element which is no longer managed by the vector. It's user responsibility to free + /// it + /// @deprecated Deprecated in favor of 'getAndDetach' as that function provides memory safety. PCPP_DEPRECATED("Please use the memory safe 'getAndDetach' instead.") T* getAndRemoveFromVector(VectorIterator& position) { @@ -308,22 +255,18 @@ namespace pcpp return result; } - /** - * Removes an element from the vector and transfers ownership to the returned unique pointer. - * @param[in] index The index of the element to detach. - * @return An unique pointer that holds ownership of the detached element. - */ + /// Removes an element from the vector and transfers ownership to the returned unique pointer. + /// @param[in] index The index of the element to detach. + /// @return An unique pointer that holds ownership of the detached element. std::unique_ptr getAndDetach(size_t index) { return getAndDetach(m_Vector.begin() + index); } - /** - * Removes an element from the vector and transfers ownership to the returned unique pointer. - * @param[in, out] position An iterator pointing to the element to detach. - * The iterator is shifted to the following element after the detach completes. - * @return An unique pointer that holds ownership of the detached element. - */ + /// Removes an element from the vector and transfers ownership to the returned unique pointer. + /// @param[in, out] position An iterator pointing to the element to detach. + /// The iterator is shifted to the following element after the detach completes. + /// @return An unique pointer that holds ownership of the detached element. std::unique_ptr getAndDetach(VectorIterator& position) { std::unique_ptr result(*position); @@ -331,11 +274,9 @@ namespace pcpp return result; } - /** - * Removes an element from the vector and transfers ownership to the returned unique pointer. - * @param[in] position An iterator pointing to the element to detach. - * @return An unique pointer that holds ownership of the detached element. - */ + /// Removes an element from the vector and transfers ownership to the returned unique pointer. + /// @param[in] position An iterator pointing to the element to detach. + /// @return An unique pointer that holds ownership of the detached element. std::unique_ptr getAndDetach(VectorIterator const& position) { std::unique_ptr result(*position); @@ -343,32 +284,26 @@ namespace pcpp return result; } - /** - * Return a pointer to the element in a certain index - * @param[in] index The index to retrieve the element from - * @return The element at the specified position in the vector - */ + /// Return a pointer to the element in a certain index + /// @param[in] index The index to retrieve the element from + /// @return The element at the specified position in the vector T* at(int index) { return m_Vector.at(index); } - /** - * Return a const pointer to the element in a certain index - * @param[in] index The index to retrieve the element from - * @return The element at the specified position in the vector - */ + /// Return a const pointer to the element in a certain index + /// @param[in] index The index to retrieve the element from + /// @return The element at the specified position in the vector const T* at(int index) const { return m_Vector.at(index); } private: - /** - * Performs a copy of the vector along with its elements. - * The caller is responsible of freeing the copied elements. - * @return A vector of pointers to the newly copied elements. - */ + /// Performs a copy of the vector along with its elements. + /// The caller is responsible of freeing the copied elements. + /// @return A vector of pointers to the newly copied elements. static std::vector deepCopyUnsafe(std::vector const& origin) { std::vector copyVec; @@ -396,12 +331,10 @@ namespace pcpp return copyVec; } - /** - * Frees all elements inside the vector. - * Calling this function with non-heap allocated pointers is UB. - * @param[in] origin The vector of elements to free. - * @remarks The vector's contents are not cleared and will point to invalid locations in memory. - */ + /// Frees all elements inside the vector. + /// Calling this function with non-heap allocated pointers is UB. + /// @param[in] origin The vector of elements to free. + /// @remarks The vector's contents are not cleared and will point to invalid locations in memory. static void freeVectorUnsafe(std::vector const& origin) { for (auto& obj : origin) diff --git a/Common++/header/SystemUtils.h b/Common++/header/SystemUtils.h index c68ab8f777..bd557ca824 100644 --- a/Common++/header/SystemUtils.h +++ b/Common++/header/SystemUtils.h @@ -12,301 +12,192 @@ int gettimeofday(struct timeval* tp, struct timezone* tzp); #endif -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * @struct SystemCore - * Represents data of 1 CPU core. Current implementation supports up to 32 cores - */ + /// @struct SystemCore + /// Represents data of 1 CPU core. Current implementation supports up to 32 cores struct SystemCore { - /** - * Core position in a 32-bit mask. For each core this attribute holds a 4B integer where only 1 bit is set, - * according to the core ID. For example: - * - In core #0 the right-most bit will be set (meaning the number 0x01); - * - in core #5 the 5th right-most bit will be set (meaning the number 0x20) - */ + + /// Core position in a 32-bit mask. For each core this attribute holds a 4B integer where only 1 bit is set, + /// according to the core ID. For example: + /// - In core #0 the right-most bit will be set (meaning the number 0x01); + /// - in core #5 the 5th right-most bit will be set (meaning the number 0x20) uint32_t Mask; - /** - * Core ID - a value between 0 and 31 - */ + /// Core ID - a value between 0 and 31 uint8_t Id; - /** - * Overload of the comparison operator - * @return true if 2 addresses are equal. False otherwise - */ + /// Overload of the comparison operator + /// @return true if 2 addresses are equal. False otherwise bool operator==(const SystemCore& other) const { return Id == other.Id; } }; - /** - * @struct SystemCores - * Contains static representation to all 32 cores and a static array to map core ID (integer) to a SystemCore struct - */ + /// @struct SystemCores + /// Contains static representation to all 32 cores and a static array to map core ID (integer) to a SystemCore + /// struct struct SystemCores { - /** - * Static representation of core #0 - */ + /// Static representation of core #0 static const SystemCore Core0; - /** - * Static representation of core #1 - */ + /// Static representation of core #1 static const SystemCore Core1; - /** - * Static representation of core #2 - */ + /// Static representation of core #2 static const SystemCore Core2; - /** - * Static representation of core #3 - */ + /// Static representation of core #3 static const SystemCore Core3; - /** - * Static representation of core #4 - */ + /// Static representation of core #4 static const SystemCore Core4; - /** - * Static representation of core #5 - */ + /// Static representation of core #5 static const SystemCore Core5; - /** - * Static representation of core #6 - */ + /// Static representation of core #6 static const SystemCore Core6; - /** - * Static representation of core #7 - */ + /// Static representation of core #7 static const SystemCore Core7; - /** - * Static representation of core #8 - */ + /// Static representation of core #8 static const SystemCore Core8; - /** - * Static representation of core #9 - */ + /// Static representation of core #9 static const SystemCore Core9; - /** - * Static representation of core #10 - */ + /// Static representation of core #10 static const SystemCore Core10; - /** - * Static representation of core #11 - */ + /// Static representation of core #11 static const SystemCore Core11; - /** - * Static representation of core #12 - */ + /// Static representation of core #12 static const SystemCore Core12; - /** - * Static representation of core #13 - */ + /// Static representation of core #13 static const SystemCore Core13; - /** - * Static representation of core #14 - */ + /// Static representation of core #14 static const SystemCore Core14; - /** - * Static representation of core #15 - */ + /// Static representation of core #15 static const SystemCore Core15; - /** - * Static representation of core #16 - */ + /// Static representation of core #16 static const SystemCore Core16; - /** - * Static representation of core #17 - */ + /// Static representation of core #17 static const SystemCore Core17; - /** - * Static representation of core #18 - */ + /// Static representation of core #18 static const SystemCore Core18; - /** - * Static representation of core #19 - */ + /// Static representation of core #19 static const SystemCore Core19; - /** - * Static representation of core #20 - */ + /// Static representation of core #20 static const SystemCore Core20; - /** - * Static representation of core #21 - */ + /// Static representation of core #21 static const SystemCore Core21; - /** - * Static representation of core #22 - */ + /// Static representation of core #22 static const SystemCore Core22; - /** - * Static representation of core #23 - */ + /// Static representation of core #23 static const SystemCore Core23; - /** - * Static representation of core #24 - */ + /// Static representation of core #24 static const SystemCore Core24; - /** - * Static representation of core #25 - */ + /// Static representation of core #25 static const SystemCore Core25; - /** - * Static representation of core #26 - */ + /// Static representation of core #26 static const SystemCore Core26; - /** - * Static representation of core #27 - */ + /// Static representation of core #27 static const SystemCore Core27; - /** - * Static representation of core #28 - */ + /// Static representation of core #28 static const SystemCore Core28; - /** - * Static representation of core #29 - */ + /// Static representation of core #29 static const SystemCore Core29; - /** - * Static representation of core #30 - */ + /// Static representation of core #30 static const SystemCore Core30; - /** - * Static representation of core #31 - */ + /// Static representation of core #31 static const SystemCore Core31; - - /** - * A static array for mapping core ID (integer) to the corresponding static SystemCore representation - */ + /// A static array for mapping core ID (integer) to the corresponding static SystemCore representation static const SystemCore IdToSystemCore[MAX_NUM_OF_CORES]; }; typedef uint32_t CoreMask; - /** - * Get total number of cores on device - * @return Total number of CPU cores on device - */ + /// Get total number of cores on device + /// @return Total number of CPU cores on device int getNumOfCores(); - /** - * Create a core mask for all cores available on machine - * @return A core mask for all cores available on machine - */ + /// Create a core mask for all cores available on machine + /// @return A core mask for all cores available on machine CoreMask getCoreMaskForAllMachineCores(); - /** - * Create a core mask from a vector of system cores - * @param[in] cores A vector of SystemCore instances - * @return A core mask representing these cores - */ + /// Create a core mask from a vector of system cores + /// @param[in] cores A vector of SystemCore instances + /// @return A core mask representing these cores CoreMask createCoreMaskFromCoreVector(const std::vector& cores); - /** - * Create a core mask from a vector of core IDs - * @param[in] coreIds A vector of core IDs - * @return A core mask representing these cores - */ + /// Create a core mask from a vector of core IDs + /// @param[in] coreIds A vector of core IDs + /// @return A core mask representing these cores CoreMask createCoreMaskFromCoreIds(const std::vector& coreIds); - /** - * Convert a core mask into a vector of its appropriate system cores - * @param[in] coreMask The input core mask - * @param[out] resultVec The vector that will contain the system cores - */ + /// Convert a core mask into a vector of its appropriate system cores + /// @param[in] coreMask The input core mask + /// @param[out] resultVec The vector that will contain the system cores void createCoreVectorFromCoreMask(CoreMask coreMask, std::vector& resultVec); - /** - * Execute a shell command and return its output - * @param[in] command The command to run - * @return The output of the command (both stdout and stderr) - * @throws std::runtime_error Error executing the command. - */ + /// Execute a shell command and return its output + /// @param[in] command The command to run + /// @return The output of the command (both stdout and stderr) + /// @throws std::runtime_error Error executing the command. std::string executeShellCommand(const std::string& command); - /** - * Check if a directory exists - * @param[in] dirPath Full path of the directory to search - * @return True if directory exists, false otherwise - */ + /// Check if a directory exists + /// @param[in] dirPath Full path of the directory to search + /// @return True if directory exists, false otherwise bool directoryExists(const std::string& dirPath); - /** - * Retrieve a system-wide real-time accurate clock. It's actually a multi-platform version of clock_gettime() which - * is fully supported only on Linux - * @param[out] sec The second portion of the time - * @param[out] nsec The nanosecond portion of the time - * @return 0 for success, or -1 for failure - */ + /// Retrieve a system-wide real-time accurate clock. It's actually a multi-platform version of clock_gettime() which + /// is fully supported only on Linux + /// @param[out] sec The second portion of the time + /// @param[out] nsec The nanosecond portion of the time + /// @return 0 for success, or -1 for failure int clockGetTime(long& sec, long& nsec); - /** - * A multi-platform version of the popular sleep method. This method simply runs the right sleep method, according - * to the platform it is running on. - * @param[in] seconds Number of seconds to sleep - */ + /// A multi-platform version of the popular sleep method. This method simply runs the right sleep method, according + /// to the platform it is running on. + /// @param[in] seconds Number of seconds to sleep void multiPlatformSleep(uint32_t seconds); - /** - * A multi-platform version of sleep in milliseconds resolution. This method simply runs the right sleep method, - * according to the platform it is running on. - * @param[in] milliseconds Number of milliseconds to sleep - */ + /// A multi-platform version of sleep in milliseconds resolution. This method simply runs the right sleep method, + /// according to the platform it is running on. + /// @param[in] milliseconds Number of milliseconds to sleep void multiPlatformMSleep(uint32_t milliseconds); - /** - * A multi-platform version of `htons` which convert host to network byte order - * @param[in] host Value in host byte order - * @return Value in network byte order - */ + /// A multi-platform version of `htons` which convert host to network byte order + /// @param[in] host Value in host byte order + /// @return Value in network byte order uint16_t hostToNet16(uint16_t host); - /** - * A multi-platform version of `ntohs` which convert network to host byte order - * @param[in] net Value in network byte order - * @return Value in host byte order - */ + /// A multi-platform version of `ntohs` which convert network to host byte order + /// @param[in] net Value in network byte order + /// @return Value in host byte order uint16_t netToHost16(uint16_t net); - /** - * A multi-platform version of `htonl` which convert host to network byte order - * @param[in] host Value in host byte order - * @return Value in network byte order - */ + /// A multi-platform version of `htonl` which convert host to network byte order + /// @param[in] host Value in host byte order + /// @return Value in network byte order uint32_t hostToNet32(uint32_t host); - /** - * A multi-platform version of `ntohl` which convert network to host byte order - * @param[in] net Value in network byte order - * @return Value in host byte order - */ + /// A multi-platform version of `ntohl` which convert network to host byte order + /// @param[in] net Value in network byte order + /// @return Value in host byte order uint32_t netToHost32(uint32_t net); - /** - * @class AppName - * This class extracts the application name from the current running executable and stores it for usage of the - * application throughout its runtime. This class should be initialized once in the beginning of the main() method - * using AppName#init() and from then on the app name could be retrieved using AppName#get() - */ + /// @class AppName + /// This class extracts the application name from the current running executable and stores it for usage of the + /// application throughout its runtime. This class should be initialized once in the beginning of the main() method + /// using AppName#init() and from then on the app name could be retrieved using AppName#get() class AppName { private: static std::string m_AppName; public: - /** - * Static init method which should be called once at the beginning of the main method. - * @param[in] argc The argc param from main() - * @param[in] argv The argv param from main() - */ + /// Static init method which should be called once at the beginning of the main method. + /// @param[in] argc The argc param from main() + /// @param[in] argv The argv param from main() // cppcheck-suppress constParameter static void init(int argc, char* argv[]) { @@ -340,47 +231,37 @@ namespace pcpp } } - /** - * @return The app name as extracted from the current running executable - */ + /// @return The app name as extracted from the current running executable static const std::string& get() { return m_AppName; } }; - /** - * @class ApplicationEventHandler - * A singleton class that provides callbacks for events that occur during application life-cycle such as ctrl+c - * pressed, application closed, killed, etc. - */ + /// @class ApplicationEventHandler + /// A singleton class that provides callbacks for events that occur during application life-cycle such as ctrl+c + /// pressed, application closed, killed, etc. class ApplicationEventHandler { public: - /** - * @typedef EventHandlerCallback - * The callback to be invoked when the event occurs - * @param[in] cookie A pointer the the cookie provided by the user in ApplicationEventHandler c'tor - */ + /// @typedef EventHandlerCallback + /// The callback to be invoked when the event occurs + /// @param[in] cookie A pointer the the cookie provided by the user in ApplicationEventHandler c'tor typedef void (*EventHandlerCallback)(void* cookie); - /** - * As ApplicationEventHandler is a singleton, this is the static getter to retrieve its instance - * @return The singleton instance of ApplicationEventHandler - */ + /// As ApplicationEventHandler is a singleton, this is the static getter to retrieve its instance + /// @return The singleton instance of ApplicationEventHandler static ApplicationEventHandler& getInstance() { static ApplicationEventHandler instance; return instance; } - /** - * Register for an application-interrupted event, meaning ctrl+c was pressed - * @param[in] handler The callback to be activated when the event occurs - * @param[in] cookie A pointer to a user provided object. This object will be transferred to the - * EventHandlerCallback callback. This cookie is very useful for transferring objects that give context to the - * event callback - */ + /// Register for an application-interrupted event, meaning ctrl+c was pressed + /// @param[in] handler The callback to be activated when the event occurs + /// @param[in] cookie A pointer to a user provided object. This object will be transferred to the + /// EventHandlerCallback callback. This cookie is very useful for transferring objects that give context to the + /// event callback void onApplicationInterrupted(EventHandlerCallback handler, void* cookie); private: diff --git a/Common++/header/TablePrinter.h b/Common++/header/TablePrinter.h index d34ec0df51..620b7dd6e7 100644 --- a/Common++/header/TablePrinter.h +++ b/Common++/header/TablePrinter.h @@ -1,61 +1,47 @@ #pragma once +#include #include /// @file -/** - * \namespace pcpp - * \brief The main namespace for the PcapPlusPlus lib - */ +/// @namespace pcpp +/// @brief The main namespace for the PcapPlusPlus lib namespace pcpp { - /** - * A class for printing tables in command-line - */ + + /// A class for printing tables in command-line class TablePrinter { public: - /** - * C'tor - get column names and column widths - * @param[in] columnNames A vector of strings containing column names - * @param[in] columnWidths A vector of integers containing column widths - */ + /// C'tor - get column names and column widths + /// @param[in] columnNames A vector of strings containing column names + /// @param[in] columnWidths A vector of integers containing column widths TablePrinter(std::vector columnNames, std::vector columnWidths); - /** - * A d'tor for this class. Closes the table if not closed - */ + /// A d'tor for this class. Closes the table if not closed virtual ~TablePrinter(); - /** - * Print a single row by providing a single string containing all values delimited by a specified character. - * For example: if specified delimiter is '|' and there are 3 columns an example input can be: - * "value for column1|value for column2|value for column3" - * @param[in] values A string delimited by a specified delimiter that contains values for all columns - * @param[in] delimiter A delimiter that separates between values of different columns in the values string - * @return True if row was printed successfully or false otherwise (in any case of error an appropriate message - * will be printed to log) - */ + /// Print a single row by providing a single string containing all values delimited by a specified character. + /// For example: if specified delimiter is '|' and there are 3 columns an example input can be: + /// "value for column1|value for column2|value for column3" + /// @param[in] values A string delimited by a specified delimiter that contains values for all columns + /// @param[in] delimiter A delimiter that separates between values of different columns in the values string + /// @return True if row was printed successfully or false otherwise (in any case of error an appropriate message + /// will be printed to log) bool printRow(const std::string& values, char delimiter); - /** - * Print a single row - * @param[in] values A vector of strings containing values for all columns - * @return True if row was printed successfully or false otherwise (in any case of error an appropriate message - * will be printed to log) - */ + /// Print a single row + /// @param[in] values A vector of strings containing values for all columns + /// @return True if row was printed successfully or false otherwise (in any case of error an appropriate message + /// will be printed to log) bool printRow(std::vector values); - /** - * Print a separator line - */ + /// Print a separator line void printSeparator(); - /** - * Close the table - should be called after all rows were printed. Calling this method is not a must as it's - * called in the class d'tor - */ + /// Close the table - should be called after all rows were printed. Calling this method is not a must as it's + /// called in the class d'tor void closeTable(); private: @@ -64,9 +50,7 @@ namespace pcpp bool m_FirstRow; bool m_TableClosed; - /** - * Print the table headline - */ + /// Print the table headline void printHeadline(); }; diff --git a/Common++/src/SystemUtils.cpp b/Common++/src/SystemUtils.cpp index 13f2d68caa..9a5bc84a92 100644 --- a/Common++/src/SystemUtils.cpp +++ b/Common++/src/SystemUtils.cpp @@ -54,10 +54,9 @@ int gettimeofday(struct timeval* tp, struct timezone* tzp) namespace { - /** - * @class PcloseDeleter - * A deleter that cleans up a FILE handle using pclose. - */ + + /// @class PcloseDeleter + /// A deleter that cleans up a FILE handle using pclose. struct PcloseDeleter { void operator()(FILE* ptr) const