org.jnetstream.capture
Interface CaptureDevice

All Superinterfaces:

com.slytechs.utils.namespace.Named

All Known Subinterfaces:

LiveCaptureDevice

public interface CaptureDevice
extends com.slytechs.utils.namespace.Named

Describes the capture device that captured the packet. Individual captured packets maintain a reference to a capture device that captured them. The CaptureDevice differes from java.net.NetworkInterface as it is essentially a snapshot of the current or past state of the interface. The CaptureDevices created are usually not cached by are new instances that contain certain state at the time they were initialized.

For example a capture device was created and initialized at 8:00am. 5 minutes later the network interface configuration was altered and another IP addresses alias added to the interface. When the device was opened at 8:10am a new CaptureDevice created and initialized and now it there are two instances of CaptureDevice associated with that same interface both containing slightly different IP addresses for that physical network interface. Another common way for a new alternate CaptureDevice to be created when a new filter is applied in a middle of a already open capture. At the time the filter is applied a new CaptureDevice is created with new filter state and from then on any packets captured and returned from LiveCapture sessions will reference the new CaptureDevice with the new filter state, while the old packets (packets already returned prior to the filter being applied) will maintain a reference to the original CaptureDevice object. "Nap" (see http://jnetpcap.sf.net?q=napspec) file format stores all of this information in the capture file. Other formats such as PCAP and SNOOP can not.

It is important to first check the capabilities of the capture device using the #getCapabilities method before accessing or setting new values. The capabilities are of the source of the capture, that is if the packet is comming from a live network interface, the capabilities are of the network interface that did the capturing and the operating system on which the capture took place. If the source of the captured packet is a file, then the information supplied by this interface is file type specific. File formats such as Snoop and Pcap have limited capabilities to store information about capturing devices, while Nap file format can store all of this information.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

static class

CaptureDevice.TimestampResolution Specified the maximum supported timestamp resolution of the capture device.

Nested classes/interfaces inherited from interface com.slytechs.utils.namespace.Named

com.slytechs.utils.namespace.Named.Util

Method Summary

java.util.List<com.slytechs.utils.net.Address>	getAddresses() Gets a list of addresses that are/were set on the interface.
java.lang.String	getDescription() Retruns device description if one is available.
java.lang.String	getDisplayName() Gets a more human readable name for the interface if one is available.
Protocol	getLinkType() Data encapsulation used by this capture device
java.lang.String	getName() Gets the name as returned by the operating system of the network interface this CaptureDevice describes.
ProtocolEntry	getProtocol() Returns a refrence to a specific protocol of the DLT for this capture device.
long	getRawLinkType() Returns the raw link type as an 32-bit signed integer as returned by the underlying implemenation of the interface or library interfacing with the device.
CaptureDevice.TimestampResolution	getTimestampResolution() Returns the resolution that the capturing device is capable of.
long	getTimezone() Gets the timezone as retrieved from the operating system at the time of the packet capture.

Method Detail

getDisplayName

java.lang.String getDisplayName()

Gets a more human readable name for the interface if one is available. If no display name is set, this method returns null.

Returns:

human readable display name for the interface or null if one is not available

getDescription

java.lang.String getDescription()

Retruns device description if one is available. If no description is available, it returns a formatted string based on the display name or the name.

Returns:

a detailed description of the device or null if description is not available

getAddresses

java.util.List<com.slytechs.utils.net.Address> getAddresses()

Gets a list of addresses that are/were set on the interface.

Returns:

list of addresses set on the interface

getName

java.lang.String getName()

Gets the name as returned by the operating system of the network interface this CaptureDevice describes. If the capture device was created based on information found in capture files, the name is typically not available and will be returned as null.

Specified by:

getName in interface com.slytechs.utils.namespace.Named

Returns:

OS assigned name of the network interface or null if name was not available

getLinkType

Protocol getLinkType()

Data encapsulation used by this capture device

Returns:

data encapsulation enum constant

getProtocol

ProtocolEntry getProtocol()

Returns a refrence to a specific protocol of the DLT for this capture device.

Returns:

getRawLinkType

long getRawLinkType()

Returns the raw link type as an 32-bit signed integer as returned by the underlying implemenation of the interface or library interfacing with the device.

Returns:

32-bit signed integer containing the raw value

getTimestampResolution

CaptureDevice.TimestampResolution getTimestampResolution()

Returns the resolution that the capturing device is capable of. This is usually hardware dependent.

Returns:

an enum constant describing the clock resolution of the capturing device

getTimezone

long getTimezone()

Gets the timezone as retrieved from the operating system at the time of the packet capture. This allows the capture timestamp as reported by the CapturePacket to be put in the correct timezone perspective.

Returns:

timezone of the device where the packet was captured on