pcappp::Pcap Class Reference

#include <Pcap.h>

Inheritance diagram for pcappp::Pcap:

List of all members.

Public Types
typedef void(*	Handler )(Pcap &pcap, Packet const &packet)
	Type of callback used in loop() and dispatch().
typedef bpf_u_int32	Netmask
	32 bit integer representing a IPv4 netmask
Public Member Functions
void	breakloop ()
	Stop reading packets.
pcap_t const *	cobj () const
	Gets the underlying libpcap C structure.
pcap_t *	cobj ()
	Gets the underlying libpcap C structure.
int	dispatch (Handler handler, int cnt=Pcap::DISPATCH_ALL)
	Collect and process packets.
DataLink	get_datalink () const
	Gets the link layer type.
Dumper const &	get_dumper () const
	Gets the Dumper object associated with this Pcap.
Dumper &	get_dumper ()
	Gets the Dumper object associated with this Pcap.
std::string const &	get_filter () const
	Gets the BPF filter expression applied to the Pcap.
unsigned int	get_snaplen () const
	Gets the snaplen.
std::vector< DataLink >	list_datalinks () const
	Gets all supported DataLinks.
int	loop (Handler handler, int cnt=Pcap::LOOP_FOREVER)
	Collect and process packets.
bool	next (Packet &packet)
	Reads the next packet available from the interface or the savefile.
bool	ok () const
	Gets the read state of the Pcap.
	operator bool () const
	Gets the read state of the Pcap.
void	set_datalink (DataLink const &datalink)
	Sets the link layer type.
void	set_filter (std::string const &expression, bool optimize=false, Netmask netmask=0)
	Apply a filter given by a BPF expression.
Static Public Attributes
static const int	BREAKLOOP = -2
static const int	DISPATCH_ALL = -1
static const int	LOOP_FOREVER = -1
static const int	OK = 1
Protected Member Functions
std::string	geterr () const
	Pcap ()
virtual	~Pcap ()
Friends
Pcap &	operator>> (Pcap &pcap, Packet &packet)
	Reads the next packet available from the interface or the savefile.

---

Detailed Description

This class wraps the libpcap's C structure pcap_t, and it is the main class to perform packet capture with libpcap++.

---

Member Typedef Documentation

typedef void(* pcappp::Pcap::Handler)(Pcap &pcap, Packet const &packet)

Type of callback used in loop() and dispatch().

A Handler specifies a callback which is called for each incoming packet, with two arguments: a reference to the Pcap from which loop() or dispatch() has been called, and a reference to the current packet.

Note that at the time the handler is invoked, only the first packet.get_caplen() bytes are available, which won’t necessarily be the entire packet; to capture the entire packet, a sufficiently large caplen has to be provided in the Pcap constructor (a value of 65535 should be sufficient on most if not all networks).

Note also that the payload of the incoming Packet (accessible by packet.get_data()), is owned by libpcap. This means that care has to be taken when manipulating the data: If you want it to be persistent among successive incoming packets, create a new Packet object as a copy of the incoming one, and then call Packet::manage() on it

typedef bpf_u_int32 pcappp::Pcap::Netmask

32 bit integer representing a IPv4 netmask

---

Constructor & Destructor Documentation

pcappp::Pcap::Pcap

(

)

[protected]

pcappp::Pcap::~Pcap

(

)

[protected, virtual]

---

Member Function Documentation

void pcappp::Pcap::breakloop

(

)

Stop reading packets.

Sets a flag that will force dispatch() or loop() to return rather than looping. They will return the number of packets that have been processed so far, or Pcap::BREAKLOOP if no packets have been processed so far.

This function is safe to use inside a signal handler on UNIX or a console control handler on Windows, as it merely sets a flag that is checked within the loop. The flag is checked in loops reading packets from the OS - a signal by itself will not necessarily terminate those loops - as well as in loops processing a set of packets returned by the OS. Note that if you are catching signals on UNIX systems that support restarting system calls after a signal, and calling breakloop() in the signal handler, you must specify, when catching those signals, that system calls should NOT be restarted by that signal. Otherwise, if the signal interrupted a call reading packets in a PcapLive, when your signal handler returns after calling breakloop(), the call will be restarted, and the loop will not terminate until more packets arrive and the call completes.

Note also that, in a multi-threaded application, if one thread is blocked in dispatch(), loop() or next(), a call to breakloop() in a different thread will not unblock that thread; you will need to use whatever mechanism the OS provides for breaking a thread out of blocking calls in order to unblock the thread, such as thread cancellation in systems that support POSIX threads.

Note that next() will, on some platforms, loop reading packets from the OS; that loop will not necessarily be terminated by a signal, so breakloop() should be used to terminate packet processing even if next() is being used.

breakloop() does not guarantee that no further packets will be processed by dispatch() or loop() after it is called; at most one more packet might be processed.

If Pcap::BREAKLOOP is returned from dispatch() or loop(), the flag is cleared, so a subsequent call will resume reading packets. If a positive number is returned, the flag is not cleared, so a subsequent call will return Pcap::BREAKLOOP and clear the flag.

pcap_t const* pcappp::Pcap::cobj

(

)

const [inline]

Gets the underlying libpcap C structure.

Returns:

A pointer to the underlying pcap_t

pcap_t* pcappp::Pcap::cobj

(

)

[inline]

Gets the underlying libpcap C structure.

Returns:

A pointer to the underlying pcap_t

int pcappp::Pcap::dispatch	(	Handler	handler,
		int	cnt = Pcap::DISPATCH_ALL
	)

Collect and process packets.

Parameters:

	handler	The callback to be called for each incoming packet
	cnt	The maximum number of packets to process before returning. For PcapLive only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A cnt of Pcap::DISPATCH_ALL processes all the packets received in one buffer on PcapLive, or all the packets in the savefile on PcapOffline.

Returns:

The number of packets read. On PcapLive, 0 may be returned if no packets were read from the interface (if, for example, they were discarded because they didn’t pass the packet filter, or if, on platforms that support a read timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the PcapLive is in non-blocking mode and no packets were available to be read). On PcapOffline, 0 may be returned if no more packets are available in the savefile. A return of Pcap::BREAKLOOP indicates that the loop terminated due to a call to breakloop() before any packets were processed.

Note that on PcapLive, dispatch() will not necessarily return when the read times out; on some platforms, the read timeout isn’t supported, and, on other platforms, the timer doesn’t start until at least one packet arrives. This means that the read timeout should not be used in, for example, an interactive application, to allow the packet capture loop to "poll" for user input periodically, as there’s no guarantee that dispatch() will return after the timeout expires.

Exceptions:

PcapError

DataLink pcappp::Pcap::get_datalink

(

)

const

Gets the link layer type.

Dumper const& pcappp::Pcap::get_dumper

(

)

const [inline]

Gets the Dumper object associated with this Pcap.

Every Pcap has an attached Dumper object, which may be opened, closed or manipulated using the Dumper member functions.

Returns:

A const reference to the Dumper object

Dumper& pcappp::Pcap::get_dumper

(

)

[inline]

Gets the Dumper object associated with this Pcap.

Every Pcap has an attached Dumper object, which may be opened, closed or manipulated using the Dumper member functions

Returns:

A reference to the Dumper object

std::string const& pcappp::Pcap::get_filter

(

)

const [inline]

Gets the BPF filter expression applied to the Pcap.

Returns:

The filter expression, or an empty string if no filter is currently applied to the Pcap.

unsigned int pcappp::Pcap::get_snaplen

(

)

const

Gets the snaplen.

std::string pcappp::Pcap::geterr

(

)

const [protected]

std::vector< DataLink > pcappp::Pcap::list_datalinks

(

)

const

Gets all supported DataLinks.

Gets a list of all the supported data link types of the interface associated with this Pcap

Returns:

A std::vector containing the DataLinks

int pcappp::Pcap::loop	(	Handler	handler,
		int	cnt = Pcap::LOOP_FOREVER
	)

Collect and process packets.

Similar to dispatch() except it keeps reading packets until cnt packets are processed or an error occurs.

Parameters:

	handler	The callback to be called for each incoming packet
	cnt	Maximum number of packets to process. A value of Pcap::LOOP_FOREVER causes loop() to loop forever (or at least until an error occurs).

Returns:

Pcap::OK upon successful processing of all the cnt packets, or Pcap::BREAKLOOP if the loop terminated due to a call to breakloop() before any packets were processed.

Exceptions:

PcapError

bool pcappp::Pcap::next

(

Packet &

packet

)

[inline]

Reads the next packet available from the interface or the savefile.

Parameters:

packet

A reference to a Packet that will be filled with the data of the incoming packet upon successful read

Returns:

true if a packet was successfully read

In PcapLive, the read may fail if the timeout expires before any packet is captured. In PcapOffline, the read may if the end-of-file of the savefile is reached.
In both cases, a flag is set in the Pcap so that ok() and the operator bool() return false. This flag is cleared upon each successful read

Exceptions:

PcapError

bool pcappp::Pcap::ok

(

)

const [inline]

Gets the read state of the Pcap.

Returns:

true if the last attempt to read a packet was successful, and false otherwise

pcappp::Pcap::operator bool

(

)

const [inline]

Gets the read state of the Pcap.

Returns:

true if the last attempt to read a packet was successful, and false otherwise

void pcappp::Pcap::set_datalink

(

DataLink const &

datalink

)

Sets the link layer type.

void pcappp::Pcap::set_filter	(	std::string const &	expression,
		bool	optimize = false,
		Netmask	netmask = 0
	)

Apply a filter given by a BPF expression.

Parameters:

	expression	The filter expression
	optimize	Whether optimization on the resulting code is performed
	netmask	Specifies the IPv4 netmask of the network on which packets are being captured. It is used only when checking for IPv4 broadcast addresses in the filter program. If the netmask of the network on which packets are being captured isn’t known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of 0 can be supplied; tests for IPv4 broadcast addresses won’t be done correctly, but all other tests in the filter program will be OK

Exceptions:

PcapError

---

Friends And Related Function Documentation

Pcap& operator>>	(	Pcap &	pcap,
		Packet &	packet
	)			[friend]

Reads the next packet available from the interface or the savefile.

In PcapLive, the read may fail if the timeout expires before any packet is captured. In PcapOffline, the read may if the end-of-file of the savefile is reached.
In both cases, a flag is set in the Pcap so that ok() and the operator bool() return false. This flag is cleared upon each successful read

Exceptions:

PcapError

---

Member Data Documentation

const int pcappp::Pcap::BREAKLOOP = -2 [static]

const int pcappp::Pcap::DISPATCH_ALL = -1 [static]

const int pcappp::Pcap::LOOP_FOREVER = -1 [static]

const int pcappp::Pcap::OK = 1 [static]

---

The documentation for this class was generated from the following files:

• Pcap.h
• Pcap.cc