Refactored overrides of WinPcapLiveDevice::startCapture. (#1832)

* Added an extension point `prepareCapture` allowing derived classes of `PcapLiveDevice` to run logic prior to initializing capture.

- Replaced WinPcapLiveDevice overrides of `startCapture` with a `prepareCapture` method.

* Added `final` qualifier to `startCapture` as a transitional step before converting the virtual methods to static.

* Removed final qualifier. Added a remarks section in startCapture comments.

* Changed usage to pcapDesciptor.getLastError()

Author: Dimi1010

Pcap++/header/PcapLiveDevice.h

@@ -404,6 +404,7 @@ namespace pcpp
 		/// - Capture is already running
 		/// - Device is not opened
 		/// - Capture thread could not be created
+		/// @remarks This method is planned for conversion to non-virtual in the future, so it should not be overridden.
 		virtual bool startCapture(OnPacketArrivesCallback onPacketArrives, void* onPacketArrivesUserCookie);
 
 		/// Start capturing packets on this network interface (device) with periodic stats collection. Each time a
@@ -428,6 +429,7 @@ namespace pcpp
 		/// - Device is not opened
 		/// - Capture thread could not be created
 		/// - Stats collection thread could not be created
+		/// @remarks This method is planned for conversion to non-virtual in the future, so it should not be overridden.
 		virtual bool startCapture(OnPacketArrivesCallback onPacketArrives, void* onPacketArrivesUserCookie,
 		                          int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate,
 		                          void* onStatsUpdateUserCookie);
@@ -448,6 +450,7 @@ namespace pcpp
 		/// - Capture is already running
 		/// - Device is not opened
 		/// - Stats collection thread could not be created
+		/// @remarks This method is planned for conversion to non-virtual in the future, so it should not be overridden.
 		virtual bool startCapture(int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate,
 		                          void* onStatsUpdateUserCookie);
 
@@ -464,6 +467,7 @@ namespace pcpp
 		/// - Capture is already running
 		/// - Device is not opened
 		/// - Capture thread could not be created
+		/// @remarks This method is planned for conversion to non-virtual in the future, so it should not be overridden.
 		virtual bool startCapture(RawPacketVector& capturedPacketsVector);
 
 		/// Start capturing packets on this network interface (device) in blocking mode, meaning this method blocks and
@@ -489,6 +493,7 @@ namespace pcpp
 		/// occurred (such as device not open etc.). When returning 0 an appropriate error message is printed to log
 		/// @note On Unix-like systems, enabling the `usePoll` option in `DeviceConfiguration` prevents the method from
 		/// blocking indefinitely when no packets are available, even if a timeout is set.
+		/// @remarks This method is planned for conversion to non-virtual in the future, so it should not be overridden.
 		virtual int startCaptureBlockingMode(OnPacketArrivesStopBlocking onPacketArrives, void* userCookie,
 		                                     const double timeout);
 
@@ -654,6 +659,16 @@ namespace pcpp
 		void getStatistics(IPcapDevice::PcapStats& stats) const override;
 
 	protected:
+		/// @brief Called before starting a capture to prepare the device for capturing packets.
+		///
+		/// This method can be overridden by derived classes to perform additional preparations before starting
+		/// the packet capture.
+		///
+		/// @param asyncCapture True if the capture is asynchronous (i.e. packets are captured in a separate thread),
+		/// @param captureStats True if statistics should be captured during the capture process.
+		virtual void prepareCapture(bool asyncCapture, bool captureStats)
+		{}
+
 		internal::PcapHandle doOpen(const DeviceConfiguration& config);
 
 		// Sends a packet directly to the network.

Pcap++/header/WinPcapLiveDevice.h

@@ -37,16 +37,6 @@ namespace pcpp
 			return WinPcapDevice;
 		}
 
-		bool startCapture(OnPacketArrivesCallback onPacketArrives, void* onPacketArrivesUserCookie,
-		                  int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate,
-		                  void* onStatsUpdateUserCookie) override;
-		bool startCapture(int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate,
-		                  void* onStatsUpdateUserCookie) override;
-		bool startCapture(RawPacketVector& capturedPacketsVector) override
-		{
-			return PcapLiveDevice::startCapture(capturedPacketsVector);
-		}
-
 		using PcapLiveDevice::sendPackets;
 		virtual int sendPackets(RawPacket* rawPacketsArr, int arrLength);
 
@@ -66,5 +56,8 @@ namespace pcpp
 		}
 
 		WinPcapLiveDevice* clone() const override;
+
+	protected:
+		void prepareCapture(bool asyncCapture, bool captureStats) override;
 	};
 }  // namespace pcpp

Pcap++/src/PcapLiveDevice.cpp

@@ -658,6 +658,16 @@ namespace pcpp
 			return false;
 		}
 
+		try
+		{
+			prepareCapture(true, onStatsUpdate != nullptr);
+		}
+		catch (std::exception const& ex)
+		{
+			PCPP_LOG_ERROR("Failed to prepare capture: " << ex.what());
+			return false;
+		}
+
 		m_CaptureCallbackMode = true;
 		m_cbOnPacketArrives = std::move(onPacketArrives);
 		m_cbOnPacketArrivesUserCookie = onPacketArrivesUserCookie;
@@ -700,6 +710,16 @@ namespace pcpp
 			return false;
 		}
 
+		try
+		{
+			prepareCapture(true, false);
+		}
+		catch (const std::exception& ex)
+		{
+			PCPP_LOG_ERROR("Failed to prepare capture: " << ex.what());
+			return false;
+		}
+
 		m_CapturedPackets = &capturedPacketsVector;
 		m_CapturedPackets->clear();
 
@@ -733,6 +753,15 @@ namespace pcpp
 			return 0;
 		}
 
+		try
+		{
+			prepareCapture(false, false);
+		}
+		catch (const std::exception& ex)
+		{
+			PCPP_LOG_ERROR("Failed to prepare capture: " << ex.what());
+			return 0;
+		}
 		m_cbOnPacketArrives = nullptr;
 		m_cbOnPacketArrivesUserCookie = nullptr;
 

Pcap++/src/WinPcapLiveDevice.cpp

@@ -18,46 +18,6 @@ namespace pcpp
 		m_MinAmountOfDataToCopyFromKernelToApplication = 16000;
 	}
 
-	bool WinPcapLiveDevice::startCapture(OnPacketArrivesCallback onPacketArrives, void* onPacketArrivesUserCookie,
-	                                     int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate,
-	                                     void* onStatsUpdateUserCookie)
-	{
-		if (!m_DeviceOpened || m_PcapDescriptor == nullptr)
-		{
-			PCPP_LOG_ERROR("Device '" << m_InterfaceDetails.name << "' not opened");
-			return false;
-		}
-
-		// Put the interface in capture mode
-		if (pcap_setmode(m_PcapDescriptor.get(), MODE_CAPT) < 0)
-		{
-			PCPP_LOG_ERROR("Error setting the capture mode for device '" << m_InterfaceDetails.name << "'");
-			return false;
-		}
-
-		return PcapLiveDevice::startCapture(onPacketArrives, onPacketArrivesUserCookie, intervalInSecondsToUpdateStats,
-		                                    onStatsUpdate, onStatsUpdateUserCookie);
-	}
-
-	bool WinPcapLiveDevice::startCapture(int intervalInSecondsToUpdateStats, OnStatsUpdateCallback onStatsUpdate,
-	                                     void* onStatsUpdateUserCookie)
-	{
-		if (!m_DeviceOpened || m_PcapDescriptor == nullptr)
-		{
-			PCPP_LOG_ERROR("Device '" << m_InterfaceDetails.name << "' not opened");
-			return false;
-		}
-
-		// Put the interface in statistics mode
-		if (pcap_setmode(m_PcapDescriptor.get(), MODE_STAT) < 0)
-		{
-			PCPP_LOG_ERROR("Error setting the statistics mode for device '" << m_InterfaceDetails.name << "'");
-			return false;
-		}
-
-		return PcapLiveDevice::startCapture(intervalInSecondsToUpdateStats, onStatsUpdate, onStatsUpdateUserCookie);
-	}
-
 	int WinPcapLiveDevice::sendPackets(RawPacket* rawPacketsArr, int arrLength)
 	{
 		if (!m_DeviceOpened || m_PcapDescriptor == nullptr)
@@ -145,4 +105,16 @@ namespace pcpp
 		return new WinPcapLiveDevice(m_InterfaceDetails, true, true, true);
 	}
 
+	void WinPcapLiveDevice::prepareCapture(bool asyncCapture, bool captureStats)
+	{
+
+		int mode = captureStats ? MODE_STAT : MODE_CAPT;
+		int res = pcap_setmode(m_PcapDescriptor.get(), mode);
+		if (res < 0)
+		{
+			throw std::runtime_error("Error setting the mode for device '" + m_InterfaceDetails.name +
+			                         "': " + m_PcapDescriptor.getLastError());
+		}
+	}
+
 }  // namespace pcpp