/src/PcapPlusPlus/Common++/header/MacAddress.h

Source (jump to first uncovered line)
#pragma once

#include <algorithm>
#include <initializer_list>
#include <iterator>
#include <ostream>
#include <cstdint>
#include <string>
#include <array>
#include <memory>

#include "DeprecationUtils.h"

/// @file

/// @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
  {
  public:
    /// 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
    /// @remarks This constructor assumes that the provided array is exactly 6 bytes long.
    /// Prefer using the constructor with size parameter if the array length is not guaranteed to be 6 bytes.
    explicit MacAddress(const uint8_t addr[6]) : MacAddress(addr, 6)
    {}

    /// @brief A constructor that creates an instance of the class out of a byte array of 6 bytes.
    /// @param[in] addr The address as a byte array in network byte order
    /// @param[in] size The size of the array in bytes
    /// @throws std::invalid_argument If the address pointer is null.
    /// @throws std::out_of_range If the provided size is smaller than 6 bytes.
    explicit MacAddress(const uint8_t* addr, size_t size);

    /// A constructor that creates an instance of the class out of a std::array.
    /// The array length should be 6 (as MAC address is 6-byte long).
    /// @param [in] addr A std::array containing 6 bytes representing the MAC address
    explicit MacAddress(const std::array<uint8_t, 6>& addr) : m_Address(addr)
    {}

    /// 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"
    template <typename T, typename = typename std::enable_if<std::is_convertible<T, std::string>::value>::type>
    MacAddress(const T& addr) : MacAddress(static_cast<std::string>(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
    MacAddress(uint8_t firstOctet, uint8_t secondOctet, uint8_t thirdOctet, uint8_t fourthOctet, uint8_t fifthOctet,
               uint8_t sixthOctet)
        : m_Address{ firstOctet, secondOctet, thirdOctet, fourthOctet, fifthOctet, 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
    MacAddress(std::initializer_list<uint8_t> octets)
    {
      if (octets.size() != m_Address.size())
      {
        throw std::invalid_argument("Invalid initializer list size, should be 6");
      }
      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
    bool operator==(const MacAddress& other) const
    {
      return m_Address == other.m_Address;
    }

    /// 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
    MacAddress& operator=(std::initializer_list<uint8_t> octets)
    {
      if (octets.size() != sizeof(m_Address))
      {
        throw std::invalid_argument("Invalid initializer list size, should be 6");
      }

      std::copy(octets.begin(), octets.end(), m_Address.begin());
      return *this;
    }

    /// Returns the pointer to raw data
    /// @return The pointer to raw data
    const uint8_t* getRawData() const
    {
      return m_Address.data();
    }

    /// Returns a std::string representation of the address
    /// @return A string representation of the address
    std::string toString() const;

    /// @return A 6-byte integer representing the MAC address
    std::array<uint8_t, 6> toByteArray() const
    {
      return m_Address;
    }

    /// 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
    /// @throws std::invalid_argument If the buffer pointer is null.
    /// @deprecated Use copyToNewBuffer instead.
    PCPP_DEPRECATED("Use copyToNewBuffer instead.")
    void copyTo(uint8_t** arr) const
    {
      size_t unused = 0;
      copyToNewBuffer(arr, unused);
    }

    /// 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
    /// @remarks This method assumes that the provided array is at least 6 bytes long.
    /// Prefer using the copyTo(uint8_t* buffer, size_t size) method if the array length is not guaranteed to be 6
    /// bytes.
    void copyTo(uint8_t arr[6]) const
    {
      copyTo(arr, 6);
    }

    /// @brief Copies the address value to a user-provided buffer.
    ///
    /// This function supports querying. If the buffer is null and size is zero, it returns the required size.
    ///
    /// @param[in] buffer A pointer to the buffer where the address will be copied
    /// @param[in] size The size of the buffer in bytes
    /// @return The number of bytes copied to the buffer or the required size if the buffer is too small.
    /// @throws std::invalid_argument If the provided buffer is null and size is not zero.
    size_t copyTo(uint8_t* buffer, size_t size) const;

    /// @brief Allocates a new buffer and copies the address value to it.
    /// The user is responsible for deallocating the buffer.
    ///
    /// @param buffer A pointer to a pointer where the new buffer will be allocated
    /// @param size A reference to a size_t variable that will be updated with the size of the allocated buffer
    /// @return True if the buffer was successfully allocated and the address was copied, false otherwise.
    /// @throws std::invalid_argument If the buffer pointer is null.
    bool copyToNewBuffer(uint8_t** buffer, size_t& size) const;

    /// A static value representing a zero value of MAC address, meaning address of value "00:00:00:00:00:00"
    static MacAddress Zero;
    /// A static value representing a broadcast MAC address, meaning address of value "ff:ff:ff:ff:ff:ff"
    static MacAddress Broadcast;

  private:
    std::array<uint8_t, 6> m_Address{};
  };

  inline std::ostream& operator<<(std::ostream& oss, const pcpp::MacAddress& macAddress)
  {
    oss << macAddress.toString();
    return oss;
  }
}  // namespace pcpp

Line	Count	Source (jump to first uncovered line)
1		#pragma once
2
3		#include <algorithm>
4		#include <initializer_list>
5		#include <iterator>
6		#include <ostream>
7		#include <cstdint>
8		#include <string>
9		#include <array>
10		#include <memory>
11
12		#include "DeprecationUtils.h"
13
14		/// @file
15
16		/// @namespace pcpp
17		/// @brief The main namespace for the PcapPlusPlus lib
18		namespace pcpp
19		{
20
21		/// @class MacAddress
22		/// Represents L2 MAC addresses. Can be constructed from string or a series of 6 byte octets
23		class MacAddress
24		{
25		public:
26		/// Default constructor for this class.
27		/// Initializes the address as 00:00:00:00:00:00.
28		MacAddress() = default;
29
30		/// A constructor that creates an instance of the class out of a byte array.
31		/// The byte array length should be 6 (as MAC address is 6-byte long), and the remaining bytes are ignored.
32		/// If the byte array is invalid, the constructor throws an exception.
33		/// @param[in] addr A pointer to the byte array containing 6 bytes representing the MAC address
34		/// @remarks This constructor assumes that the provided array is exactly 6 bytes long.
35		/// Prefer using the constructor with size parameter if the array length is not guaranteed to be 6 bytes.
36		explicit MacAddress(const uint8_t addr[6]) : MacAddress(addr, 6)
37	0	{}
38
39		/// @brief A constructor that creates an instance of the class out of a byte array of 6 bytes.
40		/// @param[in] addr The address as a byte array in network byte order
41		/// @param[in] size The size of the array in bytes
42		/// @throws std::invalid_argument If the address pointer is null.
43		/// @throws std::out_of_range If the provided size is smaller than 6 bytes.
44		explicit MacAddress(const uint8_t* addr, size_t size);
45
46		/// A constructor that creates an instance of the class out of a std::array.
47		/// The array length should be 6 (as MAC address is 6-byte long).
48		/// @param [in] addr A std::array containing 6 bytes representing the MAC address
49		explicit MacAddress(const std::array<uint8_t, 6>& addr) : m_Address(addr)
50	0	{}
51
52		/// A constructor that creates an instance of the class out of a std::string.
53		/// If the string doesn't represent a valid MAC address, the constructor throws an exception.
54		/// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00"
55		explicit MacAddress(const std::string& addr);
56
57		/// A template constructor that creates an instance of the class out of a string convertible to std::string.
58		/// If the string doesn't represent a valid MAC address, the constructor throws an exception.
59		/// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00"
60		template <typename T, typename = typename std::enable_if<std::is_convertible<T, std::string>::value>::type>
61		MacAddress(const T& addr) : MacAddress(static_cast<std::string>(addr))
62		{}
63
64		/// A constructor that creates an instance of 6 bytes representing the MAC address
65		/// @param[in] firstOctet Represent the first octet in the address
66		/// @param[in] secondOctet Represent the second octet in the address
67		/// @param[in] thirdOctet Represent the third octet in the address
68		/// @param[in] fourthOctet Represent the fourth octet in the address
69		/// @param[in] fifthOctet Represent the fifth octet in the address
70		/// @param[in] sixthOctet Represent the sixth octet in the address
71		MacAddress(uint8_t firstOctet, uint8_t secondOctet, uint8_t thirdOctet, uint8_t fourthOctet, uint8_t fifthOctet,
72		uint8_t sixthOctet)
73	4	: m_Address{ firstOctet, secondOctet, thirdOctet, fourthOctet, fifthOctet, sixthOctet }
74	4	{}
75
76		/// A constructor that creates an instance out of the initializer list.
77		/// The byte list length should be 6 (as MAC address is 6-byte long).
78		/// If the list is invalid, the constructor throws an exception.
79		/// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address
80		MacAddress(std::initializer_list<uint8_t> octets)
81	0	{
82	0	if (octets.size() != m_Address.size())
83	0	{
84	0	throw std::invalid_argument("Invalid initializer list size, should be 6");
85	0	}
86	0	std::copy(octets.begin(), octets.end(), std::begin(m_Address));
87	0	}
88
89		/// Overload of the comparison operator.
90		/// @param[in] other The object to compare with
91		/// @return True if addresses are equal, false otherwise
92		bool operator==(const MacAddress& other) const
93	0	{
94	0	return m_Address == other.m_Address;
95	0	}
96
97		/// Overload of the not-equal operator
98		/// @param[in] other The object to compare with
99		/// @return True if addresses are not equal, false otherwise
100		bool operator!=(const MacAddress& other) const
101	0	{
102	0	return !operator==(other);
103	0	}
104
105		/// Overload of the assignment operator.
106		/// If the list is invalid, the constructor throws an exception.
107		/// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address,
108		/// the length of the list must be equal to 6
109		MacAddress& operator=(std::initializer_list<uint8_t> octets)
110	0	{
111	0	if (octets.size() != sizeof(m_Address))
112	0	{
113	0	throw std::invalid_argument("Invalid initializer list size, should be 6");
114	0	}
115	0
116	0	std::copy(octets.begin(), octets.end(), m_Address.begin());
117	0	return *this;
118	0	}
119
120		/// Returns the pointer to raw data
121		/// @return The pointer to raw data
122		const uint8_t* getRawData() const
123	0	{
124	0	return m_Address.data();
125	0	}
126
127		/// Returns a std::string representation of the address
128		/// @return A string representation of the address
129		std::string toString() const;
130
131		/// @return A 6-byte integer representing the MAC address
132		std::array<uint8_t, 6> toByteArray() const
133	0	{
134	0	return m_Address;
135	0	}
136
137		/// Allocates a byte array of length 6 and copies address value into it. Array deallocation is user
138		/// responsibility
139		/// @param[in] arr A pointer to where array will be allocated
140		/// @throws std::invalid_argument If the buffer pointer is null.
141		/// @deprecated Use copyToNewBuffer instead.
142		PCPP_DEPRECATED("Use copyToNewBuffer instead.")
143		void copyTo(uint8_t** arr) const
144	0	{
145	0	size_t unused = 0;
146	0	copyToNewBuffer(arr, unused);
147	0	}
148
149		/// Gets a pointer to an already allocated byte array and copies the address value to it.
150		/// This method assumes array allocated size is at least 6 (the size of a MAC address)
151		/// @param[in] arr A pointer to the array which address will be copied to
152		/// @remarks This method assumes that the provided array is at least 6 bytes long.
153		/// Prefer using the copyTo(uint8_t* buffer, size_t size) method if the array length is not guaranteed to be 6
154		/// bytes.
155		void copyTo(uint8_t arr[6]) const
156	0	{
157	0	copyTo(arr, 6);
158	0	}
159
160		/// @brief Copies the address value to a user-provided buffer.
161		///
162		/// This function supports querying. If the buffer is null and size is zero, it returns the required size.
163		///
164		/// @param[in] buffer A pointer to the buffer where the address will be copied
165		/// @param[in] size The size of the buffer in bytes
166		/// @return The number of bytes copied to the buffer or the required size if the buffer is too small.
167		/// @throws std::invalid_argument If the provided buffer is null and size is not zero.
168		size_t copyTo(uint8_t* buffer, size_t size) const;
169
170		/// @brief Allocates a new buffer and copies the address value to it.
171		/// The user is responsible for deallocating the buffer.
172		///
173		/// @param buffer A pointer to a pointer where the new buffer will be allocated
174		/// @param size A reference to a size_t variable that will be updated with the size of the allocated buffer
175		/// @return True if the buffer was successfully allocated and the address was copied, false otherwise.
176		/// @throws std::invalid_argument If the buffer pointer is null.
177		bool copyToNewBuffer(uint8_t** buffer, size_t& size) const;
178
179		/// A static value representing a zero value of MAC address, meaning address of value "00:00:00:00:00:00"
180		static MacAddress Zero;
181		/// A static value representing a broadcast MAC address, meaning address of value "ff:ff:ff:ff:ff:ff"
182		static MacAddress Broadcast;
183
184		private:
185		std::array<uint8_t, 6> m_Address{};
186		};
187
188		inline std::ostream& operator<<(std::ostream& oss, const pcpp::MacAddress& macAddress)
189	0	{
190	0	oss << macAddress.toString();
191	0	return oss;
192	0	}
193		} // namespace pcpp

Coverage Report

Created: 2025-07-18 06:14