whisper_library::PcapWrapper Class Reference

Used to receive packets and send TCP packets under win32. More...

Classes
struct	PcapPacket
	Packet structure as returned by pcap. More...

Public Types
enum	RC {   NORMAL_EXECUTION = 0, EMPTY_PACKET_DATA = 1, CLOSE_ON_UNOPENED_HANDLE = 2, OPEN_ON_OPENED_HANDLE = 3,   NO_ADAPTERS_FOUND = 255, UNSPECIFIED_ERROR_OCCURED = -1, ADAPTER_NOT_FOUND = -2, ACCESS_ON_UNOPENED_HANDLE = -3,   ERROR_RETRIEVING_ADAPTERS = -4, ERROR_OPENING_HANDLE = -5, ERROR_COMPILING_FILTER = -6, ERROR_APPLYING_FILTER = -7,   OUT_OF_MEMORY = -254 }
	Possible return codes issued by PcapWrapper Methods.

Public Member Functions
int	adapterCount ()
	retrieve the amount of available network adapters with a valid network address
std::vector< std::string >	adapterNames ()
	retrieve all adapter/device names (e.g. /dev/eth0) from network adapters with a valid network address
std::string	adapterName (int adapter_id)
	Get the name from a specific network adapter.
std::vector< std::string >	adapterAddresses (int adapter_id)
	Get all network addresses from a specific network adapter.
std::string	adapterDescription (int adapter_id)
	Get the descriptional text from a specific network adapter (under windows e.g. the name of the hardware network device, under unix often "<null>")
int	adapterId (std::string adapter_value, int value_type)
	Get the id from an adapter with a specific value \ Value Types: ADAPTER_NAME, ADAPTER_DESCRIPTION, ADAPTER_ADDRESS.
std::vector< int >	lastReturnCodes ()
	Returns a pointer to the global return code buffer.
void	clearReturnCodes ()
	empties the PcapWrapper's global return code buffer
int	retrieveAdapters ()
	Retrieves available network devices from the (local) machine. More...
int	openAdapter (std::string adapter_name, int max_packet_size, bool promiscuous_mode, int timeout)
	Opens a live capture handle to the given device. More...
int	openAdapter (int adapter_id, int max_packet_size, bool promiscuous_mode, int timeout)
	Opens a live capture handle to the given device. More...
int	closeAdapter (std::string adapter_name)
	Closes an openend handle on the adapter with the given name/id.
int	closeAdapter (int adapter_id)
	Closes an openend handle on the adapter with the given name/id.
int	freeAdapters ()
	Frees unopened adapters and closes previously opened handles. More...
int	applyFilter (int adapter_id, std::string filter)
	Applies a given filter with pcap syntax to the selected adapter.
int	applyFilter (std::string adapter_name, std::string filter)
	Applies a given filter with pcap syntax to the selected adapter.
int	removeFilter (int adapter_id)
	Removes any previously applied filter from the adapter handle.
int	removeFilter (std::string adapter_name)
	Removes any previously applied filter from the adapter handle.
PcapPacket	retrievePacket (int adapter_id)
	Retrieves the next packet from the capture device. More...
PcapPacket	retrievePacket (std::string adapter_name)
	Retrieves the next packet from the capture device. More...
std::vector< bool >	retrievePacketAsVector (int adapter_id)
	Calls retrievePacket(adapter_id) and converts the retrieved packet payload in a std::vector<bool> More...
std::vector< bool >	retrievePacketAsVector (std::string adapter_name)
	Calls retrievePacket(adapter_id) and converts the retrieved packet payload in a std::vector<bool> More...
int	sendPacket (int adapter_id, unsigned char *packet_buffer, int buffer_size)
	Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages) More...
int	sendPacket (std::string adapter_name, unsigned char *packet_buffer, int buffer_size)
	Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages) More...
int	sendPacket (int adapter_id, std::vector< bool > packet_data)
	Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages) More...
int	sendPacket (std::string adapter_name, std::vector< bool > packet_data)
	Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages) More...

Static Public Attributes
static const int	ADAPTER_NAME = 0
	value type ID for the adapter name (used as parameter in adapterId(...))
static const int	ADAPTER_DESCRIPTION = 1
	value type ID for the adapter description (used as parameter in adapterId(...))
static const int	ADAPTER_ADDRESS = 2
	value type ID for the adapter address (used as parameter in adapterId(...))
static const int	DEFAULT_MAXPACKETSIZE = 65535
	default maximal packet size to capture entire packets (used as parameter in openAdapter(...))
static const int	RETURN_CODE_BUFFER_SIZE = 20
	defines the size of the last return codes-buffer (retrieved via lastReturnCodes()).
static const int	TIMEOUT_WAIT_FOREVER = 0
	timeout value for openAdapter which can cause retrievePacket(...) and retrievePacketAsVector(...) to wait forever til packets arrive

Private Member Functions
bool	checkForAdapterId (int adapter_id)
	Checks if a given adapter_id exists. More...
char *	ipToString (sockaddr *sockaddr, char *buffer, size_t buffer_size)
	Converts a given socket address to a human readable string.
int	adapterId (std::string value, int key, bool increment_key)
	returns the adapter id from the adapter with the given key.

Private Attributes
std::vector< std::vector < std::string > >	m_adapter_data
	Stores for each adapter its name, the description and each address.
std::vector< pcap_t * >	m_adapter_handles
	Contains all open Adapter handles for each adapter, NULL otherwise.
std::vector< bpf_u_int32 >	m_adapter_netmasks
	Contains the netmask for each adapter.
pcap_if_t *	m_adapter_raw_data
	Raw adapter data as returned from pcap_findalldevs(...)
boost::circular_buffer< int >	m_last_return_codes
	Stores the last RETURN_CODE_BUFFER_SIZE method return codes.

Detailed Description

Used to receive packets and send TCP packets under win32.

All Functions needed to apply filters, select adapters and send packets are provided.

Member Function Documentation

bool whisper_library::PcapWrapper::checkForAdapterId ( int  adapter_id )

inlineprivate

Checks if a given adapter_id exists.

checkForAdapterId

int whisper_library::PcapWrapper::freeAdapters

(

)

Frees unopened adapters and closes previously opened handles.

Returns

0 - normal execution, -1 Error occured

int whisper_library::PcapWrapper::openAdapter	(	std::string	adapter_name,
		int	max_packet_size,
		bool	promiscuous_mode,
		int	timeout
	)

Opens a live capture handle to the given device.

Parameters

adapter_name	- Name of the adapter (pcap_if_t->name) to open
max_packet_size	- Maximum number of bytes that should be captured from each packet. 65535 is enough for the whole packet in most networks.
promiscuous_mode	- Open in promiscuous mode? false: No, true: Yes.
timeout	- Specifies a timeout in ms. A value of 0 can cause the process to wait forever. promiscuous mode: capture all packets non-promiscuous: capture only packets directed to the application

Returns

0 - normal execution, -1 - Error occured

int whisper_library::PcapWrapper::openAdapter	(	int	adapter_id,
		int	max_packet_size,
		bool	promiscuous_mode,
		int	timeout
	)

Opens a live capture handle to the given device.

Parameters

adapter_id	- internal id of the adapter to open
max_packet_size	- Maximum number of bytes that should be captured from each packet. 65535 is enough for the whole packet in most networks.
promiscuous_mode	- Open in promiscuous mode? false: No, true: Yes.
timeout	- Specifies a timeout in ms. A value of 0 can cause the process to wait forever. promiscuous mode: capture all packets non-promiscuous: capture only packets directed to the application

Returns

0 - normal execution, -1 - Error occured

int whisper_library::PcapWrapper::retrieveAdapters

(

)

Retrieves available network devices from the (local) machine.

Returns

0 - normal execution, -1 - Error occured, -2 - Out of memory 255 - no adapters found

PcapWrapper::PcapPacket whisper_library::PcapWrapper::retrievePacket

(

int

adapter_id

)

Retrieves the next packet from the capture device.

Returns

PcapPacket{NULL, NULL} if adapter was not found or if the specified adapter had no open handle
or PcapPacket{pcap_pkthdr, NULL} if no packet passed through the configured filter
or PcapPacket{pcap_pkthdr, NULL} if no packet arrived in a system dependent time window (timeout)
or PcapPacket{pcap_pkthdr, const u_char*} where const u_char* is the pointer to the packet data with the maximum size configured in openAdapter()

PcapWrapper::PcapPacket whisper_library::PcapWrapper::retrievePacket

(

std::string

adapter_name

)

Retrieves the next packet from the capture device.

Returns

PcapPacket{NULL, NULL} if adapter was not found or if the specified adapter had no open handle
or PcapPacket{pcap_pkthdr, NULL} if no packet passed through the configured filter
or PcapPacket{pcap_pkthdr, NULL} if no packet arrived in a system dependent time window (timeout)
or PcapPacket{pcap_pkthdr, const u_char*} where const u_char* is the pointer to the packet data with the maximum size configured in openAdapter()

std::vector< bool > whisper_library::PcapWrapper::retrievePacketAsVector

(

int

adapter_id

)

Calls retrievePacket(adapter_id) and converts the retrieved packet payload in a std::vector<bool>

Returns

bitwise representation of the packet payload from retrievePacket() as a std::vector<bool>

std::vector< bool > whisper_library::PcapWrapper::retrievePacketAsVector

(

std::string

adapter_name

)

Calls retrievePacket(adapter_id) and converts the retrieved packet payload in a std::vector<bool>

Returns

bitwise representation of the packet payload from retrievePacket() as a std::vector<bool>

int whisper_library::PcapWrapper::sendPacket	(	int	adapter_id,
		unsigned char *	packet_buffer,
		int	buffer_size
	)

Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages)

Returns

RC.NORMAL_EXECUTION - normal execution RC.ADAPTER_NOT_FOUND - adapter with given id not found RC.ACCESS_ON_UNOPENED_HANDLE - tried to access an unopened adapter (use openAdapter(...) beforehand) RC.UNSPECIFIED_ERROR_OCCURED - otherwise

int whisper_library::PcapWrapper::sendPacket	(	std::string	adapter_name,
		unsigned char *	packet_buffer,
		int	buffer_size
	)

Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages)

Returns

RC.NORMAL_EXECUTION - normal execution RC.ADAPTER_NOT_FOUND - adapter with given id not found RC.ACCESS_ON_UNOPENED_HANDLE - tried to access an unopened adapter (use openAdapter(...) beforehand) RC.UNSPECIFIED_ERROR_OCCURED - otherwise

int whisper_library::PcapWrapper::sendPacket	(	int	adapter_id,
		std::vector< bool >	packet_data
	)

Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages)

Returns

RC.NORMAL_EXECUTION - normal execution RC.ADAPTER_NOT_FOUND - adapter with given id not found RC.ACCESS_ON_UNOPENED_HANDLE - tried to access an unopened adapter (use openAdapter(...) beforehand) RC.UNSPECIFIED_ERROR_OCCURED - otherwise

int whisper_library::PcapWrapper::sendPacket	(	std::string	adapter_name,
		std::vector< bool >	packet_data
	)

Sends a packet using a raw socket via the WinPcap driver (Note: libcap on linux currently doesn't allow sending packages)

Returns

RC.NORMAL_EXECUTION - normal execution RC.ADAPTER_NOT_FOUND - adapter with given id not found RC.ACCESS_ON_UNOPENED_HANDLE - tried to access an unopened adapter (use openAdapter(...) beforehand) RC.UNSPECIFIED_ERROR_OCCURED - otherwise