/src/PcapPlusPlus/Pcap++/header/PcapFileDevice.h

Source
#pragma once

#include "Device.h"
#include "PcapDevice.h"
#include "RawPacket.h"
#include <fstream>

/// @file

/// @namespace pcpp
/// @brief The main namespace for the PcapPlusPlus lib
namespace pcpp
{
  namespace internal
  {
    /// @struct LightPcapNgHandle
    /// An opaque struct representing a handle for pcapng files.
    struct LightPcapNgHandle;
  }  // namespace internal

  /// @enum FileTimestampPrecision
  /// An enumeration representing the precision of timestamps in a pcap file.
  /// The precision can be Unknown, Micro, or Nano.
  enum class FileTimestampPrecision : int8_t
  {
    /// Precision is unknown or not set/determined
    Unknown = -1,
    /// Precision is in microseconds.
    Microseconds = 0,
    /// Precision is in nanoseconds.
    Nanoseconds = 1
  };

  /// @class IFileDevice
  /// An abstract class (cannot be instantiated, has a private c'tor) which is the parent class for all file devices
  class IFileDevice : public IFilterableDevice, public IPcapStatisticsProvider
  {
  protected:
    std::string m_FileName;
    BpfFilterWrapper m_BpfWrapper;

    explicit IFileDevice(const std::string& fileName);

    bool doUpdateFilter(std::string const* filterAsString) override;

  public:
    /// @return The name of the file
    std::string getFileName() const;

    // override methods

    /// @brief Get the statistics for this device.
    ///
    /// The PcapStats structure will hold the following:
    /// - packetsRecv: Number of packets processed (read or written, depending on the device type)
    /// - packetsDrop: Number of packets dropped (not read or not written, depending on the device type)
    /// - packetsDropByInterface: Not supported for file devices, will always be 0
    ///
    /// @param[out] stats The stats object to fill in.
    void getStatistics(PcapStats& stats) const override;

  protected:
    /// @brief Report that packets were processed (read or written, depending on the device type).
    /// @param numPackets The number of packets processed. Default is 1.
    void reportPacketProcessed(uint64_t numPackets = 1)
    {
      m_NumOfPacketsProcessed += numPackets;
    }

    /// @brief Report that packets were dropped (not read or not written, depending on the device type).
    /// @param numPackets The number of packets dropped. Default is 1.
    void reportPacketDropped(uint64_t numPackets = 1)
    {
      m_NumOfPacketsDropped += numPackets;
    }

    /// @brief Reset the internal statistic counters to zero.
    void resetStatisticCounters();

  private:
    uint64_t m_NumOfPacketsProcessed = 0;
    uint64_t m_NumOfPacketsDropped = 0;
  };

  /// @class IFileReaderDevice
  /// An abstract class (cannot be instantiated, has a private c'tor) which is the parent class for file reader
  /// devices
  class IFileReaderDevice : public IFileDevice
  {
  protected:
    /// A constructor for this class that gets the pcap full path file name to open. Notice that after calling this
    /// constructor the file isn't opened yet, so reading packets will fail. For opening the file call open()
    /// @param[in] fileName The full path of the file to read
    IFileReaderDevice(const std::string& fileName);

  public:
    /// A destructor for this class
    ~IFileReaderDevice() override = default;

    /// @return The file size in bytes
    uint64_t getFileSize() const;

    virtual bool getNextPacket(RawPacket& rawPacket) = 0;

    /// Read the next N packets into a raw packet vector
    /// @param[out] packetVec The raw packet vector to read packets into
    /// @param[in] numOfPacketsToRead Number of packets to read. If value <0 all remaining packets in the file will
    /// be read into the raw packet vector (this is the default value)
    /// @return The number of packets actually read
    int getNextPackets(RawPacketVector& packetVec, int numOfPacketsToRead = -1);

    /// A static method that creates an instance of the reader best fit to read the file. It decides by the file
    /// extension: for .pcapng files it returns an instance of PcapNgFileReaderDevice and for all other extensions
    /// it returns an instance of PcapFileReaderDevice
    /// @param[in] fileName The file name to open
    /// @return An instance of the reader to read the file. Notice you should free this instance when done using it
    static IFileReaderDevice* getReader(const std::string& fileName);
  };

  /// @class IFileWriterDevice
  /// An abstract class (cannot be instantiated, has a private c'tor) which is the parent class for file writer
  /// devices
  class IFileWriterDevice : public IFileDevice
  {
  protected:
    IFileWriterDevice(const std::string& fileName);

  public:
    /// A destructor for this class
    ~IFileWriterDevice() override = default;

    virtual bool writePacket(RawPacket const& packet) = 0;

    virtual bool writePackets(const RawPacketVector& packets) = 0;

    using IFileDevice::open;
    virtual bool open(bool appendMode) = 0;
  };

  /// @class PcapFileReaderDevice
  /// A class for opening a pcap file in read-only mode. This class enable to open the file and read all packets,
  /// packet-by-packet
  class PcapFileReaderDevice : public IFileReaderDevice
  {
  public:
    /// A constructor for this class that gets the pcap full path file name to open. Notice that after calling this
    /// constructor the file isn't opened yet, so reading packets will fail. For opening the file call open()
    /// @param[in] fileName The full path of the file to read
    explicit PcapFileReaderDevice(const std::string& fileName) : IFileReaderDevice(fileName)
    {}

    /// A destructor for this class
    ~PcapFileReaderDevice() override = default;

    PcapFileReaderDevice(const PcapFileReaderDevice& other) = delete;
    PcapFileReaderDevice& operator=(const PcapFileReaderDevice& other) = delete;

    /// @return The link layer type of this file
    LinkLayerType getLinkLayerType() const
    {
      return m_PcapLinkLayerType;
    }

    /// @return The precision of the timestamps in the file
    FileTimestampPrecision getTimestampPrecision() const
    {
      return m_Precision;
    }

    /// @return The file's snapshot length (snaplen)
    uint32_t getSnapshotLength() const
    {
      return m_SnapshotLength;
    }

    /// A static method that checks if nano-second precision is supported in the current platform and environment
    /// @return True if nano-second precision is supported, false otherwise
    /// @deprecated Nanosecond precision is now natively supported by the internal parser and always returns true
    PCPP_DEPRECATED("Nanosecond precision is now natively supported by the internal parser and always returns true")
    static bool isNanoSecondPrecisionSupported()
    {
      return true;
    }

    // overridden methods

    /// @return True if the file is opened, false otherwise
    bool isOpened() const override
    {
      return m_PcapFile.is_open();
    }

    /// Read the next packet from the file. Before using this method please verify the file is opened using open()
    /// @param[out] rawPacket A reference for an empty RawPacket where the packet will be written
    /// @return True if a packet was read successfully. False will be returned if the file isn't opened (also, an
    /// error log will be printed) or if reached end-of-file
    bool getNextPacket(RawPacket& rawPacket) override;

    /// Open the file name which path was specified in the constructor in a read-only mode
    /// @return True if file was opened successfully or if file is already opened. False if opening the file failed
    /// for some reason (for example: file path does not exist)
    bool open() override;

    /// Close the pacp file
    void close() override;

  private:
    FileTimestampPrecision m_Precision = FileTimestampPrecision::Unknown;
    LinkLayerType m_PcapLinkLayerType = LINKTYPE_ETHERNET;
    std::ifstream m_PcapFile;
    bool m_NeedsSwap = false;
    uint32_t m_SnapshotLength = 0;
    std::vector<uint8_t> m_ReadBuffer;

    bool readNextPacket(timespec& packetTimestamp, uint8_t* packetData, uint32_t packetDataLen,
                        uint32_t& capturedLength, uint32_t& frameLength);
  };

  /// @class PcapFileWriterDevice
  /// A class for opening a pcap file for writing or creating a new pcap file and writing packets to it.
  /// It supports opening a pcap file in append mode where packets are written at the end of the file
  /// instead of overwriting it. This implementation writes the pcap stream directly using C++ I/O
  /// facilities (std::fstream) and does not require libpcap/WinPcap at runtime.
  class PcapFileWriterDevice : public IFileWriterDevice
  {
  public:
    /// A constructor for this class that gets the pcap full path file name to open for writing or create. Notice
    /// that after calling this constructor the file isn't opened yet, so writing packets will fail. For opening the
    /// file call open()
    /// @param[in] fileName The full path of the file
    /// @param[in] linkLayerType The link layer type all packet in this file will be based on. The default is
    /// Ethernet
    /// @param[in] nanosecondsPrecision A boolean indicating whether to write timestamps in nano-precision. If set
    /// to false, timestamps will be written in micro-precision
    /// @throws std::runtime_error if nanosecondsPrecision is set to `true` but the current platform and environment
    /// doesn't support it.
    PcapFileWriterDevice(const std::string& fileName, LinkLayerType linkLayerType = LINKTYPE_ETHERNET,
                         bool nanosecondsPrecision = false);

    PcapFileWriterDevice(const PcapFileWriterDevice& other) = delete;
    PcapFileWriterDevice& operator=(const PcapFileWriterDevice& other) = delete;

    /// Write a RawPacket to the file. Before using this method please verify the file is opened using open(). This
    /// method won't change the written packet
    /// @param[in] packet A reference for an existing RawPcket to write to the file
    /// @return True if a packet was written successfully. False will be returned if the file isn't opened
    /// or if the packet link layer type is different than the one defined for the file
    /// (in all cases, an error will be printed to log)
    bool writePacket(RawPacket const& packet) override;

    /// Write multiple RawPacket to the file. Before using this method please verify the file is opened using
    /// open(). This method won't change the written packets or the RawPacketVector instance
    /// @param[in] packets A reference for an existing RawPcketVector, all of its packets will be written to the
    /// file
    /// @return True if all packets were written successfully to the file. False will be returned if the file isn't
    /// opened (also, an error log will be printed) or if at least one of the packets wasn't written successfully to
    /// the file
    bool writePackets(const RawPacketVector& packets) override;

    /// @return The precision of the timestamps in the file.
    FileTimestampPrecision getTimestampPrecision() const
    {
      return m_Precision;
    }

    /// A static method that checks if nano-second precision is supported in the current platform and environment
    /// @return True if nano-second precision is supported, false otherwise
    /// @deprecated Nanosecond precision is now natively supported by the internal parser and always returns true
    PCPP_DEPRECATED("Nanosecond precision is now natively supported by the internal parser and always returns true")
    static bool isNanoSecondPrecisionSupported()
    {
      return true;
    }

    LinkLayerType getLinkLayerType() const
    {
      return m_PcapLinkLayerType;
    }

    /// Open the file in a write mode. If file doesn't exist, it will be created. If it does exist it will be
    /// overwritten, meaning all its current content will be deleted
    /// @return True if file was opened/created successfully or if file is already opened. False if opening the file
    /// failed for some reason (an error will be printed to log)
    bool open() override;

    /// Same as open(), but enables to open the file in append mode in which packets will be appended to the file
    /// instead of overwrite its current content. In append mode file must exist, otherwise opening will fail
    /// @param[in] appendMode A boolean indicating whether to open the file in append mode or not. If set to false
    /// this method will act exactly like open(). If set to true, file will be opened in append mode
    /// @return True of managed to open the file successfully. In case appendMode is set to true, false will be
    /// returned if file wasn't found or couldn't be read, if file type is not pcap, or if link type specified in
    /// c'tor is different from current file link type. In case appendMode is set to false, please refer to open()
    /// for return values
    bool open(bool appendMode) override;

    /// @return True if the file is opened, false otherwise
    bool isOpened() const override
    {
      return m_PcapFile.is_open();
    }

    /// Flush and close the pacp file
    void close() override;

    /// Flush packets to disk.
    void flush();

  private:
    LinkLayerType m_PcapLinkLayerType = LINKTYPE_ETHERNET;
    bool m_NeedsSwap = false;
    FileTimestampPrecision m_Precision = FileTimestampPrecision::Unknown;
    std::fstream m_PcapFile;

    struct CheckHeaderResult
    {
      enum class Result
      {
        HeaderOk,
        HeaderError,
        HeaderNeeded
      };

      Result result;
      std::string error;
      bool needsSwap = false;

      static CheckHeaderResult fromOk(bool needsSwap)
      {
        return { Result::HeaderOk, "", needsSwap };
      }

      static CheckHeaderResult fromError(const std::string& error)
      {
        return { Result::HeaderError, error };
      }

      static CheckHeaderResult fromHeaderNeeded()
      {
        return { Result::HeaderNeeded };
      }
    };

    static bool writeHeader(std::fstream& pcapFile, FileTimestampPrecision precision, uint32_t snaplen,
                            LinkLayerType linkType);
    static CheckHeaderResult checkHeader(std::fstream& pcapFile, FileTimestampPrecision requestedPrecision,
                                         LinkLayerType requestedLinkType);
  };

  /// @class PcapNgFileReaderDevice
  /// A class for opening a pcap-ng file in read-only mode. This class enable to open the file and read all packets,
  /// packet-by-packet
  class PcapNgFileReaderDevice : public IFileReaderDevice
  {
  private:
    internal::LightPcapNgHandle* m_LightPcapNg;

  public:
    /// A constructor for this class that gets the pcap-ng full path file name to open. Notice that after calling
    /// this constructor the file isn't opened yet, so reading packets will fail. For opening the file call open()
    /// @param[in] fileName The full path of the file to read
    PcapNgFileReaderDevice(const std::string& fileName);

    /// A destructor for this class
    ~PcapNgFileReaderDevice() override
    {
      PcapNgFileReaderDevice::close();
    }

    PcapNgFileReaderDevice(const PcapNgFileReaderDevice& other) = delete;
    PcapNgFileReaderDevice& operator=(const PcapNgFileReaderDevice& other) = delete;

    /// The pcap-ng format allows storing metadata at the header of the file. Part of this metadata is a string
    /// specifying the operating system that was used for capturing the packets. This method reads this string from
    /// the metadata (if exists) and returns it
    /// @return The operating system string if exists, or an empty string otherwise
    std::string getOS() const;

    /// The pcap-ng format allows storing metadata at the header of the file. Part of this metadata is a string
    /// specifying the hardware that was used for capturing the packets. This method reads this string from the
    /// metadata (if exists) and returns it
    /// @return The hardware string if exists, or an empty string otherwise
    std::string getHardware() const;

    /// The pcap-ng format allows storing metadata at the header of the file. Part of this metadata is a string
    /// specifying the capture application that was used for capturing the packets. This method reads this string
    /// from the metadata (if exists) and returns it
    /// @return The capture application string if exists, or an empty string otherwise
    std::string getCaptureApplication() const;

    /// The pcap-ng format allows storing metadata at the header of the file. Part of this metadata is a string
    /// containing a user-defined comment (can be any string). This method reads this string from the metadata (if
    /// exists) and returns it
    /// @return The comment written inside the file if exists, or an empty string otherwise
    std::string getCaptureFileComment() const;

    /// The pcap-ng format allows storing a user-defined comment for every packet (besides the comment per-file).
    /// This method reads the next packet and the comment attached to it (if such comment exists), and returns them
    /// both
    /// @param[out] rawPacket A reference for an empty RawPacket where the packet will be written
    /// @param[out] packetComment The comment attached to the packet or an empty string if no comment exists
    /// @return True if a packet was read successfully. False will be returned if the file isn't opened (also, an
    /// error log will be printed) or if reached end-of-file
    bool getNextPacket(RawPacket& rawPacket, std::string& packetComment);

    // overridden methods

    /// Read the next packet from the file. Before using this method please verify the file is opened using open()
    /// @param[out] rawPacket A reference for an empty RawPacket where the packet will be written
    /// @return True if a packet was read successfully. False will be returned if the file isn't opened (also, an
    /// error log will be printed) or if reached end-of-file
    bool getNextPacket(RawPacket& rawPacket) override;

    /// Open the file name which path was specified in the constructor in a read-only mode
    /// @return True if file was opened successfully or if file is already opened. False if opening the file failed
    /// for some reason (for example: file path does not exist)
    bool open() override;

    /// @return True if the file is opened, false otherwise
    bool isOpened() const override
    {
      return m_LightPcapNg != nullptr;
    }

    /// Close the pacp-ng file
    void close() override;

  private:
    bool getNextPacketInternal(RawPacket& rawPacket, std::string* packetComment);
  };

  /// @class PcapNgFileWriterDevice
  /// A class for opening a pcap-ng file for writing or creating a new pcap-ng file and write packets to it. This
  /// class adds unique capabilities such as writing metadata attributes into the file header, adding comments per
  /// packet and opening the file in append mode where packets are added to a file instead of overriding it. This
  /// capabilities are part of the pcap-ng standard but aren't supported in most tools and libraries
  class PcapNgFileWriterDevice : public IFileWriterDevice
  {
  private:
    internal::LightPcapNgHandle* m_LightPcapNg;
    int m_CompressionLevel;

  public:
    /// A constructor for this class that gets the pcap-ng full path file name to open for writing or create. Notice
    /// that after calling this constructor the file isn't opened yet, so writing packets will fail. For opening the
    /// file call open()
    /// @param[in] fileName The full path of the file
    /// @param[in] compressionLevel The compression level to use when writing the file, use 0 to disable compression
    /// or 10 for max compression. Default is 0
    PcapNgFileWriterDevice(const std::string& fileName, int compressionLevel = 0);

    /// A destructor for this class
    ~PcapNgFileWriterDevice() override
    {
      PcapNgFileWriterDevice::close();
    }

    PcapNgFileWriterDevice(const PcapFileWriterDevice& other) = delete;
    PcapNgFileWriterDevice& operator=(const PcapNgFileWriterDevice& other) = delete;

    /// The pcap-ng format allows adding a user-defined comment for each stored packet. This method writes a
    /// RawPacket to the file and adds a comment to it. Before using this method please verify the file is opened
    /// using open(). This method won't change the written packet or the input comment
    /// @param[in] packet A reference for an existing RawPcket to write to the file
    /// @param[in] comment The comment to be written for the packet. If this string is empty or null it will be
    /// ignored
    /// @return True if a packet was written successfully. False will be returned if the file isn't opened (an error
    /// will be printed to log)
    bool writePacket(RawPacket const& packet, const std::string& comment);

    // overridden methods

    /// Write a RawPacket to the file. Before using this method please verify the file is opened using open(). This
    /// method won't change the written packet
    /// @param[in] packet A reference for an existing RawPcket to write to the file
    /// @return True if a packet was written successfully. False will be returned if the file isn't opened (an error
    /// will be printed to log)
    bool writePacket(RawPacket const& packet) override;

    /// Write multiple RawPacket to the file. Before using this method please verify the file is opened using
    /// open(). This method won't change the written packets or the RawPacketVector instance
    /// @param[in] packets A reference for an existing RawPcketVector, all of its packets will be written to the
    /// file
    /// @return True if all packets were written successfully to the file. False will be returned if the file isn't
    /// opened (also, an error log will be printed) or if at least one of the packets wasn't written successfully to
    /// the file
    bool writePackets(const RawPacketVector& packets) override;

    /// Open the file in a write mode. If file doesn't exist, it will be created. If it does exist it will be
    /// overwritten, meaning all its current content will be deleted
    /// @return True if file was opened/created successfully or if file is already opened. False if opening the file
    /// failed for some reason (an error will be printed to log)
    bool open() override;

    /// Same as open(), but enables to open the file in append mode in which packets will be appended to the file
    /// instead of overwrite its current content. In append mode file must exist, otherwise opening will fail
    /// @param[in] appendMode A boolean indicating whether to open the file in append mode or not. If set to false
    /// this method will act exactly like open(). If set to true, file will be opened in append mode
    /// @return True of managed to open the file successfully. In case appendMode is set to true, false will be
    /// returned if file wasn't found or couldn't be read, if file type is not pcap-ng. In case appendMode is set to
    /// false, please refer to open() for return values
    bool open(bool appendMode) override;

    /// Open the file in a write mode. If file doesn't exist, it will be created. If it does exist it will be
    /// overwritten, meaning all its current content will be deleted. As opposed to open(), this method also allows
    /// writing several metadata attributes that will be stored in the header of the file
    /// @param[in] os A string describing the operating system that was used to capture the packets. If this string
    /// is empty or null it will be ignored
    /// @param[in] hardware A string describing the hardware that was used to capture the packets. If this string is
    /// empty or null it will be ignored
    /// @param[in] captureApp A string describing the application that was used to capture the packets. If this
    /// string is empty or null it will be ignored
    /// @param[in] fileComment A string containing a user-defined comment that will be part of the metadata of the
    /// file. If this string is empty or null it will be ignored
    /// @return True if file was opened/created successfully or if file is already opened. False if opening the file
    /// failed for some reason (an error will be printed to log)
    bool open(const std::string& os, const std::string& hardware, const std::string& captureApp,
              const std::string& fileComment);

    /// @return True if the file is opened, false otherwise
    bool isOpened() const override
    {
      return m_LightPcapNg != nullptr;
    }

    /// Flush packets to the pcap-ng file
    void flush();

    /// Flush and close the pcap-ng file
    void close() override;

  private:
    /// @struct PcapNgMetadata
    /// @brief A struct for holding the metadata of a pcap-ng file. The metadata includes the operating system,
    /// hardware, capture application and file comment.
    struct PcapNgMetadata
    {
      /// The operating system that was used for capturing the packets
      std::string os;
      /// The hardware that was used for capturing the packets
      std::string hardware;
      /// The capture application that was used for capturing the packets
      std::string captureApplication;
      /// The comment that was written inside the file
      std::string comment;
    };

    bool openWrite(PcapNgMetadata const* metadata = nullptr);
    bool openAppend();
  };

  /// @class SnoopFileReaderDevice
  /// A class for opening a snoop file in read-only mode. This class enable to open the file and read all packets,
  /// packet-by-packet
  class SnoopFileReaderDevice : public IFileReaderDevice
  {
  private:
#pragma pack(1)
    /// File format header.
    typedef struct
    {
      uint64_t identification_pattern;
      uint32_t version_number;
      uint32_t datalink_type;
    } snoop_file_header_t;

    /// Packet record header.
    typedef struct
    {
      uint32_t original_length;       ///< original packet length
      uint32_t included_length;       ///< saved packet length
      uint32_t packet_record_length;  ///< total record length
      uint32_t ndrops_cumulative;     ///< cumulative drops
      uint32_t time_sec;              ///< timestamp
      uint32_t time_usec;             ///< microsecond timestamp
    } snoop_packet_header_t;
#pragma pack()

    LinkLayerType m_PcapLinkLayerType;
    std::ifstream m_SnoopFile;

    bool readNextPacket(timespec& packetTimestamp, uint8_t* packetData, uint32_t packetDataLen,
                        uint32_t& capturedLength, uint32_t& frameLength);

  public:
    /// A constructor for this class that gets the snoop full path file name to open. Notice that after calling this
    /// constructor the file isn't opened yet, so reading packets will fail. For opening the file call open()
    /// @param[in] fileName The full path of the file to read
    SnoopFileReaderDevice(const std::string& fileName)
        : IFileReaderDevice(fileName), m_PcapLinkLayerType(LINKTYPE_ETHERNET)
    {}

    /// A destructor for this class
    ~SnoopFileReaderDevice() override;

    SnoopFileReaderDevice(const PcapFileReaderDevice& other) = delete;
    SnoopFileReaderDevice& operator=(const PcapFileReaderDevice& other) = delete;

    /// @return The link layer type of this file
    LinkLayerType getLinkLayerType() const
    {
      return m_PcapLinkLayerType;
    }

    // overridden methods

    /// Read the next packet from the file. Before using this method please verify the file is opened using open()
    /// @param[out] rawPacket A reference for an empty RawPacket where the packet will be written
    /// @return True if a packet was read successfully. False will be returned if the file isn't opened (also, an
    /// error log will be printed) or if reached end-of-file
    bool getNextPacket(RawPacket& rawPacket) override;

    /// Open the file name which path was specified in the constructor in a read-only mode
    /// @return True if file was opened successfully or if file is already opened. False if opening the file failed
    /// for some reason (for example: file path does not exist)
    bool open() override;

    /// @return True if the file is opened, false otherwise
    bool isOpened() const override
    {
      return m_SnoopFile.is_open();
    }

    /// Close the snoop file
    void close() override;
  };
}  // namespace pcpp

Coverage Report

Created: 2026-03-31 07:53