org.jnetpcap.packet
Class JPacket

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

All Implemented Interfaces:

JByteBuffer

Direct Known Subclasses:

JMemoryPacket, PcapPacket

public abstract class JPacket
extends JBuffer

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 JBuffer	memory The allocated memory buffer.
protected static JMemoryPool	pool Packet's default memory pool out of which allocates memory for deep copies
protected static JScanner	scanner Default scanner used to scan a packet per user request
protected JPacket.State	state Packet's state structure

Fields inherited from class org.jnetpcap.nio.JMemory

JNETPCAP_LIBRARY_NAME

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

<T extends JAnalysis> void	addAnalysis(T analysis)
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
<T extends JAnalysis> T	getAnalysis(java.lang.Class<? extends JHeader> c, T analysis)
<T extends JAnalysis> T	getAnalysis(int id, int instance, T analysis)
<T extends JAnalysis> T	getAnalysis(int id, T analysis)
<T extends JAnalysis> T	getAnalysis(T analysis)
abstract JCaptureHeader	getCaptureHeader() Gets the capture header as generated by the native capture library.
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.
JPacket.State	getState() Gets the peered packet state object
abstract int	getTotalSize() Gets the total size of this packet.
int	getType()
boolean	hasAnalysis(java.lang.Class<? extends JAnalysis> analysis)
boolean	hasAnalysis(int type)
<T extends JAnalysis> boolean	hasAnalysis(T analysis)
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 toString() method.
static void	setMemoryPool(JMemoryPool pool) Replaces the default memory allocation mechanism with user supplied one.
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, 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, setUByte, setUInt, setUShort, transferFrom, transferFrom, transferFrom, transferTo, transferTo, transferTo

Methods inherited from class org.jnetpcap.nio.JMemory

check, cleanup, finalize, isInitialized, isJMemoryBasedOwner, isOwner, peer, setSize, size, toDebugString, toHexdump, toHexdump, totalActiveAllocated, totalAllocateCalls, totalAllocated, totalAllocatedSegments0To255Bytes, totalAllocatedSegments256OrAbove, totalDeAllocateCalls, totalDeAllocated, transferFrom, transferFrom, transferFromDirect, transferOwnership, transferTo, transferTo, transferTo, transferTo, transferTo

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.jnetpcap.nio.JByteBuffer

size

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

pool

protected static JMemoryPool pool

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

scanner

protected static JScanner scanner

Default scanner used to scan a packet per user request

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.

Method Detail

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 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.

Parameters:

out - new formatter

setMemoryPool

public static void setMemoryPool(JMemoryPool pool)

Replaces the default memory allocation mechanism with user supplied one.

Parameters:

pool - new memory pool to use.

addAnalysis

public <T extends JAnalysis> void addAnalysis(T analysis)

Parameters:

sequence -

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

getAnalysis

public <T extends JAnalysis> T getAnalysis(T analysis)

getAnalysis

public <T extends JAnalysis> T getAnalysis(int id,
                                           T analysis)

getAnalysis

public <T extends JAnalysis> T getAnalysis(int id,
                                           int instance,
                                           T analysis)

getAnalysis

public <T extends JAnalysis> T getAnalysis(java.lang.Class<? extends JHeader> c,
                                           T analysis)

getCaptureHeader

public abstract JCaptureHeader getCaptureHeader()

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

Returns:

capture header

getHeader

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

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

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.

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.

Type Parameters:

T - name of the header

Parameters:

header - instance of a header object

index - index into the header array the scanner has found

Returns:

the supplied header

Throws:

java.lang.IndexOutOfBoundsException

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

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

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.

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

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

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

getType

public int getType()

hasAnalysis

public boolean hasAnalysis(int type)

hasAnalysis

public boolean hasAnalysis(java.lang.Class<? extends JAnalysis> analysis)

hasAnalysis

public <T extends JAnalysis> boolean hasAnalysis(T analysis)

hasHeader

public boolean hasHeader(int id)

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

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

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.

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.

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

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

getFrameNumber

public long getFrameNumber()

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

Returns:

zero based frame number