org.jnetpcap.packet
Class JHeader

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

All Implemented Interfaces:

JPayloadAccessor

Direct Known Subclasses:

Arp, Ethernet, Html, IEEE802dot1q, IEEE802dot2, IEEE802dot3, IEEESnap, Ip6, JHeaderMap, JMappedHeader, JSubHeader, L2TP, Payload, PPP, Rip, Rtp, SLL, Udp, WebImage

public abstract class JHeader
extends JBuffer
implements JPayloadAccessor

A base class for all protocol header definitions.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

static class

JHeader.State This class is peered state of a header a native state structure

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

JMemory.Type

Field Summary

protected AnnotatedHeader	annotatedHeader The annotated header.
static int	BYTE A constant that defines how many bits there are in a byte.
protected static JHeader[]	EMPTY_HEADER_ARRAY The Constant EMPTY_HEADER_ARRAY.
protected boolean	isSubHeader The is sub header.
protected JPacket	packet A reference to the packet that this header is part of.
protected JHeader.State	state Reference to header's native state structure.

Fields inherited from class org.jnetpcap.nio.JMemory

JNETPCAP_LIBRARY_NAME, MAX_DIRECT_MEMORY_DEFAULT, POINTER

Constructor Summary

JHeader()
Calls on the header defintion's static annotated \@HeaderLength method to get header's length.

JHeader(int id, JField[] fields, java.lang.String name)
Constructs a header and initializes its static fields.

JHeader(int id, JField[] fields, java.lang.String name, java.lang.String nicname)
Constructs a header and initializes its static fields.

JHeader(int id, java.lang.String name)
Constructs a header.

JHeader(int id, java.lang.String name, java.lang.String nicname)
Constructs a header.

JHeader(JHeader.State state, JField[] fields, java.lang.String name, java.lang.String nicname)
Constructs a header and initializes its static fields.

JHeader(JProtocol protocol)
Constructs a header for a CORE protocol.

Method Summary

void	decode() Method that gets called everytime a header is successfully peered with new buffer and/or state structure.
protected void	decodeHeader() Allows a header to decode its complex fields.
AnnotatedHeader	getAnnotatedHeader() Retrieves the cached annotation of the header definition file.
java.lang.String	getDescription() Retrives the description property for this header as defined in the source definition.
JField[]	getFields() Retrieves the fields at runtime, that this header has so that they may be used by a formatter.
byte[]	getGap() Reads the contents of the protocol's 'record' gap property as a byte array.
int	getGapLength() Reads the length of the gap between the header and payload: *
int	getGapOffset() Gets the offset into the packet, not the header, where the gap starts.
byte[]	getHeader() Convenience method that retrieves the contents of the header as a byte are
int	getHeaderLength() Length of the header in bytes.
int	getHeaderOffset() Gets the offset in bytes into the packet, of the start of the header.
int	getId() Gets the numerical ID of this protocol header at runtime as assigned by the JRegistry.
int	getIndex() Gets the header's index into the packet state structure.
int	getLength() Length of this header within the buffer.
java.lang.String	getName() Gets the comprehensive name for this header.
int	getNextHeaderId() Gets the next header id.
int	getNextHeaderOffset() Gets the next header offset.
java.lang.String	getNicname() Gets the short name for this header.
int	getOffset() Offset into the packet buffer.
JPacket	getPacket() Gets the packet that this header is associated with
JHeader	getParent() If this is a sub-header of another header, gets the reference to the parent header.
byte[]	getPayload() Retrieves the playload data portion of the packet right after the current header.
int	getPayloadLength() Gets the length in bytes of the payload that follows the header and the gap.
int	getPayloadOffset() Gets the offset of the payload into the packet buffer.
byte[]	getPostfix() Gets the contents of the postfix as a byte array.
int	getPostfixLength() Gets the length of the postfix.
int	getPostfixOffset() Gets the offset in bytes into the packet buffer of the start of the postfix, even if not set or zero length.
byte[]	getPrefix() Gets the contents of the prefix in a byte array.
int	getPrefixLength() The length in bytes of the prefix within the packet buffer.
int	getPrefixOffset() The offset in bytes into the packet buffer where the prefix starts, even if prefix is not set or zero in length.
int	getPreviousHeaderId() Gets the previous header id.
int	getPreviousHeaderOffset() Gets the previous header offset.
JHeader.State	getState() Gets the reference to the current header's native state structure
JHeader[]	getSubHeaders() Gets an array of currently defined sub headers.
boolean	hasDescription() Checks if description header property has been set that provides a short description of this header.
boolean	hasGap() Checks if gap has been set.
boolean	hasNextHeader() Checks for next header.
boolean	hasPayload() Checks if payload has been set.
boolean	hasPostfix() Checks if postfix has been set.
boolean	hasPrefix() Checks if prefix has been set.
boolean	hasPreviousHeader() Checks for previous header.
boolean	hasSubHeaders() Checks if header has any sub-headers.
boolean	isFragmented() Checks if this entire header "record" which includes prefix, header, gap, payload and post is fragmented.
boolean	isGapTruncated() Checks if gap has been truncated due to truncation at the time of the capture.
boolean	isHeaderTruncated() Checks if header has been truncated due to truncation at the time of the capture.
boolean	isPayloadTruncated() Checks if payload has been truncated due to truncation at the time of the capture.
boolean	isPostfixTruncated() Checks if postifx has been truncated due to truncation at the time of the capture.
boolean	isPrefixTruncated() Checks if prefix has been truncated due to truncation at the time of the capture.
int	peer(JBuffer buffer, int offset) Peers this state object with the buffer at specified offset.
int	peer(JHeader header) Peers, associates a native packet buffer and scanner structure with this header.
JBuffer	peerPayloadTo(JBuffer buffer) Peers, without copy, the user supplied buffer with payload data portion of the packet right after the current header.
void	setPacket(JPacket packet) Sets the packet that this header should be associated with
void	setSubHeaders(JHeader[] headers) Allows sub-headers to be set.
static int	sizeof() Gets the size of the native header_t structure on this particular platform.
java.lang.String	toString() Gets a string with summary information about the header.
byte[]	transferPayloadTo(byte[] buffer) Copies the payload data portion of the packet right after the current header to user supplied buffer.
java.nio.ByteBuffer	transferPayloadTo(java.nio.ByteBuffer buffer) Copies into the user supplied buffer, the payload data portion of the packet right after the current header.
JBuffer	transferPayloadTo(JBuffer buffer) Copies into the user supplied buffer, the payload data portion of the packet right after the current header.
protected void	validateHeader() Allows a header to validate its values.

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

BYTE

public static final int BYTE

A constant that defines how many bits there are in a byte. This constant is used in unit conversion from bytes to bits and visa-versa. To convert from bytes to bit you multiple your number of bytes by the BYTE constant. To convert from bits to bytes, you divide the number of bits by the BYTE constant.

See Also:

Constant Field Values

EMPTY_HEADER_ARRAY

protected static final JHeader[] EMPTY_HEADER_ARRAY

The Constant EMPTY_HEADER_ARRAY.

annotatedHeader

protected AnnotatedHeader annotatedHeader

The annotated header.

isSubHeader

protected boolean isSubHeader

The is sub header.

packet

protected JPacket packet

A reference to the packet that this header is part of.

state

protected final JHeader.State state

Reference to header's native state structure.

Constructor Detail

JHeader

public JHeader()

Calls on the header defintion's static annotated \@HeaderLength method to get header's length. The method is given a buffer and offset as the start of the header. The method invoked must be defined in the header definition otherwise an exception will be thrown.

JHeader

public JHeader(int id,
               JField[] fields,
               java.lang.String name)

Constructs a header and initializes its static fields.

Parameters:

id - numerical ID of the protocol

fields - fields usd by the formatter to reformat the packet for output

name - comprehensive name of the protocol

JHeader

public JHeader(int id,
               JField[] fields,
               java.lang.String name,
               java.lang.String nicname)

Constructs a header and initializes its static fields.

Parameters:

id - numerical ID of the protocol

fields - fields usd by the formatter to reformat the packet for output

name - comprehensive name of the protocol

nicname - a short name for the protocol

JHeader

public JHeader(int id,
               java.lang.String name)

Constructs a header.

Parameters:

id - numerical ID of the protocol

name - comprehensive name of the protocol

JHeader

public JHeader(int id,
               java.lang.String name,
               java.lang.String nicname)

Constructs a header.

Parameters:

id - numerical ID of the protocol

name - comprehensive name of the protocol

nicname - a short name for the protocol

JHeader

public JHeader(JProtocol protocol)

Constructs a header for a CORE protocol.

Parameters:

protocol - the CORE protocol constant

JHeader

public JHeader(JHeader.State state,
               JField[] fields,
               java.lang.String name,
               java.lang.String nicname)

Constructs a header and initializes its static fields.

Parameters:

state - the default header state object being referenced

fields - fields usd by the formatter to reformat the packet for output

name - comprehensive name of the protocol

nicname - a short name for the protocol

Method Detail

sizeof

public static int sizeof()

Gets the size of the native header_t structure on this particular platform.

Returns:

length in bytes

decode

public final void decode()

Method that gets called everytime a header is successfully peered with new buffer and/or state structure. This method in JHeader is empty and is expected to be overriden by subclasses of JHeader that require special processing of the header such as decoding its structure at runtime when the header object is bound to new state.

decodeHeader

protected void decodeHeader()

Allows a header to decode its complex fields.

getAnnotatedHeader

public AnnotatedHeader getAnnotatedHeader()

Retrieves the cached annotation of the header definition file. The AT-Header annotation is a class that contains all of the annotation parameters that were set in the definition file or its defaults.

Returns:

annotation class for the source header definition

getDescription

public java.lang.String getDescription()

Retrives the description property for this header as defined in the source definition.

Returns:

a short description of this protocol and the header

getFields

public JField[] getFields()

Retrieves the fields at runtime, that this header has so that they may be used by a formatter.

Returns:

an array of fields that this header is made up of, as determined at runtime

getGap

public byte[] getGap()

Reads the contents of the protocol's 'record' gap property as a byte array.

 +------------------=====--------------------+
 | prefix | header | GAP | payload | postfix |
 +------------------=====--------------------+
 

Returns:

contents of the gap or zero length byte[] if not set

getGapLength

public int getGapLength()

Reads the length of the gap between the header and payload: *

 +------------------=====--------------------+
 | prefix | header | GAP | payload | postfix |
 +------------------=====--------------------+
 

.

Returns:

length of the gap in bytes or 0 if not set

getGapOffset

public int getGapOffset()

Gets the offset into the packet, not the header, where the gap starts. Even if the gap is zero length or not set, the offset is still calculated and will always be the first byte past the header.

 +------------------=====--------------------+
 | prefix | header | GAP | payload | postfix |
 +------------------=====--------------------+
 

Returns:

offset in bytes into the packet's buffer

getHeader

public byte[] getHeader()

Convenience method that retrieves the contents of the header as a byte are

 +---------========--------------------------+
 | prefix | HEADER | gap | payload | postfix |
 +---------========--------------------------+
 

.

Returns:

the contents of the header

getHeaderLength

public int getHeaderLength()

Length of the header in bytes. *

 +---------========--------------------------+
 | prefix | HEADER | gap | payload | postfix |
 +---------========--------------------------+
 

Returns:

the length in bytes fo the header

getHeaderOffset

public int getHeaderOffset()

Gets the offset in bytes into the packet, of the start of the header. *

 +---------========--------------------------+
 | prefix | HEADER | gap | payload | postfix |
 +---------========--------------------------+
 

Returns:

offset in bytes into the packet buffer

getId

public final int getId()

Gets the numerical ID of this protocol header at runtime as assigned by the JRegistry.

Returns:

unique numerical ID of this header

getLength

public int getLength()

Length of this header within the buffer.

Returns:

length in bytes

getName

public final java.lang.String getName()

Gets the comprehensive name for this header.

Returns:

the name full name of this header

getNicname

public final java.lang.String getNicname()

Gets the short name for this header.

Returns:

the nicname for this header

getOffset

public int getOffset()

Offset into the packet buffer.

Returns:

offset into the buffer in bytes

getPacket

public final JPacket getPacket()

Gets the packet that this header is associated with

Returns:

parent packet

getParent

public JHeader getParent()

If this is a sub-header of another header, gets the reference to the parent header.

Returns:

the parent header if sub-header, otherwise returns a reference to itself

getPayload

public byte[] getPayload()

Retrieves the playload data portion of the packet right after the current header.

 +------------------------=========----------+
 | prefix | header | gap | PAYLOAD | postfix |
 +------------------------=========----------+
 

Specified by:

getPayload in interface JPayloadAccessor

Returns:

newly allocated byte array containing copy of the contents of the header's payload from the packet.

getPayloadLength

public int getPayloadLength()

Gets the length in bytes of the payload that follows the header and the gap. The length reflects the actual data that resides in the captured packet, not neccessarily all of the data that was originaly transmited if the packet has been trucated during capture.

 +------------------------=========----------+
 | prefix | header | gap | PAYLOAD | postfix |
 +------------------------=========----------+
 

Returns:

length of the payload in bytes

getPayloadOffset

public int getPayloadOffset()

Gets the offset of the payload into the packet buffer.

 +------------------------=========----------+
 | prefix | header | gap | PAYLOAD | postfix |
 +------------------------=========----------+
 

Returns:

the start of the payload within the packet buffer

getPostfix

public byte[] getPostfix()

Gets the contents of the postfix as a byte array.

Returns:

the contents of the postfix as a byte array or zero length byte array if no postfix set

getPostfixLength

public int getPostfixLength()

Gets the length of the postfix.

 +----------------------------------=========+
 | prefix | header | gap | payload | POSTFIX |
 +----------------------------------=========+
 

Returns:

the length of the postfix in bytes or zero if not set

getPostfixOffset

public int getPostfixOffset()

Gets the offset in bytes into the packet buffer of the start of the postfix, even if not set or zero length.

Returns:

the offeset into the packet buffer in bytes

getPrefix

public byte[] getPrefix()

Gets the contents of the prefix in a byte array.

 +========-----------------------------------+
 | PREFIX | header | gap | payload | postfix |
 +========-----------------------------------+
 

Returns:

the contents of the prefix or zero length byte array if not set

getPrefixLength

public int getPrefixLength()

The length in bytes of the prefix within the packet buffer. Zero if not set.

Returns:

the length in bytes within the packet buffer

getPrefixOffset

public int getPrefixOffset()

The offset in bytes into the packet buffer where the prefix starts, even if prefix is not set or zero in length.

Returns:

offset in bytes into the packet buffer

getState

public JHeader.State getState()

Gets the reference to the current header's native state structure

Returns:

current state of the header

getSubHeaders

public JHeader[] getSubHeaders()

Gets an array of currently defined sub headers.

Returns:

array of sub headers

hasDescription

public boolean hasDescription()

Checks if description header property has been set that provides a short description of this header.

Returns:

true if header description has been set in Header annotation

hasGap

public boolean hasGap()

Checks if gap has been set.

Returns:

true if set, otherwise false

hasPayload

public boolean hasPayload()

Checks if payload has been set.

Returns:

true if set, otherwise false

hasPostfix

public boolean hasPostfix()

Checks if postfix has been set.

Returns:

true if set, otherwise false

hasPrefix

public boolean hasPrefix()

Checks if prefix has been set.

Returns:

true if set, otherwise false

hasSubHeaders

public boolean hasSubHeaders()

Checks if header has any sub-headers.

Returns:

true if set, otherwise false

isGapTruncated

public boolean isGapTruncated()

Checks if gap has been truncated due to truncation at the time of the capture. If the gap was never set (initially set to zero) and then completely removed because of packet truncation, this method will return false, since the gap never existed in the first place.

Returns:

true if truncated, otherwise false

isHeaderTruncated

public boolean isHeaderTruncated()

Checks if header has been truncated due to truncation at the time of the capture.

Returns:

true if truncated, otherwise false

isPayloadTruncated

public boolean isPayloadTruncated()

Checks if payload has been truncated due to truncation at the time of the capture. If the payload was never set (initially set to zero) and then completely removed because of packet truncation, this method will return false, since the payload never existed in the first place.

Returns:

true if truncated, otherwise false

isPostfixTruncated

public boolean isPostfixTruncated()

Checks if postifx has been truncated due to truncation at the time of the capture. If the postifx was never set (initially set to zero) and then completely removed because of packet truncation, this method will return false, since the postfix never existed in the first place.

Returns:

true if truncated, otherwise false

isPrefixTruncated

public boolean isPrefixTruncated()

Checks if prefix has been truncated due to truncation at the time of the capture. If the prefix was never set (initially set to zero) and then completely removed because of packet truncation, this method will return false, since the gap never existed in the first place.

Returns:

true if truncated, otherwise false

peer

public int peer(JBuffer buffer,
                int offset)

Peers this state object with the buffer at specified offset.

Parameters:

buffer - buffer to peer to

offset - offset into the buffer

Returns:

number of bytes that were peered, not copied

peer

public int peer(JHeader header)

Peers, associates a native packet buffer and scanner structure with this header. This header is unchanged while the header being passed in is rereferenced to point at this headers buffer and state structure.

Parameters:

header - the header to peer with this header

Returns:

number of bytes total that were peered with the supplied header

peerPayloadTo

public JBuffer peerPayloadTo(JBuffer buffer)

Peers, without copy, the user supplied buffer with payload data portion of the packet right after the current header.

Specified by:

peerPayloadTo in interface JPayloadAccessor

Parameters:

buffer - buffer to peer the data with

Returns:

the same buffer that was passed in

setPacket

public final void setPacket(JPacket packet)

Sets the packet that this header should be associated with

Parameters:

packet - packet to associate with this header

setSubHeaders

public void setSubHeaders(JHeader[] headers)

Allows sub-headers to be set.

Parameters:

headers - array of sub header

toString

public java.lang.String toString()

Gets a string with summary information about the header.

Overrides:

toString in class java.lang.Object

Returns:

String with summary of the header

transferPayloadTo

public byte[] transferPayloadTo(byte[] buffer)

Copies the payload data portion of the packet right after the current header to user supplied buffer.

Specified by:

transferPayloadTo in interface JPayloadAccessor

Parameters:

buffer - buffer where the data will be written to

Returns:

the same buffer that was passed in

transferPayloadTo

public java.nio.ByteBuffer transferPayloadTo(java.nio.ByteBuffer buffer)

Copies into the user supplied buffer, the payload data portion of the packet right after the current header. The copy will start at the current ByteBuffer position property.

Specified by:

transferPayloadTo in interface JPayloadAccessor

Parameters:

buffer - buffer to copy the data to

Returns:

the same buffer that was passed in

transferPayloadTo

public JBuffer transferPayloadTo(JBuffer buffer)

Copies into the user supplied buffer, the payload data portion of the packet right after the current header.

Specified by:

transferPayloadTo in interface JPayloadAccessor

Parameters:

buffer - buffer to copy the data to

Returns:

the same buffer that was passed in

getIndex

public int getIndex()

Gets the header's index into the packet state structure. Various pieces of information in packet state structure can be looked up using this index.

Returns:

header index in Packet.State structure

validateHeader

protected void validateHeader()

Allows a header to validate its values.

hasNextHeader

public boolean hasNextHeader()

Checks for next header.

Returns:

true, if successful

getNextHeaderId

public int getNextHeaderId()

Gets the next header id.

Returns:

the next header id

getNextHeaderOffset

public int getNextHeaderOffset()

Gets the next header offset.

Returns:

the next header offset

hasPreviousHeader

public boolean hasPreviousHeader()

Checks for previous header.

Returns:

true, if successful

getPreviousHeaderId

public int getPreviousHeaderId()

Gets the previous header id.

Returns:

the previous header id

getPreviousHeaderOffset

public int getPreviousHeaderOffset()

Gets the previous header offset.

Returns:

the previous header offset

isFragmented

public boolean isFragmented()

Checks if this entire header "record" which includes prefix, header, gap, payload and post is fragmented. The fragmentation may have happened in encapsulating protocol such as Ip. This property may be inherited from encapsulating headers.

Returns:

true if this header is believed to be a fragment, otherwise false