SourceForge Jpcap

net.sourceforge.jpcap.capture
Interface PacketCaptureCapable

All Superinterfaces:
Closeable
All Known Implementing Classes:
JWinPcap, PacketCapture

public interface PacketCaptureCapable
extends Closeable

This is the packet capture interface. It is implemented by both the packet capture system PacketCapture and the simulator PacketCaptureSimulator.

The interface has two major components:

Version:
$Revision: 1.1 $
Author:
Patrick Charles and Jonas Lehmann, Esmond Pitt
Last modified by:
$Author: esmondpitt $
Last modified at:
$Date: 2008/08/21 02:57:57 $

Field Summary
static int DEFAULT_SNAPLEN
          Snapshot length.
static int DEFAULT_TIMEOUT
          Default capture timeout in milliseconds.
 
Method Summary
 void addPacketListener(PacketListener listener)
          Register a packet object listener with this capture system.
 void addRawPacketListener(RawPacketListener listener)
          Register a raw packet listener with this capture system.
 void capture(int count)
          Capture packets.
 void close()
           Close cleans up after a packet capture session.
 void endCapture()
          Stop capturing packets.
 String findDevice()
          Deprecated. Please use PacketCapture.lookupCaptureDevices().
 String getLinkLayerDescription()
          Return a description of the link layer for the current capture device, corresponding to getLinkLayerType().
 int getLinkLayerType()
          Fetch the link layer type for the current capture device.
 int getNetmask(String device)
          Deprecated. Please use PacketCapture.lookupCaptureDevices().
 int getNetwork(String device)
          Deprecated. Please use PacketCapture.lookupCaptureDevices().
 int getSnapshotLength()
          Get the snapshot length specified when this network device was opened.
 CaptureStatistics getStatistics()
          Fetch statistics on captured packets.
 void open(String device, boolean promiscuous)
          Open a network device for data capture.
 void open(String device, int snaplen, boolean promiscuous, int timeout)
          Open a network device for data capture.
 void openOffline(String fileName)
          Open a tcpdump-formatted savefile for reading.
 void removePacketListener(PacketListener listener)
          Deregister a packet object listener from this capture system.
 void removeRawPacketListener(RawPacketListener listener)
          Deregister a raw packet listener from this capture system.
 void setFilter(String filterExpression, boolean optimize)
          Create, compile and activate a filter from a filter expression.
 

Field Detail

DEFAULT_SNAPLEN

static final 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?

See Also:
Constant Field Values

DEFAULT_TIMEOUT

static final int DEFAULT_TIMEOUT
Default capture timeout in milliseconds.

See Also:
Constant Field Values
Method Detail

open

void open(String device,
          boolean promiscuous)
          throws CaptureDeviceOpenException
Open a network device for data capture.

This call is equivalent to


        open(device, DEFAULT_SNAPLEN, promiscuous, DEFAULT_TIMEOUT);

Parameters:
device - the name of the network device.
promiscuous - whether or not the device should be put into 'promiscuous' mode: true => capture all packets; false => capture packets only to and from this system.
Throws:
CaptureDeviceOpenException
See Also:
open(String, int, boolean, int)

open

void open(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 put into 'promiscuous' mode: true => capture all packets; false => capture packets only to and from this system.
timeout - the packet capture timeout in milliseconds. Defines the maximum amount of time that capture will wait for another packet, if the capture device's buffer isn't full, before notifying the application of the packets already captured. A value of zero means return each packet immediately: this mode is rather inefficient. Timeouts of 500ms-2 seconds are reasonable, or longer if the application can wait longer.
Throws:
CaptureDeviceOpenException - can't open the specified device

openOffline

void openOffline(String fileName)
                 throws CaptureFileOpenException
Open a tcpdump-formatted savefile for reading.

Parameters:
fileName - the name of the savefile.
Throws:
CaptureFileOpenException - can't open the specified file

setFilter

void setFilter(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.
optimize - whether or not the resulting bpf code is optimized internally by libpcap.
Throws:
InvalidFilterException - invalid filter specification

capture

void capture(int count)
             throws CapturePacketException
Capture packets.

Parameters:
count - the number of packets to capture. If count is -1, this method will run forever unless endCapture() is called or an exception is thrown.
Throws:
CapturePacketException - Capture problem

endCapture

void endCapture()
Stop capturing packets. Any current capture(int) call will return. Does not guarantee that no further packets will be processed after it is called; one more packet might be processed.


getStatistics

CaptureStatistics getStatistics()
Fetch statistics on captured packets. This method should not be called unless capture(int) was previously called, with capture occurring from a network device.

Returns:
packet capture statistics, or null if capture was from a file.

close

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

To signal an end to a capture session before the specified number of packets has been received, first call endCapture().

Specified by:
close in interface Closeable

findDevice

String findDevice()
                  throws CaptureDeviceNotFoundException
Deprecated. Please use PacketCapture.lookupCaptureDevices().

Detect a network device suitable for packet capture.

This API should be static; does not work reliably; and will be removed in a future release.

Returns:
the network device name.
Throws:
CaptureDeviceNotFoundException - No capture devices found

getNetwork

int getNetwork(String device)
               throws CaptureConfigurationException
Deprecated. Please use PacketCapture.lookupCaptureDevices().

Fetch the network address for the specified device.

This API:

For these reasons it will be removed in a future release.

Parameters:
device - the name of the network device.
Returns:
the network address
Throws:
CaptureConfigurationException - Capture device not found

getNetmask

int getNetmask(String device)
               throws CaptureConfigurationException
Deprecated. Please use PacketCapture.lookupCaptureDevices().

Fetch the network mask for the specified device.

This API:

For these reasons it will be removed in a future release.

Parameters:
device - the name of the network device.
Returns:
the netmask address
Throws:
CaptureConfigurationException - Capture device not found

getLinkLayerDescription

String getLinkLayerDescription()
                               throws CaptureConfigurationException
Return a description of the link layer for the current capture device, corresponding to getLinkLayerType().

Returns:
link layer description.
Throws:
CaptureConfigurationException - Unknown link layer type.
Since:
2.0.0

getLinkLayerType

int getLinkLayerType()
                     throws CaptureConfigurationException
Fetch the link layer type for the current capture device.

Returns:
the link layer type code.
Throws:
CaptureConfigurationException - Capture configuration lookup problem

getSnapshotLength

int getSnapshotLength()
Get the snapshot length specified when this network device was opened.

Returns:
the packet snapshot length, or -1 if a capture device is not open.

addRawPacketListener

void addRawPacketListener(RawPacketListener listener)
Register a raw packet listener with this capture system. This method is safe to call during a packet-arrival callback, e.g. to remove the current listener, but won't take effect until the next packet in that case.

Parameters:
listener - the raw packet listener to add to the notification list.
Throws:
IllegalArgumentException - 'listener' is null

removeRawPacketListener

void removeRawPacketListener(RawPacketListener listener)
Deregister a raw packet listener from this capture system. This method is safe to call during a packet-arrival callback, e.g. to remove the current listener, but won't take effect until the next packet in that case.

Parameters:
listener - the raw packet listener to remove from the notification list.
Throws:
IllegalArgumentException - 'listener' not registered

addPacketListener

void addPacketListener(PacketListener listener)
Register a packet object listener with this capture system. This method is safe to call during a packet-arrival callback, e.g. to remove the current listener, but won't take effect until the next packet in that case.

Parameters:
listener - the packet listener to add to the notification list.
Throws:
IllegalArgumentException - 'listener' is null

removePacketListener

void removePacketListener(PacketListener listener)
Deregister a packet object listener from this capture system. This method is safe to call during a packet-arrival callback, e.g. to remove the current listener, but won't take effect until the next packet in that case.

Parameters:
listener - the packet listener to remove from the notification list.
Throws:
IllegalArgumentException - 'listener' not registered

Copyright © Patrick Charles & Jonas Lehmann, 2001; Esmond Pitt, 2008.