#include <IPReassembly.h>

Classes
class	IPv4PacketKey

class	IPv6PacketKey

class	PacketKey

Public Types
enum	ReassemblyStatus { NON_IP_PACKET = 0x00, NON_FRAGMENT = 0x01, FIRST_FRAGMENT = 0x02, FRAGMENT = 0x04, OUT_OF_ORDER_FRAGMENT = 0x08, MALFORMED_FRAGMENT = 0x10, REASSEMBLED = 0x20 }

typedef void(*	OnFragmentsClean) (const PacketKey key, void userCookie)

Public Member Functions
	IPReassembly (OnFragmentsClean onFragmentsCleanCallback=NULL, void *callbackUserCookie=NULL, size_t maxPacketsToStore=500000)

	~IPReassembly ()

Packet *	processPacket (Packet *fragment, ReassemblyStatus &status, ProtocolType parseUntil=UnknownProtocol, OsiModelLayer parseUntilLayer=OsiModelLayerUnknown)

Packet *	processPacket (RawPacket *fragment, ReassemblyStatus &status, ProtocolType parseUntil=UnknownProtocol, OsiModelLayer parseUntilLayer=OsiModelLayerUnknown)

Packet *	getCurrentPacket (const PacketKey &key)

void	removePacket (const PacketKey &key)

size_t	getMaxCapacity () const

size_t	getCurrentCapacity () const

Detailed Description

Contains the IP reassembly (a.k.a IP de-fragmentation) mechanism. Encapsulates both IPv4 and IPv6 reassembly. Please refer to the documentation at the top of IPReassembly.h to understand how this mechanism works. The main APIs are:

IPReassembly::processPacket() - process a fragment. This is the main method which should be called whenever a new fragment arrives. This method processes the fragment, runs the reassembly logic and returns the result packet when it's fully reassembled
IPReassembly::getCurrentPacket() - get the reassembled data that is currently available, even if reassembly process is not yet completed
IPReassembly::removePacket() - remove all data that is currently stored for a packet, including the reassembled data that was gathered so far

Member Typedef Documentation

◆ OnFragmentsClean

pcpp::IPReassembly::OnFragmentsClean

The IP reassembly mechanism has a certain capacity of concurrent packets it can handle. This capacity is determined in its c'tor (default value is PCPP_IP_REASSEMBLY_DEFAULT_MAX_PACKETS_TO_STORE). When traffic volume exceeds this capacity the mechanism starts dropping packets in a LRU manner (least recently used are dropped first). Whenever a packet is dropped this callback is fired

Parameters

[in]	key	A pointer to the identifier of the packet that is being dropped
[in]	userCookie	A pointer to the cookie provided by the user in IPReassemby c'tor (or NULL if no cookie provided)

Member Enumeration Documentation

◆ ReassemblyStatus

enum pcpp::IPReassembly::ReassemblyStatus

An enum representing the status returned from processing a fragment

Enumerator
NON_IP_PACKET	The processed packet isn't of type IPv4 or IPv6
NON_FRAGMENT	The processed packet isn't a fragment
FIRST_FRAGMENT	The processed fragment is the first fragment
FRAGMENT	The processed fragment is a fragment (but not the first one)
OUT_OF_ORDER_FRAGMENT	The processed fragment is not the fragment that was expected at this time
MALFORMED_FRAGMENT	The processed fragment is malformed, meaning a fragment which has offset of zero but isn't the first fragment
REASSEMBLED	Packet is now fully reassembled

Constructor & Destructor Documentation

◆ IPReassembly()

pcpp::IPReassembly::IPReassembly	(	OnFragmentsClean	onFragmentsCleanCallback = `NULL`,
		void *	callbackUserCookie = `NULL`,
		size_t	maxPacketsToStore = `500000`
	)

inline

A c'tor for this class.

Parameters

[in]	onFragmentsCleanCallback	The callback to be called when packets are dropped due to capacity limit. Please read more about capacity limit in IPReassembly.h file description. This parameter is optional, default value is NULL (no callback)
[in]	callbackUserCookie	A pointer to an object provided by the user. This pointer will be returned when invoking the onFragmentsCleanCallback. This parameter is optional, default cookie is NULL
[in]	maxPacketsToStore	Set the capacity limit of the IP reassembly mechanism. Default capacity is PCPP_IP_REASSEMBLY_DEFAULT_MAX_PACKETS_TO_STORE

◆ ~IPReassembly()

pcpp::IPReassembly::~IPReassembly ( )

A d'tor for this class

Member Function Documentation

◆ getCurrentCapacity()

size_t pcpp::IPReassembly::getCurrentCapacity ( ) const

inline

Get the current number of packets being processed

◆ getCurrentPacket()

Packet* pcpp::IPReassembly::getCurrentPacket ( const PacketKey & key )

Get a partially reassembled packet. This method returns all the reassembled data that was gathered so far which is obviously not a fully reassembled packet (otherwise it would have returned by processPacket()). Notice all data is being copied so the user is responsible to free the returned Packet object when done using it. Notice#2 - calling this method doesn't interfere with the reassembly of this packet - all internal structures and data remain

Parameters

[in] key The identifiers of the packet to return

Returns: A pointer to a Packet object containing the partially reassembled packet. Notice the user is responsible to free this object when done using it

◆ getMaxCapacity()

size_t pcpp::IPReassembly::getMaxCapacity ( ) const

inline

Get the maximum capacity as determined in the c'tor

◆ processPacket() [1/2]

Packet* pcpp::IPReassembly::processPacket	(	Packet *	fragment,
		ReassemblyStatus &	status,
		ProtocolType	parseUntil = `UnknownProtocol`,
		OsiModelLayer	parseUntilLayer = `OsiModelLayerUnknown`
	)

The main API that drives IPReassembly. This method should be called whenever a fragment arrives. This method finds the relevant packet this fragment belongs to and runs the IP reassembly logic that is described in IPReassembly.h.

Parameters

[in]	fragment	The fragment to process (IPv4 or IPv6). Please notice that the reassembly logic doesn't change or manipulate this object in any way. All of its data is copied to internal structures and manipulated there
[out]	status	An indication of the packet reassembly status following the processing of this fragment. Possible values are: The input fragment is not a IPv4 or IPv6 packet The input fragment is not a IPv4 or IPv6 fragment packet The input fragment is the first fragment of the packet The input fragment is not the first or last fragment The input fragment came out-of-order, meaning that wasn't the fragment that was currently expected (it's data is copied to the out-of-order fragment list) The input fragment is malformed and will be ignored The input fragment is the last one and the packet is now fully reassembled. In this case the return value will contain a pointer to the reassebmled packet
[in]	parseUntil	Optional parameter. Parse the reassembled packet until you reach a certain protocol (inclusive). Can be useful for cases when you need to parse only up to a certain layer and want to avoid the performance impact and memory consumption of parsing the whole packet. Default value is UnknownProtocol which means don't take this parameter into account
[in]	parseUntilLayer	Optional parameter. Parse the reassembled packet until you reach a certain layer in the OSI model (inclusive). Can be useful for cases when you need to parse only up to a certain OSI layer (for example transport layer) and want to avoid the performance impact and memory consumption of parsing the whole packet. Default value is OsiModelLayerUnknown which means don't take this parameter into account

Returns

If the input fragment isn't an IPv4/IPv6 packet or if it isn't an IPv4/IPv6 fragment, the return value is a pointer to the input fragment
If the input fragment is the last one and the reassembled packet is ready - a pointer to the reassembled packet is returned. Notice it's the user's responsibility to free this pointer when done using it
If the reassembled packet isn't ready then NULL is returned

◆ processPacket() [2/2]

Packet* pcpp::IPReassembly::processPacket	(	RawPacket *	fragment,
		ReassemblyStatus &	status,
		ProtocolType	parseUntil = `UnknownProtocol`,
		OsiModelLayer	parseUntilLayer = `OsiModelLayerUnknown`
	)

The main API that drives IPReassembly. This method should be called whenever a fragment arrives. This method finds the relevant packet this fragment belongs to and runs the IPv4 reassembly logic that is described in IPReassembly.h.

Parameters

[in]	fragment	The fragment to process (IPv4 or IPv6). Please notice that the reassembly logic doesn't change or manipulate this object in any way. All of its data is copied to internal structures and manipulated there
[out]	status	An indication of the packet reassembly status following the processing of this fragment. Possible values are: The input fragment is not a IPv4 or IPv6 packet The input fragment is not a IPv4 or IPv6 fragment packet The input fragment is the first fragment of the packet The input fragment is not the first or last fragment The input fragment came out-of-order, meaning that wasn't the fragment that was currently expected (it's data is copied to the out-of-order fragment list) The input fragment is malformed and will be ignored The input fragment is the last one and the packet is now fully reassembled. In this case the return value will contain a pointer to the reassebmled packet
[in]	parseUntil	Optional parameter. Parse the raw and reassembled packets until you reach a certain protocol (inclusive). Can be useful for cases when you need to parse only up to a certain layer and want to avoid the performance impact and memory consumption of parsing the whole packet. Default value is UnknownProtocol which means don't take this parameter into account
[in]	parseUntilLayer	Optional parameter. Parse the raw and reassembled packets until you reach a certain layer in the OSI model (inclusive). Can be useful for cases when you need to parse only up to a certain OSI layer (for example transport layer) and want to avoid the performance impact and memory consumption of parsing the whole packet. Default value is OsiModelLayerUnknown which means don't take this parameter into account

Returns

If the input fragment isn't an IPv4/IPv6 packet or if it isn't an IPv4/IPv6 fragment, the return value is a pointer to a Packet object wrapping the input fragment RawPacket object. It's the user responsibility to free this instance
If the input fragment is the last one and the reassembled packet is ready - a pointer to the reassembled packet is returned. Notice it's the user's responsibility to free this pointer when done using it
If the reassembled packet isn't ready then NULL is returned

◆ removePacket()

void pcpp::IPReassembly::removePacket ( const PacketKey & key )

Remove a partially reassembled packet from all internal structures. That means that if another fragment of this packet appears it will be treated as a new packet

Parameters

[in] key The identifiers of the packet to remove

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ OnFragmentsClean

Member Enumeration Documentation

◆ ReassemblyStatus

Constructor & Destructor Documentation

◆ IPReassembly()

◆ ~IPReassembly()

Member Function Documentation

◆ getCurrentCapacity()

◆ getCurrentPacket()

◆ getMaxCapacity()

◆ processPacket() [1/2]

◆ processPacket() [2/2]

◆ removePacket()