net.sourceforge.jpcap.capture
Class PacketCapture

java.lang.Object
  |
  +--net.sourceforge.jpcap.capture.PacketDispatcher
        |
        +--net.sourceforge.jpcap.capture.PacketCapture
All Implemented Interfaces:
PacketHandler

public class PacketCapture
extends PacketDispatcher
implements PacketHandler

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 packet listener and subscribe to 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.


Field Summary
static int DEFAULT_SNAPLEN
          Snapshot length.
static int DEFAULT_TIMEOUT
          Default capture timeout in milliseconds.
protected static java.lang.String LIB_PCAP_WRAPPER
          Name of the java-enabled wrapper around libpcap.
 
Constructor Summary
PacketCapture()
           
 
Method Summary
 void capture(int count)
          Capture packets.
 void close()
          Close the capture device.
static java.lang.String findDevice()
          Detect a network device suitable for packet capture.
static int getLinkLayerType()
          Fetch the link layer type for the specified device.
static int getNetmask(java.lang.String device)
          Fetch the network mask for the specified device.
static int getNetwork(java.lang.String device)
          Fetch the network number for the specified device.
 CaptureStatistics getStatistics()
          Fetch statistics on captured packets.
 void handlePacket(int length, int caplen, int seconds, int useconds, byte[] data)
          Handle packets arriving from the libpcap interface.
 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 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.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
 

Field Detail

LIB_PCAP_WRAPPER

protected static java.lang.String LIB_PCAP_WRAPPER
Name of the java-enabled wrapper around libpcap.

DEFAULT_SNAPLEN

public static int DEFAULT_SNAPLEN
Snapshot length. Maximum number of bytes per packet to capture. For IPv4, 96 bytes guarantees that at least the headers of most packet types and protocols will get captured. For IPv6, 68 is a better value?

DEFAULT_TIMEOUT

public static int DEFAULT_TIMEOUT
Default capture timeout in milliseconds.
Constructor Detail

PacketCapture

public PacketCapture()
Method Detail

open

public void open(java.lang.String device,
                 boolean promiscuous)
          throws CaptureDeviceOpenException
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.
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.
Returns:
a string describing the network device. if no device can be found, null is returned.

open

public void open(java.lang.String device,
                 int snaplen,
                 boolean promiscuous,
                 int timeout)
          throws CaptureDeviceOpenException
Open a network device for data capture.
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.
Returns:
a string describing the network device. if no device can be found, null is returned.

setFilter

public void setFilter(java.lang.String filterExpression,
                      boolean optimize)
               throws InvalidFilterException
Create, compile and activate a filter from a filter expression.
Parameters:
filterExpression - the filter expression. For example, the expression "host techno" would filter only packets sent or arriving at the host named techno.

capture

public void capture(int count)
             throws CapturePacketException
Capture packets.
Parameters:
count - the number of packets to capture. If count is negative, capture will block forever, unless an exception is thrown.

getStatistics

public CaptureStatistics getStatistics()
Fetch statistics on captured packets. This method should not be called unless capture() was previously called.
Returns:
packet capture statistics.

close

public void close()
Close the capture device.

findDevice

public static java.lang.String findDevice()
                                   throws CaptureDeviceNotFoundException
Detect a network device suitable for packet capture.
Returns:
a string describing the network device. if no device can be found, null is returned.

getNetwork

public static int getNetwork(java.lang.String device)
                      throws CaptureConfigurationException
Fetch the network number for the specified device.
Parameters:
device - the name of the network device.
Returns:
the network address

getNetmask

public static int getNetmask(java.lang.String device)
                      throws CaptureConfigurationException
Fetch the network mask for the specified device.
Parameters:
device - the name of the network device.
Returns:
the netmask address

getLinkLayerType

public static int getLinkLayerType()
                            throws CaptureConfigurationException
Fetch the link layer type for the specified device.
Returns:
the link layer type code.

handlePacket

public void handlePacket(int length,
                         int caplen,
                         int seconds,
                         int useconds,
                         byte[] data)
Handle packets arriving from the libpcap interface.

Arriving packets are dispatched to registered packet listeners. If caplen is smaller than length, then the packet was truncated because the amount of data on the wire exceeded the snapshot length specified when open() was called.

Specified by:
handlePacket in interface PacketHandler
Parameters:
length - the length of the packet off of the wire.
caplen - the number of bytes actually captured.
seconds - the seconds component of the timestamp.
useconds - the microseconds component of the timestamp.
data - the contents of the captured packet.