jnetpcap.capture
Interface CapturePacket

All Known Subinterfaces:

DeserializedPacket, FilePacket, LivePacket

public interface CapturePacket

A captured network packet. The actual packet data may have been captured live from a network interface or device or came from a file, streamed . That is this interface does not neccessarily represent a 1-to-1 relationship with any record contained within the capture file.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Method Summary

java.nio.ByteBuffer	allocatePacketBuffer(int length) Allocates a packet buffer that is implementation optimized.
CaptureInterface	getCaptureInterface() Returns information about the device that captured this packet.
int	getIncludedPacketLength() Gets the number of octets that were included as packet data after the packet was captured.
int	getOriginalPacketLength() Gets the number of octets of the actual packet as it was originally seen at the time of the capture or on the wire.
java.nio.ByteBuffer	getPacketBuffer() Gets a buffer that contains the packet's data.
java.sql.Timestamp	getTimestamp() Convenience method which converts the getTimestampSeconds() and getTimestampNanos() to a Timestamp object.
long	getTimestampNanos() Gets the timestamp as recorded at the time of the packet capture in fraction of a second, in nanoseconds.
long	getTimestampSeconds() Gets the timestamp as recorded at the time of the packet capture in number of seconds since 1.1.1970.
void	setCaptureInterface(CaptureInterface device) Sets the device that captured this packet.
void	setOriginalPacketLength(int length) Sets the original length of the packet in octets.
void	setPacketBuffer(java.nio.ByteBuffer buffer) Set the packets data buffer.
void	setTimestamp(long seconds, long nanos) Sets the timestamp when the packet was captured by a CaptureInterface, i.e.
void	setTimestamp(java.sql.Timestamp time) Convenience method which sets the capture timestamp using a Timestamp object.

Method Detail

getCaptureInterface

CaptureInterface getCaptureInterface()

Returns information about the device that captured this packet. This is typically some network interface on this or some other system. The structure also has DataEncapsulation information about the first data header within the packet.

Returns:

device that captured this packet

setCaptureInterface

void setCaptureInterface(CaptureInterface device)

Sets the device that captured this packet.

Parameters:

device - device to set as the device that captured this packet

getPacketBuffer

java.nio.ByteBuffer getPacketBuffer()

Gets a buffer that contains the packet's data. The buffer does not contain any header information if the packet was read from a file. Only the raw captured data is included. The capacity of the buffer will be the size of underlying data storage which may be more then length of included data as returned by getIncludedPacketLength() method. This is because if the packet came from a packet record stored in a file, the record's data length may have been bigger then the actual data. This extra buffer size is unused and can be used to expand that packet. Lastly the position and limit of the buffer will be set to the start and length of the actual packet data, respectively.

Returns:

buffer containing this packet data

setPacketBuffer

void setPacketBuffer(java.nio.ByteBuffer buffer)

Set the packets data buffer. This allows the user to supply and external buffer. Once the packet has been commited to a file the buffer may be replaced by another buffer. Therefore it is always neccessary to get the actual reference to the current packet buffer using the getPacketBuffer() method after each commit or write to a storage device such as using the MutableFileCapture.flush() method.

Parameters:

buffer - buffer to set as this packets data buffer

allocatePacketBuffer

java.nio.ByteBuffer allocatePacketBuffer(int length)

Allocates a packet buffer that is implementation optimized. This may be more efficient then user allocated buffer as buffers are cached and reused; also the buffer may be part of much larger native memory allocation that is used for storing packet buffer information.

Parameters:

length - length of the buffer to allocate

getIncludedPacketLength

int getIncludedPacketLength()

Gets the number of octets that were included as packet data after the packet was captured. This number may be less then the actual length of the packet as it was seen on the wire. This is sometimes also called the "snaplength" or "slice" of a packet. Truncating packet data in such a way allows greater storage efficiency when only the beginning of a packet data is needed. The beginning of a packet data contains the important protocol headers which can be used to determine the packet type and other important information. This is typically enough of accounting type application or monitoring applications.

Returns:

number of octets that were captured and stored in the packet data buffer

getOriginalPacketLength

int getOriginalPacketLength()

Gets the number of octets of the actual packet as it was originally seen at the time of the capture or on the wire. This number may not neccessarily correspond with getIncludedPacketLength() method since sometimes packets are "sliced", "truncated", "snapped" etc to preserve storage space.

Returns:

number of octets of the original packet before any truncation of its data buffer

setOriginalPacketLength

void setOriginalPacketLength(int length)

Sets the original length of the packet in octets. This should correspond to the actual size of the packet as seen on the wire (traversing a network). The number should not include capture or file headers that were generated at the time of the capture or when the packet data was read from a file.

Parameters:

length - length in octets of the packet data buffer

getTimestampSeconds

long getTimestampSeconds()

Gets the timestamp as recorded at the time of the packet capture in number of seconds since 1.1.1970.

Returns:

number of seconds

getTimestampNanos

long getTimestampNanos()

Gets the timestamp as recorded at the time of the packet capture in fraction of a second, in nanoseconds. The valid range is from 0 to 999,999,999 nanoseconds. The value is always returned in nanoseconds even when the capturing device, such as a network interface, is not capable of timestamping at nanosecond resolution. In case the capture device has microsecond resolution, the valid value of this counter would be from 0 to 999,999,000. To determine the timestamp real resolution of the capturing device use the method getCaptureInterface() and then CaptureInterface.getTimestampResolution() which will return an enum constant which describes if the resulution is in nanoseconds or microseconds. In either case this information should only be required in rare circuimstances as the timestamp is always converted and reported in nanoseconds, no matter what the resolution actually is.

Returns:

fraction of a second in nanosecond increments in valid range of 0 to 999,999,999

getTimestamp

java.sql.Timestamp getTimestamp()

Convenience method which converts the getTimestampSeconds() and getTimestampNanos() to a Timestamp object. The timestamp object is cached.

Returns:

Timestamp object of the capture timestamp

setTimestamp

void setTimestamp(java.sql.Timestamp time)

Convenience method which sets the capture timestamp using a Timestamp object. The capture timestamp is recorded in whatever underlying medium is.

Parameters:

time - timestamp for when the packet was captured off of a live network

setTimestamp

void setTimestamp(long seconds,
                  long nanos)
                  throws java.lang.IllegalArgumentException

Sets the timestamp when the packet was captured by a CaptureInterface, i.e. a network interface. CaptureInterface.getTimestampResolution() is not checked and all values in the range of 0 to 999,999,999 are allowed even if the clock's resolution is only in microseconds. It is upto the user to convert the timestamp into nanoseconds when the actual resolution is in microseconds by multiplying the microsecond value by one thousand (nanoseconds = microseconds * 1000).

Parameters:

seconds - number of seconds since 1.1.1970

nanos - fraction of a second in range of 0 to 999,999,999

Throws:

java.lang.IllegalArgumentException - if nanos is less then 0 or greater then 999,999,999 nanoseconds