org.jnetpcap.packet
Class JPacket.State

java.lang.Object
  org.jnetpcap.nio.JMemory
      org.jnetpcap.nio.JStruct
          org.jnetpcap.packet.JPacket.State

Enclosing class:

JPacket

public static class JPacket.State
extends JStruct

Class maintains the decoded packet state. The class is peered with struct packet_state_t

 typedef struct packet_state_t {
        uint64_t pkt_header_map; // bit map of presence of headers
        char *pkt_data; // packet data buffer
        int32_t pkt_header_count; // total number of headers found
 
        // Keep track of how many instances of each header we have
        uint8_t pkt_instance_counts[MAX_ID_COUNT];
        header_t pkt_headers[]; // One per header + 1 more for payload
 } packet_t;
 

and struct header_t

 typedef struct header_t {
        int32_t hdr_id; // header ID
        uint32_t hdr_offset; // offset into the packet_t->data buffer
        int32_t hdr_length; // length of the header in packet_t->data buffer
 } header_t;
 
 

The methods in this State provide 3 sets of functions. Looking up global state of the packet found in packet_state_t structure, looking up header information in struct header_t by header ID retrieved from JRegistry and instance numbers, looking up header information by direct indexes into native maps and arrays. Instance numbers specify which instance of the header, if more than 1 exists in a packet. For example if there is a packet with 2 Ip4 headers such as

 Ethernet->Ip4->Snmp->Ip4 
 or 
 Ethernet->Ip4->Ip4 (IP tunneled IP)
 

the first Ip4 header is instance 0 and the second Ip4 header is instance 2. You can use the method getInstanceCount(int) to learn how many instance headers exists. That information is stored in the packet_state_t structure for efficiency.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

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

JMemory.Type

Field Summary

static java.lang.String

STRUCT_NAME

Fields inherited from class org.jnetpcap.nio.JMemory

JNETPCAP_LIBRARY_NAME

Constructor Summary

JPacket.State(int size)

JPacket.State(JMemory.Type type)

Method Summary

void	cleanup() Called to clean up and release any allocated memory.
int	findHeaderIndex(int id)
int	findHeaderIndex(int id, int instance)
long	get64BitHeaderMap(int index)
JAnalysis	getAnalysis() Retrieves the analysis object that is attached to this packet.
JAnalysis	getAnalysis(int index) Retrieves the analysis object htat is attached to the header at index.
JFlowKey	getFlowKey()
long	getFrameNumber() The frame number is assigned by the scanner at the time of the scan.
int	getHeaderCount()
int	getHeaderIdByIndex(int index)
int	getInstanceCount(int id)
int	peer(java.nio.ByteBuffer peer) Peers the src structure with this instance.
int	peer(JBuffer peer)
int	peer(JBuffer peer, int offset, int length)
int	peer(JMemory memory, int offset)
int	peer(JMemoryPool.Block peer, int offset, int length)
int	peer(JPacket.State peer)
int	peerHeaderById(int id, int instance, JHeader.State dst)
int	peerHeaderByIndex(int index, JHeader.State dst)
int	peerTo(JBuffer buffer, int offset) Peers this packet's state to buffer
int	peerTo(JBuffer buffer, int offset, int size) Peers this packet's state to buffer
int	peerTo(JPacket.State state, int offset)
void	setAnalysis(JAnalysis analysis) Sets the analysis object for this packet.
static int	sizeof(int count)
java.lang.String	toDebugString() Dump packet_state_t structure and its sub structures to textual debug output
int	transferTo(byte[] dst, int dstOffset)
int	transferTo(byte[] dst, int srcOffset, int length, int dstOffset) Copies data from memory to byte array
int	transferTo(JBuffer dst, int srcOffset, int length, int dstOffset) Transfers the contents of this memory to buffer.
int	transferTo(JPacket.State dst)

Methods inherited from class org.jnetpcap.nio.JStruct

getStructName, toString

Methods inherited from class org.jnetpcap.nio.JMemory

check, finalize, isInitialized, isJMemoryBasedOwner, isOwner, peer, peer, setSize, size, toHexdump, toHexdump, totalActiveAllocated, totalAllocateCalls, totalAllocated, totalAllocatedSegments0To255Bytes, totalAllocatedSegments256OrAbove, totalDeAllocateCalls, totalDeAllocated, transferFrom, transferFrom, 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

Field Detail

STRUCT_NAME

public static final java.lang.String STRUCT_NAME

See Also:

Constant Field Values

Constructor Detail

JPacket.State

public JPacket.State(int size)

Parameters:

size -

JPacket.State

public JPacket.State(JMemory.Type type)

Method Detail

sizeof

public static int sizeof(int count)

Parameters:

count - header counter, number of headers to calaculate in

Returns:

size in bytes

cleanup

public void cleanup()

Description copied from class: JMemory

Called to clean up and release any allocated memory. This method should be overriden if the allocated memory is not simply a single memory block and something more complex. This method is safe to call at anytime even if the object does not hold any allocated memory or is not the owner of the memory it is peered with. The method will reset this object to orignal unpeered state releasing any allocated and own memory at the same time if neccessary.

Overrides:

cleanup in class JMemory

findHeaderIndex

public int findHeaderIndex(int id)

findHeaderIndex

public int findHeaderIndex(int id,
                           int instance)

get64BitHeaderMap

public long get64BitHeaderMap(int index)

Parameters:

index - TODO: remove index, its no longer used natively

Returns:

getAnalysis

public JAnalysis getAnalysis()

Retrieves the analysis object that is attached to this packet.

Returns:

an attached analysis based object or null if not set

getAnalysis

public JAnalysis getAnalysis(int index)

Retrieves the analysis object htat is attached to the header at index. This method provides a way to retrive analysis object directly from a header without having to have a reference to the header, only its index in the packet state table of headers.

Parameters:

index - index of the header within the packet state structure

Returns:

attached analysis object or null if none are attached

getFlowKey

public JFlowKey getFlowKey()

getFrameNumber

public long getFrameNumber()

The frame number is assigned by the scanner at the time of the scan. Therefore number is only unique within the same scanner.

Returns:

frame number

getHeaderCount

public int getHeaderCount()

getHeaderIdByIndex

public int getHeaderIdByIndex(int index)

getInstanceCount

public int getInstanceCount(int id)

peer

public int peer(java.nio.ByteBuffer peer)
         throws PeeringException

Description copied from class: JMemory

Peers the src structure with this instance. The physical memory that the src peered object points to is set to this instance. The owner flag is not copied and src remains at the same state as it did before. This instance does not become the owner of the memory.

Further more, since we are peering with a ByteBuffer, the actual memory that is peered is between ByteBuffer's position and limit properties. Those 2 properties determine which portion of the memory that will be peered. This allows a larger ByteBuffer to be peered with different objects providing rudimentary memory allocation mechanism.

Lastly care must be taken, to ensure that the lifespans do not conflict. The memory that we are peering to must not be deallocated prior the termination of the lifespan of this object or at minimum calling JMemory.cleanup() method to ensure that this object no longer references memory which may have been or become deallocated.

Overrides:

peer in class JMemory

Parameters:

peer - The ByteBuffer whose allocated native memory we want to peer with. The ByteByffer must be if direct buffer type which can be checked using ByteBuffer.isDirect() call.

Throws:

PeeringException

See Also:

ByteBuffer.isDirect()

peer

public int peer(JBuffer peer)

peer

public int peer(JBuffer peer,
                int offset,
                int length)
         throws java.lang.IndexOutOfBoundsException

Throws:

java.lang.IndexOutOfBoundsException

peer

public int peer(JMemory memory,
                int offset)

Parameters:

memory -

offset -

peer

public int peer(JMemoryPool.Block peer,
                int offset,
                int length)
         throws java.lang.IndexOutOfBoundsException

Throws:

java.lang.IndexOutOfBoundsException

peer

public int peer(JPacket.State peer)

peerHeaderById

public int peerHeaderById(int id,
                          int instance,
                          JHeader.State dst)

peerHeaderByIndex

public int peerHeaderByIndex(int index,
                             JHeader.State dst)
                      throws java.lang.IndexOutOfBoundsException

Throws:

java.lang.IndexOutOfBoundsException

peerTo

public int peerTo(JBuffer buffer,
                  int offset)

Peers this packet's state to buffer

Parameters:

buffer - source buffer

offset - offset into the buffer

Returns:

number of bytes peered

peerTo

public int peerTo(JBuffer buffer,
                  int offset,
                  int size)

Peers this packet's state to buffer

Parameters:

buffer - source buffer

offset - offset into the buffer

size - specifies the number of bytes to peer

Returns:

number of bytes peered

peerTo

public int peerTo(JPacket.State state,
                  int offset)

Parameters:

state -

offset -

setAnalysis

public void setAnalysis(JAnalysis analysis)

Sets the analysis object for this packet.

Parameters:

analysis -

toDebugString

public java.lang.String toDebugString()

Dump packet_state_t structure and its sub structures to textual debug output

Explanation:

 sizeof(packet_state_t)=16
 sizeof(header_t)=8 and *4=32
 pkt_header_map=0x1007         // bitmap, each bit represets a header
 pkt_header_count=4            // how many header found
 // per header information (4 header found in this example)
 pkt_headers[0]=<hdr_id=1  ETHERNET ,hdr_offset=0  ,hdr_length=14>
 pkt_headers[1]=<hdr_id=2  IP4      ,hdr_offset=14 ,hdr_length=60>
 pkt_headers[2]=<hdr_id=12 ICMP     ,hdr_offset=74 ,hdr_length=2>
 pkt_headers[3]=<hdr_id=0  PAYLOAD  ,hdr_offset=76 ,hdr_length=62>
 
 // hdr_id = numerical ID of the header, asssigned by JRegistry
 // hdr_offset = offset in bytes into the packet buffer
 // hdr_length = length in bytes of the entire header
 

Packet state is made up of 2 structures: packet_stat_t and an array of header_t, one per header. Total size in bytes is all of the header structures combined, that is 16 + 32 = 48 bytes. Each bit in the header_map represents the presence of that header type. The index of the bit is the numerical ID of the header. If 2 headers of the same type are present, they are both represented by a single bit in the bitmap. This way the implementation JPacket.hasHeader(int id) is a simple bit operation to test if the header is present or not.

Overrides:

toDebugString in class JMemory

Returns:

multiline string containing dump of the entire structure

transferTo

public int transferTo(byte[] dst,
                      int dstOffset)

transferTo

public int transferTo(byte[] dst,
                      int srcOffset,
                      int length,
                      int dstOffset)

Description copied from class: JMemory

Copies data from memory to byte array

Overrides:

transferTo in class JMemory

Parameters:

dst - destination buffer

srcOffset - starting offset in memory

length - number of bytes to copy

dstOffset - starting offset in byte array

Returns:

number of bytes copied

transferTo

public int transferTo(JBuffer dst,
                      int srcOffset,
                      int length,
                      int dstOffset)

Description copied from class: JMemory

Transfers the contents of this memory to buffer.

Overrides:

transferTo in class JMemory

Parameters:

dst - destination buffer

srcOffset - offset in source

length - number of bytes to copy

dstOffset - offset in destination buffer

Returns:

number of bytes copied

transferTo

public int transferTo(JPacket.State dst)