net.sourceforge.jpcap.capture
Class PacketCapture

java.lang.Object
  net.sourceforge.jpcap.capture.PacketDispatcher
      net.sourceforge.jpcap.capture.PacketCaptureBase
          net.sourceforge.jpcap.capture.PacketCapture

All Implemented Interfaces:

PacketCaptureCapable, PacketDispatchCapable, net.sourceforge.jpcap.capture.PacketHandler

Direct Known Subclasses:

SyncPacketCapture

public class PacketCapture

extends PacketCaptureBase

implements PacketCaptureCapable

This class is the core of packet capture in jpcap. It provides a high-level interface for capturing network packets by encapsulating libpcap.

If you want to capture network packets, implement PacketListener and register with an instance of this class. When packets arrive, the object will call you back via packetArrived().

Examples can be found in net.sourceforge.jpcap.tutorial.

For more documentation on this class's methods, see PacketCaptureCapable; Javadoc is 'inherited' from this interface.

PacketCapture utilizes libpcap's pcap_loop(). See SyncPacketCapture for pcap_dispatch()-type behavior.

Field Summary

protected static java.lang.String

LIB_PCAP_WRAPPER Name of the java-enabled wrapper around libpcap.

Fields inherited from class net.sourceforge.jpcap.capture.PacketCaptureBase

droppedCount, linkType, receivedCount

Fields inherited from interface net.sourceforge.jpcap.capture.PacketCaptureCapable

DEFAULT_SNAPLEN, DEFAULT_TIMEOUT

Constructor Summary

PacketCapture()
Create a new packet capture instance.

Method Summary

void	capture(int count) Capture packets.
void	capture(int instance, int count)
void	close() Close the capture device.
void	close(int instance) Close cleans up after a packet capture session.
java.lang.String	findDevice() Detect a network device suitable for packet capture.
int	getLinkLayerType() Fetch the link layer type for the specified device.
int	getLinkLayerType(int instance)
int	getNetmask(java.lang.String device) Fetch the network mask for the specified device.
int	getNetwork(java.lang.String device) Fetch the network number for the specified device.
int	getSnapshotLength() Get the snapshot length given that network device is open.
int	getSnapshotLength(int instance)
CaptureStatistics	getStatistics() Fetch statistics on captured packets.
static java.lang.String[]	lookupDevices() Get Interface List
void	open(int instance, java.lang.String device, int snaplen, boolean promiscuous, int timeout)
void	open(java.lang.String device, boolean promiscuous) Open a network device for data capture.
void	open(java.lang.String device, int snaplen, boolean promiscuous, int timeout) Open a network device for data capture.
void	openOffline(int instance, java.lang.String fileName)
void	openOffline(java.lang.String fileName) Open a tcpdump-formatted savefile.
void	setFilter(int instance, java.lang.String filterExpression, boolean optimize)
void	setFilter(java.lang.String filterExpression, boolean optimize) Create, compile and activate a filter from a filter expression.

Methods inherited from class net.sourceforge.jpcap.capture.PacketCaptureBase

handlePacket

Methods inherited from class net.sourceforge.jpcap.capture.PacketDispatcher

addPacketListener, addRawPacketListener, dispatchPacket, dispatchRawPacket, removePacketListener, removeRawPacketListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.sourceforge.jpcap.capture.PacketCaptureCapable

addPacketListener, addRawPacketListener, removePacketListener, removeRawPacketListener

Field Detail

LIB_PCAP_WRAPPER

protected static java.lang.String LIB_PCAP_WRAPPER

Name of the java-enabled wrapper around libpcap.

Constructor Detail

PacketCapture

public PacketCapture()

Create a new packet capture instance.

Method Detail

open

public void open(java.lang.String device,
                 boolean promiscuous)
          throws CaptureDeviceOpenException

Description copied from interface: PacketCaptureCapable

Open a network device for data capture. Throws an exception if the device name specified is invalid. Uses default values for the capture timeout and snaplen.

Specified by:

open in interface PacketCaptureCapable

Parameters:

device - the name of the network device. Examples of valid network devices on linux are 'eth0' and 'ppp0'.

promiscuous - whether or not the device should be opened in promiscuous mode.

Throws:

CaptureDeviceOpenException

open

public void open(java.lang.String device,
                 int snaplen,
                 boolean promiscuous,
                 int timeout)
          throws CaptureDeviceOpenException

Description copied from interface: PacketCaptureCapable

Open a network device for data capture.

Specified by:

open in interface PacketCaptureCapable

Parameters:

device - the name of the network device. Examples of valid network devices on linux are 'eth0' and 'ppp0'.

snaplen - the 'snapshot' length. Defines the maximum number of bytes to save from each captured packet.

promiscuous - whether or not the device should be opened in promiscuous mode.

timeout - the packet capture timeout in milliseconds.

Throws:

CaptureDeviceOpenException

open

public void open(int instance,
                 java.lang.String device,
                 int snaplen,
                 boolean promiscuous,
                 int timeout)
          throws CaptureDeviceOpenException

Throws:

CaptureDeviceOpenException

openOffline

public void openOffline(java.lang.String fileName)
                 throws CaptureFileOpenException

Description copied from interface: PacketCaptureCapable

Open a tcpdump-formatted savefile.

Specified by:

openOffline in interface PacketCaptureCapable

Parameters:

fileName - the name of the savefile.

Throws:

CaptureFileOpenException

openOffline

public void openOffline(int instance,
                        java.lang.String fileName)
                 throws CaptureFileOpenException

Throws:

CaptureFileOpenException

setFilter

public void setFilter(java.lang.String filterExpression,
                      boolean optimize)
               throws InvalidFilterException

Description copied from interface: PacketCaptureCapable

Create, compile and activate a filter from a filter expression.

Specified by:

setFilter in interface PacketCaptureCapable

Parameters:

filterExpression - the filter expression. For example, the expression "host techno" would filter only packets sent or arriving at the host named techno.

optimize - whether or not the resulting bpf code is optimized internally by libpcap.

Throws:

InvalidFilterException

setFilter

public void setFilter(int instance,
                      java.lang.String filterExpression,
                      boolean optimize)
               throws InvalidFilterException

Throws:

InvalidFilterException

capture

public void capture(int count)
             throws CapturePacketException

Description copied from interface: PacketCaptureCapable

Capture packets.

Specified by:

capture in interface PacketCaptureCapable

Parameters:

count - the number of packets to capture. If count is negative, capture will block forever, unless an exception is thrown.

Throws:

CapturePacketException

capture

public void capture(int instance,
                    int count)
             throws CapturePacketException

Throws:

CapturePacketException

getStatistics

public CaptureStatistics getStatistics()

Description copied from interface: PacketCaptureCapable

Fetch statistics on captured packets. This method should not be called unless capture() was previously called.

Specified by:

getStatistics in interface PacketCaptureCapable

Returns:

packet capture statistics.

close

public void close(int instance)

Close cleans up after a packet capture session. It does _not_ terminate a packet capture. capture() does not return control until 'count' packets are captured.

If you are looking for a way to signal an end to a capture session before a set number of packets are received, check out the class SyncPacketCapture.

close

public void close()

Description copied from interface: PacketCaptureCapable

Close the capture device.

Specified by:

close in interface PacketCaptureCapable

lookupDevices

public static java.lang.String[] lookupDevices()
                                        throws CaptureDeviceLookupException

Get Interface List

Returns:

Network device interface names.

Throws:

CaptureDeviceLookupException

findDevice

public java.lang.String findDevice()
                            throws CaptureDeviceNotFoundException

Description copied from interface: PacketCaptureCapable

Detect a network device suitable for packet capture.

Specified by:

findDevice in interface PacketCaptureCapable

Returns:

a string describing the network device. if no device can be found, null is returned.

Throws:

CaptureDeviceNotFoundException

getNetwork

public int getNetwork(java.lang.String device)
               throws CaptureConfigurationException

Description copied from interface: PacketCaptureCapable

Fetch the network number for the specified device.

Specified by:

getNetwork in interface PacketCaptureCapable

Parameters:

device - the name of the network device.

Returns:

the network address

Throws:

CaptureConfigurationException

getNetmask

public int getNetmask(java.lang.String device)
               throws CaptureConfigurationException

Description copied from interface: PacketCaptureCapable

Fetch the network mask for the specified device.

Specified by:

getNetmask in interface PacketCaptureCapable

Parameters:

device - the name of the network device.

Returns:

the netmask address

Throws:

CaptureConfigurationException

getLinkLayerType

public int getLinkLayerType()
                     throws CaptureConfigurationException

Description copied from interface: PacketCaptureCapable

Fetch the link layer type for the specified device.

Specified by:

getLinkLayerType in interface PacketCaptureCapable

Returns:

the link layer type code.

Throws:

CaptureConfigurationException

getLinkLayerType

public int getLinkLayerType(int instance)
                     throws CaptureConfigurationException

Throws:

CaptureConfigurationException

getSnapshotLength

public int getSnapshotLength()

Description copied from interface: PacketCaptureCapable

Get the snapshot length given that network device is open.

Specified by:

getSnapshotLength in interface PacketCaptureCapable

Returns:

the packet snapshot length.

getSnapshotLength

public int getSnapshotLength(int instance)