PcapPlusPlus  20.08
pcpp::PcapNgFileWriterDevice Class Reference

#include <PcapFileDevice.h>

Inheritance diagram for pcpp::PcapNgFileWriterDevice:
pcpp::IFileWriterDevice pcpp::IFileDevice pcpp::IPcapDevice pcpp::IDevice pcpp::IFilterableDevice

Public Member Functions

 PcapNgFileWriterDevice (const char *fileName, int compressionLevel=0)
 
virtual ~PcapNgFileWriterDevice ()
 
bool open (const char *os, const char *hardware, const char *captureApp, const char *fileComment)
 
bool writePacket (RawPacket const &packet, const char *comment)
 
bool writePacket (RawPacket const &packet)
 
bool writePackets (const RawPacketVector &packets)
 
bool open ()
 
bool open (bool appendMode)
 
void flush ()
 
void close ()
 
void getStatistics (pcap_stat &stats) const
 
bool setFilter (std::string filterAsString)
 
- Public Member Functions inherited from pcpp::IFileWriterDevice
virtual ~IFileWriterDevice ()
 
- Public Member Functions inherited from pcpp::IFileDevice
std::string getFileName () const
 
- Public Member Functions inherited from pcpp::IPcapDevice
bool clearFilter ()
 
virtual bool setFilter (GeneralFilter &filter)
 
virtual bool setFilter (std::string filterAsString)=0
 
- Public Member Functions inherited from pcpp::IDevice
bool isOpened ()
 
- Public Member Functions inherited from pcpp::IFilterableDevice
virtual bool setFilter (GeneralFilter &filter)
 

Additional Inherited Members

- Static Public Member Functions inherited from pcpp::IPcapDevice
static std::string getPcapLibVersionInfo ()
 
static bool verifyFilter (std::string filterAsString)
 
static bool matchPacketWithFilter (std::string filterAsString, RawPacket *rawPacket)
 
static bool matchPacketWithFilter (GeneralFilter &filter, RawPacket *rawPacket)
 

Detailed Description

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

Constructor & Destructor Documentation

◆ PcapNgFileWriterDevice()

pcpp::PcapNgFileWriterDevice::PcapNgFileWriterDevice ( const char *  fileName,
int  compressionLevel = 0 
)

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()

Parameters
[in]fileNameThe full path of the file
[in]compressionLevelThe compression level to use when writing the file, use 0 to disable compression or 10 for max compression. Default is 0

◆ ~PcapNgFileWriterDevice()

virtual pcpp::PcapNgFileWriterDevice::~PcapNgFileWriterDevice ( )
inlinevirtual

A destructor for this class

Member Function Documentation

◆ close()

void pcpp::PcapNgFileWriterDevice::close ( )
virtual

Flush and close the pcap-ng file

Reimplemented from pcpp::IFileDevice.

◆ flush()

void pcpp::PcapNgFileWriterDevice::flush ( )

Flush packets to the pcap-ng file

◆ getStatistics()

void pcpp::PcapNgFileWriterDevice::getStatistics ( pcap_stat &  stats) const
virtual

Get statistics of packets written so far. In the pcap_stat struct, only ps_recv member is relevant. The rest of the members will contain 0

Parameters
[out]statsThe stats struct where stats are returned

Implements pcpp::IPcapDevice.

◆ open() [1/3]

bool pcpp::PcapNgFileWriterDevice::open ( )
virtual

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

Returns
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)

Implements pcpp::IDevice.

◆ open() [2/3]

bool pcpp::PcapNgFileWriterDevice::open ( bool  appendMode)
virtual

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

Parameters
[in]appendModeA 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
Returns
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

Implements pcpp::IFileWriterDevice.

◆ open() [3/3]

bool pcpp::PcapNgFileWriterDevice::open ( const char *  os,
const char *  hardware,
const char *  captureApp,
const char *  fileComment 
)

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

Parameters
[in]osA string describing the operating system that was used to capture the packets. If this string is empty or null it will be ignored
[in]hardwareA string describing the hardware that was used to capture the packets. If this string is empty or null it will be ignored
[in]captureAppA string describing the application that was used to capture the packets. If this string is empty or null it will be ignored
[in]fileCommentA 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
Returns
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)

◆ setFilter()

bool pcpp::PcapNgFileWriterDevice::setFilter ( std::string  filterAsString)
virtual

Set a filter for PcapNG writer device. Only packets that match the filter will be persisted

Parameters
[in]filterAsStringThe filter to be set in Berkeley Packet Filter (BPF) syntax (http://biot.com/capstats/bpf.html)
Returns
True if filter set successfully, false otherwise

Reimplemented from pcpp::IPcapDevice.

◆ writePacket() [1/2]

bool pcpp::PcapNgFileWriterDevice::writePacket ( RawPacket const &  packet)
virtual

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

Parameters
[in]packetA reference for an existing RawPcket to write to the file
Returns
True if a packet was written successfully. False will be returned if the file isn't opened (an error will be printed to log)

Implements pcpp::IFileWriterDevice.

◆ writePacket() [2/2]

bool pcpp::PcapNgFileWriterDevice::writePacket ( RawPacket const &  packet,
const char *  comment 
)

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

Parameters
[in]packetA reference for an existing RawPcket to write to the file
[in]commentThe comment to be written for the packet. If this string is empty or null it will be ignored
Returns
True if a packet was written successfully. False will be returned if the file isn't opened (an error will be printed to log)

◆ writePackets()

bool pcpp::PcapNgFileWriterDevice::writePackets ( const RawPacketVector packets)
virtual

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

Parameters
[in]packetsA reference for an existing RawPcketVector, all of its packets will be written to the file
Returns
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

Implements pcpp::IFileWriterDevice.