jnetpcap.capture
Interface CaptureInterface

All Known Subinterfaces:

MutableCaptureInterface

public interface CaptureInterface

Describes the capture device that captured the packet. Individual captured packets maintain a reference to a capture device that captured them. The CaptureInterface 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 CaptureInterface created and initialized and now it there are two instances of CaptureInterface associated with that same interface both containing slightly different IP addresses for that physical network interface. Another common way for a new alternate CaptureInterface 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 CaptureInterface is created with new filter state and from then on any packets captured and returned from LiveCapture sessions will reference the new CaptureInterface 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 CaptureInterface 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	CaptureInterface.Capability Enum structure which defines the capabilities of the capturing device such as a network interface and the kernel of this particular OS.
static class	CaptureInterface.TimestampResolution

Method Summary

java.util.Set<CaptureInterface.Capability>	getCapabilities() Returns the capabilities of the capturing device.
DataEncapsulation	getDataEncapsulation() Data encapsulation used by this capture device
java.lang.String	getDisplayName() Gets a more human readable name for the interface if one is available.
Filter	getFilter() Gets the currently assigned filter to this capture device.
java.util.List<java.net.InetAddress>	getIpAddresses() Gets a list of ip addresses that are/were set on the interface.
MutableCaptureInterface	getMutableCaptureInterface() Gets the mutable version of this CaptureInterface interface.
java.lang.String	getName() Gets the name as returned by the operating system of the network interface this CaptureInterface describes.
java.lang.String	getOSArchitecture() Gets the OS architecture as recorded using system property os.architecture
java.lang.String	getOSName() Get the name of the operating system the capture device is on.
java.lang.String	getOSVersion() Get the version of the operating system the capture device is on.
CaptureInterface.TimestampResolution	getTimestampResolution() Returns the resolution that the capturing device is capable of.
int	getTimezone() Gets the timezone as retrieved from the operating system at the time of the packet capture.
boolean	isMutable() Tells if this instance of CaptureInterface is mutable.

Method Detail

getCapabilities

java.util.Set<CaptureInterface.Capability> getCapabilities()

Returns the capabilities of the capturing device. The actual capabilities that a physical capture device had may vary from what is reported by the capability set as some information about the capture device may have been lost after the information was stored in a capture file fromat that does not support storage of such information. Typically though the most important information is kept.

Returns:

capabilities this current instance of this capture device has

getDataEncapsulation

DataEncapsulation getDataEncapsulation()

Data encapsulation used by this capture device

Returns:

data encapsulation enum constant

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

getFilter

Filter getFilter()

Gets the currently assigned filter to this capture device. Null if none exists. The currently assigned filter may have been assigned either by #setFilter method or at the time the capture device was opened using one of CaptureFactory.openLive(), CaptureFactory.openLive() or CaptureFactory.Factory.openLive() methods.

Returns:

currently assigned filter or null if none assigned

getIpAddresses

java.util.List<java.net.InetAddress> getIpAddresses()

Gets a list of ip addresses that are/were set on the interface. The list is mutable and you can add new ip addresses as needed.

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 CaptureInterface describes.

Returns:

OS assigned name of the network interface. This method never retruns null.

getOSArchitecture

java.lang.String getOSArchitecture()

Gets the OS architecture as recorded using system property os.architecture

Returns:

OS architecture of the OS that the capture device resides on

getOSName

java.lang.String getOSName()

Get the name of the operating system the capture device is on.

Returns:

name of the operating system

getOSVersion

java.lang.String getOSVersion()

Get the version of the operating system the capture device is on.

Returns:

version of the operating system

getTimestampResolution

CaptureInterface.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

int 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

isMutable

boolean isMutable()

Tells if this instance of CaptureInterface is mutable. CaptureInterfaces when initialy created are mutable. The moment they are used in a live capture the CaptureInterface is made immutable and its config frozen, essentially maintaining a snapshot of the underlying network interface configuration.

Returns:

true if it is mutable otherwise false

getMutableCaptureInterface

MutableCaptureInterface getMutableCaptureInterface()

Gets the mutable version of this CaptureInterface interface. You must use the method isMutable() prior to calling this method. If this CaptureInterface is not mutable this method will throw IllegalStateException.

Returns:

mutable version of the CaptureInterface interface

Throws:

java.lang.IllegalStateException - if you access this method when this instance is immutable