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:

Closeable, PacketCaptureCapable, PacketDispatchCapable

Direct Known Subclasses:

JWinPcap

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.

To capture network packets, implement PacketListener and register with an instance of this class. When packets arrive, your packetArrived() callback method will be invoked. Examples can be found in net.sourceforge.jpcap.tutorial. This utilizes libpcap's pcap_loop(), pcap_dispatch(), and pcap_breakloop() methods.

In addition to packet capture via callbacks, the class supports:

• A simpler 'no-callbacks' packet-reading interface via getInputStream() (which corresponds to pcap_next_ex())
• packet sending via getOutputStream(),
• packet dumping from the network or a tcpdump-formatted savefile to a tcpdump-formatted savefile, via getOutputStream(File file)
• high-efficiency packet filtering from the network or a tcpdump-formatted savefile to a tcpdump-formatted savefile, via captureTo(int, PacketOutputStream).

So you can use this class:

1. to capture and filter packets
2. to save packets to savefiles
3. to filter a live capture directly to an output savefile, or
4. to filter an input savefile directly to an output savefile.

There are several parameters that control packet capture:

timeout

This is specified when you open the capture device, which defaults to 1 second. The timeout allows the kernel layer to buffer up several packets for transfer to the application at the same time, which is much more efficient than transferring one at a time (fewer context switches). You have to trade that off against your application's requirement for timeliness.

PacketCapture.LoopMode

This is set by setLoopMode(), which defaults to Loop.

'minimum kernel copy' value

On Winpcap platforms, this is as documented for JWinPcap.getMinimumKernelCopy() and setMinimumKernelCopy(); on non-Winpcap platforms it defaults to an unknown but probably similar value.

capture method

The capture method you call can be one of capture(), captureTo(), captureNext(), or PacketInputStream.readPacket().

count

The count supplied to capture().

The operation of these is explained below.

1. capture() in Loop mode loops doing the following until the specified count is reached:
   1. buffer packets until the 'minimum kernel copy' value is reached, or the timeout expires, (whichever occurs first), then
   2. call your callback with the buffered packets one by one.
2. capture() in Dispatch mode does the same steps, then resumes looping, but, on any loop iteration, if the timeout expires without any packets being captured, it returns.

   Neither of these throws SocketTimeoutException. If a timeout occurs, Loop mode just keeps running until the count expires; Dispatch mode returns immediately.

   You can see how many packets were captured via getStatistics().

3. captureTo() behaves the same as capture(), i.e. it is subject to the LoopMode, MinimumKernelCopy, and timeout settings.
4. captureNext() captures and returns one packet, without a callback, but it is still subject to the timeout specified when opening. If the timeout expires it throws SocketTimeoutException.
5. PacketInputStream.readPacket() is identical to captureNext() under the hood.

Note: Version 2.0.0 binary incompatibility: All the native methods in this class have been renamed, are now private, and in almost all cases now have different calling sequences. The old public native methods of this class that took instance arguments:

• were made public unintentionally
• were unsafe, unchecked, and liable to cause JVM crashes
• are now unimplementable, because the concept of 'instance numbers' has been banished, and therefore
• have been removed.

Any code that calls these methods it must be changed.

Version:

$Revision: 1.1 $

Author:

Patrick Charles and Jonas Lehmann, Esmond Pitt

See Also:

PacketCaptureCapable, PacketInputStream, PacketOutputStream, PacketListener

Last modified by:

$Author: esmondpitt $

Last modified at:

$Date: 2008/08/21 02:57:57 $

Nested Class Summary

static class	PacketCapture.Direction Capture Direction enumeration.
static class	PacketCapture.LoopMode LoopModes determine how the capture(int) and captureTo(int, net.sourceforge.jpcap.capture.PacketOutputStream) methods behave in the presence of timeouts.

Field Summary

static String	LIB_PCAP_WRAPPER Name of the java-enabled wrapper around libpcap.
static int	MAX_SNAPLEN Maximum size of a capture buffer, snaplen, Ethernet packet, etc.

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

linkType

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

DEFAULT_SNAPLEN, DEFAULT_TIMEOUT

Constructor Summary

PacketCapture()
Create a new packet capture instance.

PacketCapture(CaptureDevice device, boolean promiscuous)
Construct a new instance and open the specified device for capture.

PacketCapture(CaptureDevice device, int snaplen, boolean promiscuous, int timeout)
Construct a new instance and open the specified device for capture.

PacketCapture(File file)
Construct a new instance and open the specified file for capture.

Method Summary

void	capture(int count) Capture packets.
Packet	captureNext() Return the next packet captured.
int	captureTo(int count, PacketOutputStream out) Capture packets and dump them to the network or a tcpdump-formatted savefile.
void	close() Close cleans up after a packet capture session.
CompiledFilter	compileFilter(String filter, boolean optimize) Compile a filter expression for the current capture device.
void	configureBlocking(boolean blocking) Configure the blocking mode.
void	endCapture() Stop capturing packets.
protected void	finalize()
static CaptureDevice	findCaptureDevice() Find a suitable CaptureDevice for live capture.
String	findDevice() Deprecated. Please use findCaptureDevice().
CaptureDevice	getDevice() Return the current capture device.
PacketInputStream	getInputStream() Return a PacketInputStream for reading packets from the network.
static String	getLibVersion() Return a string giving information about the version of the libpcap library being used; note that it contains more information than just a version number.
String	getLinkLayerDescription() Return a description of the link layer for the current capture device, corresponding to PacketCaptureCapable.getLinkLayerType().
String	getLinkLayerDescription(int linkType) Return the link layer description for the specified type.
String	getLinkLayerName() Return the link layer name, e.g.
String	getLinkLayerName(int linkType) Return the link layer name for the specified linkType.
int	getLinkLayerType() Fetch the link layer type for the current capture device.
int[]	getLinkLayerTypes() Get the available link layer types for the current capture device.
PacketCapture.LoopMode	getLoopMode() Get the current loop mode.
int	getNetmask(String name) Deprecated. Please use lookupCaptureDevices().
int	getNetwork(String name) Deprecated. Please use lookupCaptureDevices().
PacketOutputStream	getOutputStream() Return a PacketOutputStream that sends packets to the network device opened by this PacketCapture.
PacketOutputStream	getOutputStream(File file) Return a PacketOutputStream that dumps packets to a tcpdump-formatted savefile.
int	getSnapshotLength() Get the snapshot length specified when this network device was opened.
CaptureStatistics	getStatistics() Fetch statistics on captured packets.
boolean	isBlocking() Return true if the capture device is in blocking mode, false for non-blocking mode.
boolean	isClosed() Return true if the captor is closed or a device or capture file hasn't been opened yet.
static CaptureDevice[]	lookupCaptureDevices() Get the interface list as an array of CaptureDevice[].
static String[]	lookupDevices() Deprecated. Please use lookupCaptureDevices().
void	open(CaptureDevice device, boolean promiscuous) Open a network device for data capture.
void	open(CaptureDevice device, int snaplen, boolean promiscuous, int timeout) Open a network device for data capture.
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	setDirection(PacketCapture.Direction direction) Set the direction of packet capture.
void	setFilter(CompiledFilter filter) Set the filter from a precompiled filter.
void	setFilter(String filterExpression, boolean optimize) Create, compile and activate a filter from a filter expression.
void	setLinkLayerType(int linkType) Set the current link layer type.
void	setLoopMode(PacketCapture.LoopMode loopMode) Set the current loop mode.

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

handlePacket

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

addPacketListener, addRawPacketListener, removePacketListener, removeRawPacketListener

Methods inherited from class java.lang.Object

clone, equals, 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

public static final String LIB_PCAP_WRAPPER

Name of the java-enabled wrapper around libpcap.

See Also:

Constant Field Values

MAX_SNAPLEN

public static final int MAX_SNAPLEN

Maximum size of a capture buffer, snaplen, Ethernet packet, etc.

See Also:

Constant Field Values

Constructor Detail

PacketCapture

public PacketCapture()

Create a new packet capture instance. Allocates an 'instance number' from zero to INSTANCE_MAX. Only INSTANCE_MAX instances of this class can exist concurrently. This is tied to declarations in the JNI code.

PacketCapture

public PacketCapture(CaptureDevice device,
                     boolean promiscuous)
              throws CaptureDeviceOpenException

Construct a new instance and open the specified device for capture. This is equivalent to:

        PacketCapture packetCapture = new PacketCapture();
        packetCapture.open(device, DEFAULT_SNAPLEN, promiscuous, DEFAULT_TIMEOUT);

Parameters:

device - CaptureDevice to capture from.

promiscuous - whether or not the device should be put into 'promiscuous' mode.

Throws:

CaptureDeviceOpenException - can't open the specified device

Since:

2.0.0

PacketCapture

public PacketCapture(CaptureDevice device,
                     int snaplen,
                     boolean promiscuous,
                     int timeout)
              throws CaptureDeviceOpenException

Construct a new instance and open the specified device for capture. This is equivalent to:

        PacketCapture packetCapture = new PacketCapture();
        packetCapture.open(device, snaplen, promiscuous, timeout);

Parameters:

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

Since:

2.0.0

PacketCapture

public PacketCapture(File file)
              throws CaptureFileOpenException

Construct a new instance and open the specified file for capture. This is equivalent to:

        PacketCapture packetCapture = new PacketCapture();
        packetCapture.openOffline(file.getPath());

Parameters:

file - tcpdump-formatted savefile to capture from.

Throws:

CaptureFileOpenException - can't open capture file

Since:

2.0.0

Method Detail

finalize

protected void finalize()
                 throws Throwable

Releases the JNI 'instance' number so it can be reused.

Overrides:

finalize in class Object

Throws:

Throwable

Since:

2.0.0

compileFilter

public CompiledFilter compileFilter(String filter,
                                    boolean optimize)
                             throws InvalidFilterException

Compile a filter expression for the current capture device.

Parameters:

filter - Filter expression.

optimize - Controls whether the filter is optimized when compiled.

Returns:

a CompiledFilter, for use with setFilter(CompiledFilter).

Throws:

InvalidFilterException - Invalid filter syntax, or capture device is not open.

configureBlocking

public void configureBlocking(boolean blocking)
                       throws IOException

Configure the blocking mode. Non-blocking mode causes the capture methods to return immediately if there are no packets to capture, rather than waiting for the specified timeout period. When capturing from a savefile, this method has no effect.

Parameters:

blocking - If true, this channel will be placed in blocking mode; if false, it will be placed non-blocking mode.

Throws:

IOException - I/O problem changing the blocking mode.

Since:

2.0.0

isBlocking

public boolean isBlocking()
                   throws IOException

Return true if the capture device is in blocking mode, false for non-blocking mode.

Returns:

true iff this channel is in blocking mode.

Throws:

IOException - I/O problem determining the blocking mode (e.g. capture device not open).

Since:

2.0.0

open

public void open(CaptureDevice device,
                 boolean promiscuous)
          throws CaptureDeviceOpenException

Open a network device for data capture. This is equivalent to open(device, DEFAULT_SNAPLEN, promiscuous, DEFAULT_TIMEOUT);

Parameters:

device - the CaptureDevice to open.

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 - can't open the specified device

Since:

2.0.0

See Also:

open(CaptureDevice, int, boolean, int)

open

public void open(CaptureDevice device,
                 int snaplen,
                 boolean promiscuous,
                 int timeout)
          throws CaptureDeviceOpenException

Open a network device for data capture.

Parameters:

device - the CaptureDevice to open.

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

Since:

2.0.0

open

public 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);

Specified by:

open in interface PacketCaptureCapable

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:

PacketCaptureCapable.open(String, int, boolean, int)

open

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

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

public void openOffline(String fileName)
                 throws CaptureFileOpenException

Open a tcpdump-formatted savefile for reading.

Specified by:

openOffline in interface PacketCaptureCapable

Parameters:

fileName - the name of the savefile.

Throws:

CaptureFileOpenException - can't open the specified file

setFilter

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

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

This is a shorthand for setFilter(compileFilter(filterExpression, optimize));

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 - invalid filter specification

setFilter

public void setFilter(CompiledFilter filter)
               throws InvalidFilterException

Set the filter from a precompiled filter.

Parameters:

filter - CompiledFilter, from compileFilter(java.lang.String, boolean)

Throws:

InvalidFilterException - Capture device is not open

capture

public void capture(int count)
             throws CapturePacketException

Capture packets.

Specified by:

capture in interface PacketCaptureCapable

Parameters:

count - the number of packets to capture. If count is -1, this method will run forever unless PacketCaptureCapable.endCapture() is called or an exception is thrown.

Throws:

CapturePacketException - Capture problem

captureNext

public Packet captureNext()
                   throws CapturePacketException,
                          SocketTimeoutException,
                          EOFException,
                          IOException

Return the next packet captured. For libpcap programmers, this method calls pcap_next_ex().

Returns:

a Packet

Throws:

CapturePacketException - some libpcap error.

SocketTimeoutException - The timeout specified when the capture device was opened has expired without a packet being captured.

EOFException - EOF on savefile.

IOException - capture device is closed.

captureTo

public int captureTo(int count,
                     PacketOutputStream out)
              throws CapturePacketException,
                     IOException,
                     IllegalArgumentException

Capture packets and dump them to the network or a tcpdump-formatted savefile. You can do this manually yourself but this method is considerably more efficient, as it doesn't have to construct Packet objects or cross and re-cross the Java/JNI interface.

Note that to replay a savefile, you need to call this method on a PacketCapture handle which is open 'offline', supplying a PacketOutputStream created by getOutputStream() from another PacketCapture handle that was created to capture 'online', i.e. with an open network device.

Parameters:

count - Maximum count of packets to capture, or -1 for infinity.

out - PacketOutputStream to dump to.

Returns:

the number of packets captured and dumped.

Throws:

CapturePacketException - Packet capture problem.

IOException - I/O problem on dump file.

IllegalArgumentException - if this PacketCapture object is capturing from the network and the output stream is dumping to the network, as this will just break your network.

Since:

2.0.0

getStatistics

public CaptureStatistics getStatistics()

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

Specified by:

getStatistics in interface PacketCaptureCapable

Returns:

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

close

public void close()

Description copied from interface: PacketCaptureCapable

Close cleans up after a packet capture session. It does not terminate a packet capture. PacketCaptureCapable.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 PacketCaptureCapable.endCapture().

Specified by:

close in interface Closeable

Specified by:

close in interface PacketCaptureCapable

isClosed

public boolean isClosed()

Return true if the captor is closed or a device or capture file hasn't been opened yet.

Returns:

false iff the captor is currently open.

getDevice

public CaptureDevice getDevice()

Return the current capture device.

Returns:

the current capture device, or null if not opened via a CaptureDevice, or closed.

Since:

2.0.0

endCapture

public void endCapture()

Stop capturing packets. Any current PacketCaptureCapable.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.

Specified by:

endCapture in interface PacketCaptureCapable

findCaptureDevice

public static CaptureDevice findCaptureDevice()
                                       throws CaptureDeviceNotFoundException,
                                              CaptureConfigurationException

Find a suitable CaptureDevice for live capture. This just returns the first element returned by lookupCaptureDevices() that isn't a loopback device.

Returns:

a CaptureDevice.

Throws:

CaptureDeviceNotFoundException - No usable capture device found

CaptureConfigurationException - Capture device configuration problem

Since:

2.0.0

findDevice

public String findDevice()
                  throws CaptureDeviceNotFoundException

Deprecated. Please use findCaptureDevice().

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.

Specified by:

findDevice in interface PacketCaptureCapable

Returns:

the network device name.

Throws:

CaptureDeviceNotFoundException - No capture devices found

lookupCaptureDevices

public static CaptureDevice[] lookupCaptureDevices()
                                            throws CaptureDeviceLookupException,
                                                   CaptureConfigurationException

Get the interface list as an array of CaptureDevice[]. The JNI implementation under this method uses standard libpcap code, not system-dependent code, so it should be much less fragile at the Jpcap.dll level than lookupDevices() used to be.

As it returns CaptureDevices, which have complete device information in them, including a list of IPv4 or IPv6 address/netmask information, this method also obsoletes the getNetwork(java.lang.String) and getNetmask(java.lang.String) methods.

Returns:

an array of CaptureDevices, possibly zero-length, never null. Devices that aren't 'up' or don't have IP addresses are not returned.

Throws:

CaptureDeviceLookupException - Capture device lookup problem

CaptureConfigurationException - Capture device configuration problem

Since:

2.0.0

lookupDevices

public static String[] lookupDevices()
                              throws CaptureDeviceLookupException

Deprecated. Please use lookupCaptureDevices().

Get Interface List.

This API will be removed in a future release.

Returns:

Network device interface names.

Throws:

CaptureDeviceLookupException - Capture device lookup problem

getNetwork

public int getNetwork(String name)
               throws CaptureConfigurationException

Deprecated. Please use lookupCaptureDevices().

Fetch the network address for the specified device.

This API:

• does not work reliably, the byte-ordering being uncertain
• cannot by design cope with interfaces that have multiple IP addresses
• cannot by design cope with IPv6 addresses.

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

Specified by:

getNetwork in interface PacketCaptureCapable

Parameters:

name - the name of the network device.

Returns:

the network address

Throws:

CaptureConfigurationException - Capture device not found

getNetmask

public int getNetmask(String name)
               throws CaptureConfigurationException

Deprecated. Please use lookupCaptureDevices().

Fetch the network mask for the specified device.

This API:

• does not work reliably, the byte-ordering being uncertain
• cannot by design cope with interfaces that have multiple IP addresses
• cannot by design cope with IPv6 addresses.

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

Specified by:

getNetmask in interface PacketCaptureCapable

Parameters:

name - the name of the network device.

Returns:

the netmask address

Throws:

CaptureConfigurationException - Capture device not found

getLinkLayerDescription

public String getLinkLayerDescription()
                               throws CaptureConfigurationException

Description copied from interface: PacketCaptureCapable

Return a description of the link layer for the current capture device, corresponding to PacketCaptureCapable.getLinkLayerType().

Specified by:

getLinkLayerDescription in interface PacketCaptureCapable

Returns:

link layer description.

Throws:

CaptureConfigurationException - Unknown link layer type.

getLinkLayerDescription

public String getLinkLayerDescription(int linkType)
                               throws CaptureConfigurationException

Return the link layer description for the specified type.

Parameters:

linkType - Link type.

Returns:

the link layer description.

Throws:

CaptureConfigurationException - I/O problem getting description.

Since:

2.0.0

getLinkLayerName

public String getLinkLayerName()
                        throws CaptureConfigurationException

Return the link layer name, e.g. "eth10".

Returns:

the link layer name.

Throws:

CaptureConfigurationException - Error finding the name

Since:

2.0.0

getLinkLayerName

public String getLinkLayerName(int linkType)
                        throws CaptureConfigurationException

Return the link layer name for the specified linkType.

Parameters:

linkType - link type.

Returns:

the link layer name.

Throws:

CaptureConfigurationException - Error finding the name

Since:

2.0.0

getLinkLayerType

public int getLinkLayerType()
                     throws CaptureConfigurationException

Fetch the link layer type for the current capture device.

Specified by:

getLinkLayerType in interface PacketCaptureCapable

Returns:

the link layer type code.

Throws:

CaptureConfigurationException - Capture configuration lookup problem

getLinkLayerTypes

public int[] getLinkLayerTypes()
                        throws CaptureConfigurationException

Get the available link layer types for the current capture device.

Returns:

an array of link layer types, suitable for use with setLinkLayerType(int).

Throws:

CaptureConfigurationException - Problem getting the link layer types.

Since:

2.0.0

setLinkLayerType

public void setLinkLayerType(int linkType)
                      throws CaptureConfigurationException

Set the current link layer type.

Parameters:

linkType - Link layer type: must be a supported type for the current adapter, e.g. as returned by getLinkLayerTypes().

Throws:

CaptureConfigurationException - Problem setting the link layer type.

Since:

2.0.0

getSnapshotLength

public int getSnapshotLength()

Get the snapshot length specified when this network device was opened.

Specified by:

getSnapshotLength in interface PacketCaptureCapable

Returns:

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

getLibVersion

public static String getLibVersion()

Return a string giving information about the version of the libpcap library being used; note that it contains more information than just a version number.

Returns:

String.

Since:

2.0.0

getLoopMode

public PacketCapture.LoopMode getLoopMode()

Get the current loop mode.

Returns:

the current loop mode.

Since:

2.0.0

setLoopMode

public void setLoopMode(PacketCapture.LoopMode loopMode)

Set the current loop mode.

Calling this method while a capture is in progress may or may not alter the mode.

Parameters:

loopMode - New loop mode.

Since:

2.0.0

getInputStream

public PacketInputStream getInputStream()
                                 throws IOException

Return a PacketInputStream for reading packets from the network. Multiple calls will always return the same input stream while the same capture device is open.

Returns:

a PacketInputStream.

Throws:

IOException - I/O problem creating the stream.

Since:

2.0.0

getOutputStream

public PacketOutputStream getOutputStream()
                                   throws IOException

Return a PacketOutputStream that sends packets to the network device opened by this PacketCapture. Repeated calls against the same captor return the same networkOutputStream.

Returns:

a packet networkOutputStream.

Throws:

IOException - I/O problem, e.g. the capture device or file is closed.

Since:

2.0.0

getOutputStream

public PacketOutputStream getOutputStream(File file)
                                   throws IOException

Return a PacketOutputStream that dumps packets to a tcpdump-formatted savefile. Only one packet saveOutputStream stream can be open at a time.

Parameters:

file - File to dump packets to, in tcpdump format.

Returns:

a packet writer for this captor.

Throws:

IOException - I/O problem opening the dump file, or a packet saveOutputStream is currently open.

Since:

2.0.0

setDirection

public void setDirection(PacketCapture.Direction direction)
                  throws IOException,
                         UnsupportedOperationException

Set the direction of packet capture. PacketCapture.Direction.PCAP_D_INOUT is the default setting if this function is not called. This isn't necessarily supported on all platforms; some platforms might throw UnsupportedOperationException, and some other platforms might not support PacketCapture.Direction.PCAP_D_OUT. This operation is not supported if a 'savefile' is being read. Note: not supported on Windows.

Parameters:

direction - PacketCapture.Direction of packet capture.

Throws:

IOException - Problem setting the capture direction.

UnsupportedOperationException - Operation not supported on this platform

Since:

2.0.0

See Also:

PacketCapture.Direction