com.voytechs.jnetstream.codec
Interface Packet

All Known Implementing Classes:
PacketImpl

public interface Packet

A decoded representation of a network packet.

A Packet is made up of headers and properties. You can find out how many headers a packet has using the getHeaderCount() method. Then you can retrieve each header using the getHeader(int) call which returns a Header object. You can also specifically retrieve a named header using the getHeader(String) call where string is a name of the header such as "IPv4" or "Ethernet". These header names are defined in the config/protocols.npl file also you can look them up by looking at the decoded packets. The summary line on top of full decode will contain the true name for each header.

There are a number of properties assigned to each packet some are permanent and other are local to just individual packet. Use the getProperty(String) method call to retrieve properties. There is a public property String defined for each supported property. Look at their individual descriptions for full details on each property. Local properties are specific to each packet whereas same instance of a permanent property is shared by each packet. getProperty(String) method call returns a Primitive object which abstracts the actual data object and allows NPL and decoder to do a number of operations. Use the getValue() method call to retrive actual value of the Primitive returned.

Here is an example that extracts a SUMMARY property from the packet. The SUMMARY property summarizes the last header within the packet. This last header is usually the most important one of interest.

 .... skipped try statement
 Decoder decoder = new Decoder("myCaptureFile.pcap");
 Packet packet = decoder.nextPacket();

 if (packet != null) {
   System.out.println(
     "Packet summary = " + packet.getProperty(Packet.SUMMARY).getValue());
 }
 ... skipped catch statements
 
Example:

 import com.voytechs.jnetstream.codec.Packet;
 import com.voytechs.jnetstream.codec.Header;
 import com.voytechs.jnetstream.codec.Field;
 import com.voytechs.jnetstream.codec.Decoder;
 import com.voytechs.jnetstream.io.StreamFormatException;
 import com.voytechs.jnetstream.npl.SyntaxError;
 import java.io.IOException;

 public class Tutorial1 {
     public static void main(String[] args) {
       try {
           Decoder decoder = new Decoder("myCaptureFile.pcap");
           Packet packet = null;
           Header header = null;
           Field field = null;
           
           while ( (packet = decoder.nextPacket()) != null) {
               header = packet.getHeader("IPv4");
           
               if (header != null) {
                   field = header.getField("hlen");
           
                   System.out.println("hlen=" + field.toString());
               } else {
                   System.out.println(packet.getProperty(Packet.SUMMARY));
               } 
               
               // OR you can use shorthand API
               
               Integer hlen = (Integer) packet.getValue("IPv4", "hlen");
               System.out.println("hlen=" + hlen);
           
           }
       } catch (StreamFormatException t) {
       } catch (IOException ie) {
       } catch (SyntaxError se) {
       }
     }
 }
 

Author:
Mark Bednarczyk

Field Summary
static java.lang.String CAPTURE_DEVICE_ARCH
          Property contains architecture description of the device the packet was captured on.
static java.lang.String CAPTURE_DEVICE_FILENAME
          Property contains the filename of the capture file that the packet was read from or interface name if packet was captured with in live capture mode.
static java.lang.String CAPTURE_DEVICE_IP
          Property contains IP address of the devide where the packet was captured on or capture file was read from.
static java.lang.String CAPTURE_DEVICE_OS
          Property contains Operating System description of the device the packet was captured on.
static java.lang.String CAPTURE_TIMESTAMP
          Property contains timestamp of when the packet was captured.
static java.lang.String DADDR
          Property contains main destination address of the host that receive this packet.
static java.lang.String FIRST_HEADER
          Property contains the name of the first header within the packet.
static java.lang.String FLOWKEY
          Property contains a flowkey that has been built up during packet decoding.
static java.lang.String INDEX
          Property contains the index as recorded by the decoder.
static java.lang.String PACKET_END
          Property contains byte offset within the stream or file where the last byte of the packet is positioned.
static java.lang.String PACKET_LENGTH
          Property contains original packet length as seen on the wire.
static java.lang.String PACKET_REMAINING
          Property contains number of packet bytes still remaining in the stream starting from the current position.
static java.lang.String PACKET_SNAPLEN
          Property contains actual packet length as stored in the file.
static java.lang.String PACKET_START
          Property contains byte offset within the stream or file where the first byte of the packet began.
static java.lang.String POST_NOTE
           
static java.lang.String PRE_NOTE
          Property contains a note that has been built up during packet decoding.
static java.lang.String SADDR
          Property contains main source address of the host that sent this packet.
static java.lang.String SUMMARY
           Property contains a summary string of the last protocol within the packet.
 
Method Summary
 Header getDataHeader()
           Returns the data header in the packet.
 Header getHeader(int index)
           Returns the indexed header from the packet.
 Header getHeader(java.lang.String name)
           Returns the named header from the packet.
 Header getHeader(java.lang.String name, int index)
           Finds all instances of the named header if more than one, and returns the index header from the headers found.
 int getHeaderCount()
          Returns the number of headers in this packet.
 Header getLastHeader()
           Returns the last header in the packet excluding the Data header if its the last header.
 Primitive getProperty(java.lang.String name)
          Retrieves a property with the given name.
 java.lang.Object getValue(int headerIndex, java.lang.String fieldName)
          Conveniece method to retrieve a value of a field or property directly from a header.
 java.lang.Object getValue(java.lang.String propertyName)
          Conveniece method to retrieve a value of a property directly from the Packet.
 java.lang.Object getValue(java.lang.String headerName, java.lang.String fieldName)
          Conveniece method to retrieve a value of a field or property directly from a header.
 

Field Detail

PACKET_LENGTH

public static final java.lang.String PACKET_LENGTH
Property contains original packet length as seen on the wire. This is a LOCAL Integer property. The actual included number of data bytes for the packet is stored in the PACKET_SNAPLEN property.

See Also:
Constant Field Values

PACKET_SNAPLEN

public static final java.lang.String PACKET_SNAPLEN
Property contains actual packet length as stored in the file. This is a LOCAL Integer property. The actual length could be different from the original packet length if only portion of the packet was captured.

See Also:
Constant Field Values

CAPTURE_TIMESTAMP

public static final java.lang.String CAPTURE_TIMESTAMP
Property contains timestamp of when the packet was captured. This is LOCAL java.sql.Timestamp property. This timestamp is in Java java.sql.Timestamp format, which contains millis and nanos for timestamp. This value is as accurate as the underlying capture mechanism or file format supports.

See Also:
Constant Field Values

CAPTURE_DEVICE_IP

public static final java.lang.String CAPTURE_DEVICE_IP
Property contains IP address of the devide where the packet was captured on or capture file was read from. This is a LOCAL jnetstream.primitive.address.IPAddress property. These days the JNetStream library assumes its an IP address (v4 or v6), although it would be trivial to set this property as jnetstream.primtiive.address.Address which is more generic, but would not have the predefined IP formatting suitable for most situations.

See Also:
Constant Field Values

CAPTURE_DEVICE_FILENAME

public static final java.lang.String CAPTURE_DEVICE_FILENAME
Property contains the filename of the capture file that the packet was read from or interface name if packet was captured with in live capture mode. This is a PERMENENT String property. Either a filename or interface name. If it is unknown to the Decoder either of these because it was passed as native java.io.InputStream then the name is set to something like: "inputstream: ...". Author does not guarrantee that the format of the string will be consistent between releases.

See Also:
Constant Field Values

CAPTURE_DEVICE_ARCH

public static final java.lang.String CAPTURE_DEVICE_ARCH
Property contains architecture description of the device the packet was captured on. This is a PERMANENT String property. This property is as its returned by System.getProperty("arch") property.

See Also:
Constant Field Values

CAPTURE_DEVICE_OS

public static final java.lang.String CAPTURE_DEVICE_OS
Property contains Operating System description of the device the packet was captured on. This is a PERMANENT String property. This property is as its returned by System.getProperty("os") property.

See Also:
Constant Field Values

FIRST_HEADER

public static final java.lang.String FIRST_HEADER
Property contains the name of the first header within the packet. This is a LOCAL String property. First header contains the name of the first header that was defined within the capture file's header. This may not neccessarily correspond to the header name returned by the Packet method call getHeader(0).getName(). The reason for this Decoder starts decoding the packet using the capture file suggested first header, but then through its normal test and Assertion tests may determine that the first header is actually something else. I.e. capture file may say its a Ethernet header but decoder may decide that its an IEEE802.3 header instead.

See Also:
Constant Field Values

PACKET_START

public static final java.lang.String PACKET_START
Property contains byte offset within the stream or file where the first byte of the packet began. This is a LOCAL Long property. This property is stored as a java.lang.long because streams can be larger then 2GB that a singed integer can support. This is mainly used for debugging purposes, there are easier and less costly methods for advancing from packet to packet within a capture file, if that is what the user wishes to do using the io.PacketInputStream methods.

See Also:
Constant Field Values

PACKET_END

public static final java.lang.String PACKET_END
Property contains byte offset within the stream or file where the last byte of the packet is positioned. This is a LOCAL Long property. This property is stored as a java.lang.long because streams can be larger then 2GB that a singed integer can support. This is mainly used for debugging purposes, there are easier and less costly methods for advancing from packet to packet within a capture file, if that is what the user wishes to do using the io.PacketInputStream methods.

See Also:
Constant Field Values

PACKET_REMAINING

public static final java.lang.String PACKET_REMAINING
Property contains number of packet bytes still remaining in the stream starting from the current position. This is a LOCAL property and when packets are fully decoded should contain 0, but not neccessarily depending how deep into the packet the decoder was able to decode the packet.

This property is mainly used for debugging.

See Also:
Constant Field Values

SADDR

public static final java.lang.String SADDR
Property contains main source address of the host that sent this packet. This is a LOCAL jnetstream.primitive.address.Address property. The address is of the last major protocol that contains somekind of an address. This could be IPAddress, MACAddress or simply Address for other protocols such as Appletalk or IPX.

See Also:
Constant Field Values

DADDR

public static final java.lang.String DADDR
Property contains main destination address of the host that receive this packet. This is a LOCAL jnetstream.primitive.address.Address property. The address is of the last major protocol that contains somekind of an address. This could be IPAddress, MACAddress or simply Address for other protocols such as Appletalk or IPX.

See Also:
Constant Field Values

INDEX

public static final java.lang.String INDEX
Property contains the index as recorded by the decoder. It is in sequence that the packet was read from the Stream. Property type is integer.

See Also:
Constant Field Values

SUMMARY

public static final java.lang.String SUMMARY

Property contains a summary string of the last protocol within the packet. This is a LOCAL String property. The summary line is tailored and customized by the Header itself during the decoding of the last header. It will contain summary information that each particular deems as important that should be included on the summary line.

The SUMMARY property combined with SADDR, DADDR and CAPTURE_TIMESTAMP properties can be used to produce 1 line summary output that contains all the information you would see in other sniffer applications such as tcpdump or tethereal.

See Also:
Constant Field Values

FLOWKEY

public static final java.lang.String FLOWKEY
Property contains a flowkey that has been built up during packet decoding. Its a 2 dimensional Primitive table (Primitive[][]).

See Also:
Constant Field Values

PRE_NOTE

public static final java.lang.String PRE_NOTE
Property contains a note that has been built up during packet decoding. Its a 2 dimensional Primitive table (Primitive[][]).

See Also:
Constant Field Values

POST_NOTE

public static final java.lang.String POST_NOTE
See Also:
Constant Field Values
Method Detail

getHeader

public Header getHeader(java.lang.String name)

Returns the named header from the packet. If the header with the given name is not found, null is returned.

Packet is made up of a number of headers that the decoder was able to decode from the capture file or stream. To find out how many headers use the getHeaderCount() method call.

Returns:
The header if found, otherwise nul..

getHeader

public Header getHeader(java.lang.String name,
                        int index)

Finds all instances of the named header if more than one, and returns the index header from the headers found. Some headers can appear more than once in a packet such as IPv4 header in an ICMP desitination unreachable packet. The IPv4 header is first found after the DataLink OSI layer typically Ethernet and then a second time after the ICMP header. You can use the index to specify which header you would like of the 2 in our example. This is zero (0) based index so index of 0 would refer to the main packet IPv4 header and index of 1 would refer to the second IPv4 header after the ICMP header in our example. null is returned if the header is not found by name or the index is out of range.

Packet is made up of a number of headers that the decoder was able to decode from the capture file or stream. To find out how many headers use the getHeaderCount() method call.

Returns:
The header if found, otherwise nul..

getHeader

public Header getHeader(int index)

Returns the indexed header from the packet. If index is out of range then null is returned.

Packet is made up of a number of headers that the decoder was able to decode from the capture file or stream. To find out how many headers use the getHeaderCount() method call.

Returns:
The header found at this header index within the packet. Header are added and stored within the packet in the order they were decoded. null is returned if index is out of range.

getLastHeader

public Header getLastHeader()

Returns the last header in the packet excluding the Data header if its the last header. Use getDataHeader() to retrieve the data header.

Packet is made up of a number of headers that the decoder was able to decode from the capture file or stream. To find out how many headers use the getHeaderCount() method call.

Returns:
The header found at this header index within the packet. Header are added and stored within the packet in the order they were decoded. null is returned if index is out of range.
Since:
JNetStream 0.2.2

getDataHeader

public Header getDataHeader()

Returns the data header in the packet. If present.

Packet is made up of a number of headers that the decoder was able to decode from the capture file or stream. To find out how many headers use the getHeaderCount() method call. Usually there is a catch all header that captures the remainder of the data in the packet. This header is called the Data header. If all available data is retrieved then there could be an empty Data header or none at all.

Returns:
The data header found within the packet.
Since:
JNetStream 0.2.2

getHeaderCount

public int getHeaderCount()
Returns the number of headers in this packet.

Packet is made up of a number of headers that the decoder was able to decode from the capture file or stream.

Returns:
Number of headers found in this packet.

getValue

public java.lang.Object getValue(java.lang.String headerName,
                                 java.lang.String fieldName)
Conveniece method to retrieve a value of a field or property directly from a header. First the header name is looked up and then the field or property within that header.

Parameters:
headerName - Header name to lookup the field.
fieldName - Field name to retrieve the value from.
Returns:
Opaque value of the field. Null if header or the field is not found within the packet.
Since:
JNetStream 0.2.2

getValue

public java.lang.Object getValue(int headerIndex,
                                 java.lang.String fieldName)
Conveniece method to retrieve a value of a field or property directly from a header. First the header is looked up by indexand then the field within that header.

Parameters:
headerIndex - Header index to lookup the field.
fieldName - Field name to retrieve the value from.
Returns:
Opaque value of the field. Null if header or the field is not found within the packet.
Since:
JNetStream 0.2.2

getValue

public java.lang.Object getValue(java.lang.String propertyName)
Conveniece method to retrieve a value of a property directly from the Packet.

Returns:
Opaque value of the property. Null if property is not found within the packet.
Since:
JNetStream 0.2.2

getProperty

public Primitive getProperty(java.lang.String name)
Retrieves a property with the given name. The names for properties are defined as public constants in this class. See the Field section for public properties and their descriptions.

Properties are stored a jnetstream.primitive.Primitive objects. Primitive interface encapsulates the underlying data object and provides interfaces and operations with capture streams.

To retrieve the value object of the primitve use the Primitive::getValue() method call. See properties description for exact data type for each property. The getValue() call returns opaque Object which needs to be typecast into appropriate data object or simply call its toString() method call if that's all is required.

Returns:
Primitive object that contains the value for the given property. Use the getProperty(String).getValue() method call chain to extract actual value of the property.