Added sized overloads for buffer construction of IPv6Address and MacAddress. (#1847)

* Added sized overloads of copyTo and constructor for IPAddress and MacAddress.

Deprecated allocating copyTo method.

* Updated mac test.

* Header fix.

* Doc improvement.

* Fixed docs.

* Fixed docs.

* Doc fix.

* Deprecated allocating API.
Updated non-allocating copyTo API to return written bytes.

* Lint

* Updated sized MacAddress ctor. Added tests.

* Updated raw array to smart ptr array.

* Added unit tests for copy to.

* Added safety checks on IPv4 and IPv6 buffer constructors.

* Fixed test

* Added unit tests for IPv6Address::copyTo

* Lint

* Returned allocating `copyTo` under the name `copyToNewBuffer`.

* Simplified tests.

* Added unit tests for copyToNewBuffer.

* Lint

* Typo fix

* Moved larger constructors to cpp files.

* Removed aliases

Author: Dimi1010

Common++/header/IpAddress.h

@@ -8,6 +8,8 @@
 #include <array>
 #include <memory>
 
+#include "DeprecationUtils.h"
+
 /// @file
 
 /// @namespace pcpp
@@ -39,10 +41,17 @@ namespace pcpp
 
 		/// 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));
-		}
+		/// @remarks This constructor assumes that the provided array is exactly 4 bytes long.
+		/// Prefer using the constructor with size parameter if the array length is not guaranteed to be 4 bytes.
+		IPv4Address(const uint8_t bytes[4]) : IPv4Address(bytes, 4)
+		{}
+
+		/// A constructor that creates an instance of the class out of a 4-byte array.
+		/// @param[in] bytes The address as 4-byte array in network byte order
+		/// @param[in] size The size of the array in bytes
+		/// @throws std::invalid_argument If the provided bytes pointer is null.
+		/// @throws std::out_of_range If the provided size is smaller than 4 bytes.
+		IPv4Address(const uint8_t* bytes, size_t size);
 
 		/// 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
@@ -160,10 +169,17 @@ namespace pcpp
 
 		/// 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));
-		}
+		/// @remarks This constructor assumes that the provided array is exactly 16 bytes long.
+		/// Prefer using the constructor with size parameter if the array length is not guaranteed to be 16 bytes.
+		IPv6Address(const uint8_t bytes[16]) : IPv6Address(bytes, 16)
+		{}
+
+		/// @brief A constructor that creates an instance of the class out of a 16-byte array.
+		/// @param bytes The address as 16-byte array in network byte order
+		/// @param size The size of the array in bytes
+		/// @throws std::invalid_argument If the provided buffer is null.
+		/// @throws std::out_of_range If the provided size is smaller than 16 bytes.
+		IPv6Address(const uint8_t* bytes, size_t size);
 
 		/// 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
@@ -224,15 +240,41 @@ namespace pcpp
 		/// 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
+		/// @throws std::invalid_argument If the provided pointer is null.
+		/// @deprecated Use copyToNewBuffer instead.
+		PCPP_DEPRECATED("Use copyToNewBuffer instead.")
 		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
+		/// @remarks This method assumes that the provided array is at least 16 bytes long.
+		/// Prefer using the copyTo(uint8_t* buffer, size_t size) method if the array length is not guaranteed to be 16
+		/// bytes.
 		void copyTo(uint8_t* arr) const
 		{
-			memcpy(arr, m_Bytes.data(), m_Bytes.size() * sizeof(uint8_t));
-		}
+			copyTo(arr, 16);
+		}
+
+		/// @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 number of required bytes, which is always 16 for
+		/// IPv6 addresses.
+		/// @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;
 
 		/// Checks whether the address matches a network.
 		/// @param network An IPv6Network network

Common++/header/MacAddress.h

@@ -7,6 +7,9 @@
 #include <cstdint>
 #include <string>
 #include <array>
+#include <memory>
+
+#include "DeprecationUtils.h"
 
 /// @file
 
@@ -28,10 +31,17 @@ namespace pcpp
 		/// 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[6])
-		{
-			std::copy(addr, addr + 6, m_Address.begin());
-		}
+		/// @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).
@@ -127,20 +137,45 @@ namespace pcpp
 		/// 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
 		{
-			*arr = new uint8_t[m_Address.size()];
-			std::copy(m_Address.begin(), m_Address.end(), *arr);
+			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
 		{
-			std::copy(m_Address.begin(), m_Address.end(), arr);
+			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"

Common++/src/IpAddress.cpp

@@ -46,6 +46,20 @@ namespace pcpp
 		       (operator<(MulticastRangeUpperBound) || operator==(MulticastRangeUpperBound));
 	}
 
+	IPv4Address::IPv4Address(const uint8_t* bytes, size_t size)
+	{
+		if (bytes == nullptr)
+		{
+			throw std::invalid_argument("Buffer pointer is null");
+		}
+
+		if (size < 4)
+		{
+			throw std::out_of_range("Buffer size is smaller than IPv4 address size");
+		}
+		memcpy(m_Bytes.data(), bytes, 4 * sizeof(uint8_t));
+	}
+
 	IPv4Address::IPv4Address(const std::string& addrAsString)
 	{
 		if (inet_pton(AF_INET, addrAsString.data(), m_Bytes.data()) <= 0)
@@ -101,6 +115,20 @@ namespace pcpp
 		return !operator<(MulticastRangeLowerBound);
 	}
 
+	IPv6Address::IPv6Address(const uint8_t* bytes, size_t size)
+	{
+		if (bytes == nullptr)
+		{
+			throw std::invalid_argument("Buffer pointer is null");
+		}
+
+		if (size < 16)
+		{
+			throw std::out_of_range("Buffer size is smaller than IPv6 address size");
+		}
+		std::memcpy(m_Bytes.data(), bytes, 16 * sizeof(uint8_t));
+	}
+
 	IPv6Address::IPv6Address(const std::string& addrAsString)
 	{
 		if (inet_pton(AF_INET6, addrAsString.data(), m_Bytes.data()) <= 0)
@@ -117,6 +145,49 @@ namespace pcpp
 		memcpy(*arr, m_Bytes.data(), addrLen);
 	}
 
+	size_t IPv6Address::copyTo(uint8_t* buffer, size_t size) const
+	{
+		const size_t requiredSize = m_Bytes.size();
+
+		if (buffer == nullptr)
+		{
+			if (size != 0)
+			{
+				throw std::invalid_argument("Buffer is null but size is not zero");
+			}
+
+			return requiredSize;
+		}
+
+		if (size < requiredSize)
+		{
+			return requiredSize;
+		}
+
+		std::memcpy(buffer, m_Bytes.data(), requiredSize);
+		return requiredSize;
+	}
+
+	bool IPv6Address::copyToNewBuffer(uint8_t** buffer, size_t& size) const
+	{
+		if (buffer == nullptr)
+		{
+			throw std::invalid_argument("Buffer pointer is null");
+		}
+
+		size = copyTo(nullptr, 0);
+		*buffer = new uint8_t[size];
+		if (copyTo(*buffer, size) != size)
+		{
+			delete[] *buffer;
+			*buffer = nullptr;
+			size = 0;
+			return false;
+		}
+
+		return true;
+	}
+
 	bool IPv6Address::matchNetwork(const IPv6Network& network) const
 	{
 		return network.includes(*this);

Common++/src/MacAddress.cpp

@@ -18,6 +18,21 @@ namespace pcpp
 		return str;
 	}
 
+	MacAddress::MacAddress(const uint8_t* addr, size_t size)
+	{
+		if (addr == nullptr)
+		{
+			throw std::invalid_argument("Address pointer is null");
+		}
+
+		if (size < 6)
+		{
+			throw std::out_of_range("Buffer size is smaller than MAC address size (6 bytes)");
+		}
+
+		std::copy(addr, addr + 6, m_Address.begin());
+	}
+
 	MacAddress::MacAddress(const std::string& address)
 	{
 		constexpr size_t validMacAddressLength = 17;
@@ -35,4 +50,42 @@ namespace pcpp
 		}
 	}
 
+	size_t MacAddress::copyTo(uint8_t* buffer, size_t size) const
+	{
+		const size_t requiredSize = m_Address.size();
+		if (buffer == nullptr)
+		{
+			if (size != 0)
+			{
+				throw std::invalid_argument("Buffer is null but size is not zero");
+			}
+			return requiredSize;
+		}
+		if (size < m_Address.size())
+		{
+			return requiredSize;
+		}
+		std::copy(m_Address.begin(), m_Address.end(), buffer);
+		return requiredSize;
+	}
+
+	bool MacAddress::copyToNewBuffer(uint8_t** buffer, size_t& size) const
+	{
+		if (buffer == nullptr)
+		{
+			throw std::invalid_argument("Buffer pointer is null");
+		}
+
+		size = copyTo(nullptr, 0);          // Get the required size
+		*buffer = new uint8_t[size];        // Allocate memory for the buffer
+		if (copyTo(*buffer, size) != size)  // Copy the address to the newly allocated buffer
+		{
+			delete[] *buffer;  // Clean up if copy fails
+			*buffer = nullptr;
+			size = 0;
+			return false;
+		}
+
+		return true;
+	}
 }  // namespace pcpp