org.jnetpcap.packet
Class JPacket

java.lang.Object
  org.jnetpcap.nio.JMemory
      org.jnetpcap.nio.JBuffer
          org.jnetpcap.packet.JPacket

All Implemented Interfaces:

JHeaderAccessor

Direct Known Subclasses:

JMemoryPacket, PcapPacket

public abstract class JPacket
extends JBuffer
implements JHeaderAccessor

A native packet buffer object. This class references both packet data buffer and decoded native packet structure. JPacket class is a subclass of a more general JBuffer providing full access to raw packet buffer data. It also has a reference to JPacket.State object which is peered, associated with, a native packet state structure generated by the packet scanner, the JScanner.

The packet interface provides numerous methods for accessing the decoded information. To check if any particular header is found within the packet's data buffer at the time the packet was scanned, the user can use hasHeader(int) methods. The method returns true if a particular header is found within the packet data buffer, otherwise false. A convenience method hasHeader(JHeader) exists that performs both an existance check and initializes the header instace supplied to point at the header within the packet.

There are also numerous peer and deep copy methods. The peering methods do not copy any buffers but simply re-orient the pointers to point at the source peer structures to destination peer. The deep copy methods do copy physical data out of buffers and entire structures using native copy functions, not in java space.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

static class

JPacket.State Class maintains the decoded packet state.

Nested classes/interfaces inherited from class org.jnetpcap.nio.JMemory

JMemory.Type

Field Summary

static int	DEFAULT_STATE_HEADER_COUNT Default number of headers used when calculating memory requirements for an empty packet state structure.
protected static JScanner	defaultScanner Default scanner used to scan a packet per user request.
protected JBuffer	memory The allocated memory buffer.
protected static JMemoryPool	pool Packet's default memory pool out of which allocates memory for deep copies.
protected JPacket.State	state Packet's state structure.

Fields inherited from class org.jnetpcap.nio.JMemory

JNETPCAP_LIBRARY_NAME, MAX_DIRECT_MEMORY_DEFAULT, POINTER

Constructor Summary

JPacket(int size, int state)
Allocates a memory block and peers both the state and data buffer with it.

JPacket(JMemory.Type type)
A JPacket pointer.

Method Summary

void	allocate(int size) Creates a new memory buffer of given size for internal usage.
int	getAllocatedMemorySize() Gets the size of the current internal memory buffer.
abstract JCaptureHeader	getCaptureHeader() Gets the capture header as generated by the native capture library.
static JScanner	getDefaultScanner() Returns the default scanner for all packets
static JFormatter	getFormatter() Gets the current internal packet formatter used in the toString() method.
long	getFrameNumber() Returns the frame number as assigned by either the packet scanner or analyzers.
<T extends JHeader> T	getHeader(T header) Peers the supplied header with the native header state structure and packet data buffer.
<T extends JHeader> T	getHeader(T header, int instance) Peers the supplied header with the native header state structure and packet data buffer.
<T extends JHeader> T	getHeaderByIndex(int index, T header) Peers a header with specific index, not the numerical header ID assigned by JRegistry, of a header.
int	getHeaderCount() Gets number of headers found within the packet header.
int	getHeaderIdByIndex(int index) Gets the numerical ID of the header at specified index into header array as found by the packet scanner.
int	getHeaderInstanceCount(int id) Gets number of headers with the same numerical ID as assigned by JRegistry within the same packet.
protected JBuffer	getMemoryBuffer(byte[] buffer) Gets the memory buffer with the supplied byte array data copied into it.
protected JBuffer	getMemoryBuffer(java.nio.ByteBuffer buffer) Gets the memory buffer with the supplied ByteBuffer data copied into it.
protected JBuffer	getMemoryBuffer(int minSize) Retrieves a memory buffer, allocated if neccessary, at least minSize in bytes.
protected JBuffer	getMemoryBuffer(JBuffer buffer) Gets the memory buffer with the supplied JBuffer data copied into it.
static JMemoryPool	getMemoryPool() Gets the current memory allocation memory pool.
int	getPacketWirelen() Gets the wire length of the packet.
JScanner	getScanner() Deprecated. use static getDefaultScanner() instead
JPacket.State	getState() Gets the peered packet state object
abstract int	getTotalSize() Gets the total size of this packet.
boolean	hasHeader(int id) Checks if header with specified numerical ID exists within the decoded packet.
boolean	hasHeader(int id, int instance) Check if requested instance of header with specified numerical ID exists within the decoded packet.
<T extends JHeader> boolean	hasHeader(T header) Check if requested instance of header with specified numerical ID exists within the decoded packet and if found peers the supplied header with the located header within the decoded packet.
<T extends JHeader> boolean	hasHeader(T header, int instance) Check if requested instance of header with specified numerical ID exists within the decoded packet and if found peers the supplied header with the located header within the decoded packet.
int	remaining(int offset) Calculates the number of bytes remaining within the packet given a specific offset.
int	remaining(int offset, int length) Calculates the remaining number of bytes within the packet buffer taking into account offset and length of a header supplied.
void	scan(int id) Scan and decode the packet using current scanner.
static void	setFormatter(JFormatter out) Replaced the default formatter for formatting output in the.
static void	setMemoryPool(JMemoryPool pool) Replaces the default memory allocation mechanism with user supplied one.
static void	shutdown() Shutdown.
java.lang.String	toHexdump() Formats packet raw data as a hexdump output and marks header boundaries with special characters.
java.lang.String	toString() Generates text formatted output using the default builtin formatter.

Methods inherited from class org.jnetpcap.nio.JBuffer

findUTF8String, getByte, getByteArray, getByteArray, getByteArray, getDouble, getFloat, getInt, getLong, getShort, getUByte, getUInt, getUShort, getUTF8Char, getUTF8String, getUTF8String, getUTF8String, getUTF8String, isReadonly, order, order, peer, peer, peer, peer, setByte, setByteArray, setByteBuffer, setDouble, setFloat, setInt, setLong, setShort, setShort0, setUByte, setUInt, setUShort, transferFrom, transferFrom, transferFrom, transferTo, transferTo, transferTo

Methods inherited from class org.jnetpcap.nio.JMemory

availableDirectMemory, check, cleanup, createReference, isInitialized, isJMemoryBasedOwner, isOwner, maxDirectMemory, peer, reservedDirectMemory, setSize, size, softDirectMemory, toDebugString, toHexdump, totalActiveAllocated, totalAllocateCalls, totalAllocated, totalAllocatedSegments0To255Bytes, totalAllocatedSegments256OrAbove, totalDeAllocateCalls, totalDeAllocated, transferFrom, transferFrom, transferFromDirect, transferOwnership, transferTo, transferTo, transferTo, transferTo, transferTo, transferTo0

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_STATE_HEADER_COUNT

public static final int DEFAULT_STATE_HEADER_COUNT

Default number of headers used when calculating memory requirements for an empty packet state structure. This value will be multiplied by the sizeof(header_t) structure and added to the size of the packet_t strcutre.

See Also:

Constant Field Values

defaultScanner

protected static JScanner defaultScanner

Default scanner used to scan a packet per user request.

pool

protected static JMemoryPool pool

Packet's default memory pool out of which allocates memory for deep copies.

memory

protected final JBuffer memory

The allocated memory buffer. Initialy this buffer is empty, but may be peered with allocated memory for internal usage such as copying header, state and data into a single buffer

state

protected final JPacket.State state

Packet's state structure.

Constructor Detail

JPacket

public JPacket(int size,
               int state)

Allocates a memory block and peers both the state and data buffer with it. The size parameter has to be big enough to hold both state and data for the packet.

Parameters:

size - amount of memory to allocate for packet data

state - size of the state

JPacket

public JPacket(JMemory.Type type)

A JPacket pointer. This is a pointer type constructor that does not allocate any memory but its intended to be pointed at a scanner packet_t structure that contains meta information about the structure of the packet data buffer.

JPacket constists of 2 peers. The first and the main memory peering is with the packet_state_t structure which stores information about the decoded state of the packet, another words the result of the scanned packet data buffer. The second peer is to the actual packet data buffer which is a seperate pointer.

Peering struct packet_t

This structure contains the "packet state". This is the decoded state which specifies what headers are in the buffer and at what offsets. This structure is the output of a JScanner.scan() method. The memory for this state can be anywhere, but by default JScanner stores it in a round-robin buffer it uses for decoding fast incoming packets. The state can easily be copied into another buffer for longer storage using such methods as transferStateAndDataTo which will copy the packet state and/or data buffer into another memory area, such as a direct ByteBuffer or JBuffer.

Parameters:

type - the type

Method Detail

getDefaultScanner

public static JScanner getDefaultScanner()

Returns the default scanner for all packets

Returns:

the current default scanner

shutdown

public static void shutdown()

Shutdown.

getFormatter

public static JFormatter getFormatter()

Gets the current internal packet formatter used in the toString() method.

Returns:

current formatter

getMemoryPool

public static JMemoryPool getMemoryPool()

Gets the current memory allocation memory pool.

Returns:

current memory pool

setFormatter

public static void setFormatter(JFormatter out)

Replaced the default formatter for formatting output in the.

Parameters:

out - new formatter toString() method. The new formatter will be used by default for all packets. The formatter should internally build a string that will be returned with out.toString() method call to get meaningfull output.

setMemoryPool

public static void setMemoryPool(JMemoryPool pool)

Replaces the default memory allocation mechanism with user supplied one.

Parameters:

pool - new memory pool to use.

allocate

public void allocate(int size)

Creates a new memory buffer of given size for internal usage.

Parameters:

size - size in bytes

getAllocatedMemorySize

public int getAllocatedMemorySize()

Gets the size of the current internal memory buffer.

Returns:

length in bytes

getCaptureHeader

public abstract JCaptureHeader getCaptureHeader()

Gets the capture header as generated by the native capture library.

Returns:

capture header

getFrameNumber

public long getFrameNumber()

Returns the frame number as assigned by either the packet scanner or analyzers.

Returns:

zero based frame number

getHeader

public <T extends JHeader> T getHeader(T header)

Peers the supplied header with the native header state structure and packet data buffer.

Specified by:

getHeader in interface JHeaderAccessor

Type Parameters:

T - name of the header

Parameters:

header - instance of a header object

Returns:

the supplied instance of the header

getHeader

public <T extends JHeader> T getHeader(T header,
                                       int instance)

Peers the supplied header with the native header state structure and packet data buffer. This method allows retrieval of a specific instance of a header if more than one instance has been found.

Specified by:

getHeader in interface JHeaderAccessor

Type Parameters:

T - name of the header

Parameters:

header - instance of a header object

instance - instance number of the header since more than one header of the same type can exist in the same packet buffer

Returns:

the supplied instance of the header

getHeaderByIndex

public <T extends JHeader> T getHeaderByIndex(int index,
                                              T header)
                                   throws java.lang.IndexOutOfBoundsException

Peers a header with specific index, not the numerical header ID assigned by JRegistry, of a header.

Specified by:

getHeaderByIndex in interface JHeaderAccessor

Type Parameters:

T - name of the header

Parameters:

index - index into the header array the scanner has found

header - instance of a header object

Returns:

the supplied header

Throws:

java.lang.IndexOutOfBoundsException - the index out of bounds exception

getHeaderCount

public int getHeaderCount()

Gets number of headers found within the packet header. The last header may or may not be the builtin Payload header

Specified by:

getHeaderCount in interface JHeaderAccessor

Returns:

number of headers present

getHeaderIdByIndex

public int getHeaderIdByIndex(int index)

Gets the numerical ID of the header at specified index into header array as found by the packet scanner.

Specified by:

getHeaderIdByIndex in interface JHeaderAccessor

Parameters:

index - index into the header array

Returns:

numerical ID of the header found at the specific index

getHeaderInstanceCount

public int getHeaderInstanceCount(int id)

Gets number of headers with the same numerical ID as assigned by JRegistry within the same packet. For example Ip4 in ip4 packet would contain 2 instances of Ip4 header.

Specified by:

getHeaderInstanceCount in interface JHeaderAccessor

Parameters:

id - numerical ID of the header to search for

Returns:

number of headers of the same type in the packet

getMemoryBuffer

protected JBuffer getMemoryBuffer(byte[] buffer)

Gets the memory buffer with the supplied byte array data copied into it. The internal memory buffer is allocated if neccessary.

Parameters:

buffer - source array buffer to copy data out of

Returns:

the memory buffer

getMemoryBuffer

protected JBuffer getMemoryBuffer(java.nio.ByteBuffer buffer)
                           throws PeeringException

Gets the memory buffer with the supplied ByteBuffer data copied into it. The internal memory buffer is allocated if neccessary.

Parameters:

buffer - source array buffer to copy data out of

Returns:

the memory buffer

Throws:

PeeringException - the peering exception

getMemoryBuffer

protected JBuffer getMemoryBuffer(int minSize)

Retrieves a memory buffer, allocated if neccessary, at least minSize in bytes. If existing buffer is already big enough, it is returned, otherwise a new buffer is allocated and the existing one released.

Parameters:

minSize - minimum number of bytes required for the buffer

Returns:

the buffer

getMemoryBuffer

protected JBuffer getMemoryBuffer(JBuffer buffer)

Gets the memory buffer with the supplied JBuffer data copied into it. The internal memory buffer is allocated if neccessary.

Parameters:

buffer - source array buffer to copy data out of

Returns:

the memory buffer

getPacketWirelen

public int getPacketWirelen()

Gets the wire length of the packet. This is the original length as seen on the wire. This length may different JPacket.size() length, as the packet may have been truncated at the time of the capture.

Returns:

original packet length

getScanner

@Deprecated
public JScanner getScanner()

Deprecated. use static getDefaultScanner() instead

Gets the current default scanner.

Returns:

current default scanner

getState

public JPacket.State getState()

Gets the peered packet state object

Returns:

packet native state

getTotalSize

public abstract int getTotalSize()

Gets the total size of this packet. The size includes state, header and packet data.

Returns:

size in bytes

hasHeader

public boolean hasHeader(int id)

Checks if header with specified numerical ID exists within the decoded packet.

Specified by:

hasHeader in interface JHeaderAccessor

Parameters:

id - protocol header ID as assigned by JRegistry

Returns:

true header exists, otherwise false

hasHeader

public boolean hasHeader(int id,
                         int instance)

Check if requested instance of header with specified numerical ID exists within the decoded packet.

Specified by:

hasHeader in interface JHeaderAccessor

Parameters:

id - protocol header ID as assigned by JRegistry

instance - instance number of the specific header within the packet

Returns:

true header exists, otherwise false

hasHeader

public <T extends JHeader> boolean hasHeader(T header)

Check if requested instance of header with specified numerical ID exists within the decoded packet and if found peers the supplied header with the located header within the decoded packet. This method executes as hasHeader followed by getHeader if found more efficiently.

Specified by:

hasHeader in interface JHeaderAccessor

Type Parameters:

T - name of the header type

Parameters:

header - protocol header object instance

Returns:

true header exists, otherwise false

hasHeader

public <T extends JHeader> boolean hasHeader(T header,
                                             int instance)

Check if requested instance of header with specified numerical ID exists within the decoded packet and if found peers the supplied header with the located header within the decoded packet. This method executes as hasHeader followed by getHeader if found more efficiently.

Specified by:

hasHeader in interface JHeaderAccessor

Type Parameters:

T - name of the header type

Parameters:

header - protocol header object instance

instance - instance number of the specific header within the packet

Returns:

true header exists, otherwise false

remaining

public int remaining(int offset)

Calculates the number of bytes remaining within the packet given a specific offset.

Parameters:

offset - offset into the packet in bytes

Returns:

number of bytes remaining from specified offset

remaining

public int remaining(int offset,
                     int length)

Calculates the remaining number of bytes within the packet buffer taking into account offset and length of a header supplied. The smaller of the 2 is returned. This should typically be the length field unless the header has been truncated and remaining number of bytes is less.

Parameters:

offset - offset of the header to take into account

length - length of the header

Returns:

smaller number of bytes either remaining or legth

scan

public void scan(int id)

Scan and decode the packet using current scanner. The new packet state replaces any existing packet state already asigned to this packet.

Parameters:

id - numerical ID as assigned by JRegistry of the first protocol header to be found in the packet, the DLT

toHexdump

public java.lang.String toHexdump()

Formats packet raw data as a hexdump output and marks header boundaries with special characters.

Overrides:

toHexdump in class JMemory

Returns:

the string

toString

public java.lang.String toString()

Generates text formatted output using the default builtin formatter. The default is to generate TextFormatter that uses a StringBuilder for output buffer and gerate a single string that is returned from here.

Overrides:

toString in class java.lang.Object

Returns:

formatted output of this packet