Class PcapHandle

java.lang.Object

org.pcap4j.core.PcapHandle

All Implemented Interfaces:

Closeable, AutoCloseable

public final class PcapHandle
extends Object
implements Closeable

A wrapper class for struct pcap_t.

Since:

pcap4j 0.9.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	PcapHandle.BlockingMode
static final class	PcapHandle.Builder	This class is used to open (i.e.
private final class	PcapHandle.GotPacketFuncExecutor
private final class	PcapHandle.GotRawPacketFuncExecutor
static enum	PcapHandle.PcapDirection	Direction of packets.
private static final class	PcapHandle.SimpleExecutor
static enum	PcapHandle.SwappedType
static enum	PcapHandle.TimestampPrecision

Field Summary

Fields

Modifier and Type	Field	Description
private static final Object	compileLock
private DataLinkType	dlt
private String	filteringExpression
private final com.sun.jna.Pointer	handle
private final ReentrantReadWriteLock	handleLock
private static final org.slf4j.Logger	logger
private boolean	open
private final ThreadLocal<Integer>	originalLengths
static final Inet4Address	PCAP_NETMASK_UNKNOWN	The netmask used for setFilter(String, BpfProgram.BpfCompileMode, Inet4Address) or compileFilter(String, BpfProgram.BpfCompileMode, Inet4Address) when you don't know what netmask you should use.
private final PcapHandle.TimestampPrecision	timestampPrecision
private final ThreadLocal<Timestamp>	timestamps

Constructor Summary

Constructors

Modifier	Constructor	Description
(package private)	PcapHandle(com.sun.jna.Pointer handle, PcapHandle.TimestampPrecision timestampPrecision)
private	PcapHandle(PcapHandle.Builder builder)

Method Summary

Modifier and Type	Method	Description
void	breakLoop()	Breaks a loop which this handle is working on.
private Timestamp	buildTimestamp(com.sun.jna.Pointer header)
void	close()	Closes this PcapHandle.
BpfProgram	compileFilter(String bpfExpression, BpfProgram.BpfCompileMode mode, Inet4Address netmask)
int	dispatch(int packetCount, PacketListener listener)
int	dispatch(int packetCount, PacketListener listener, Executor executor)
int	dispatch(int packetCount, RawPacketListener listener)
int	dispatch(int packetCount, RawPacketListener listener, Executor executor)
private int	doDispatch(int packetCount, NativeMappings.pcap_handler handler)
private void	doLoop(int packetCount, NativeMappings.pcap_handler handler)
PcapDumper	dumpOpen(String filePath)
PcapHandle.BlockingMode	getBlockingMode()
DataLinkType	getDlt()
private DataLinkType	getDltByNative()
String	getError()
String	getFilteringExpression()
int	getMajorVersion()
int	getMinorVersion()
Packet	getNextPacket()
Packet	getNextPacketEx()
byte[]	getNextRawPacket()
byte[]	getNextRawPacketEx()
Integer	getOriginalLength()
int	getSnapshot()
PcapStat	getStats()
Timestamp	getTimestamp()
PcapHandle.TimestampPrecision	getTimestampPrecision()
boolean	isOpen()
PcapHandle.SwappedType	isSwapped()
List<DataLinkType>	listDatalinks()
void	loop(int packetCount, PacketListener listener)	A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *).
void	loop(int packetCount, PacketListener listener, Executor executor)	A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *).
void	loop(int packetCount, PcapDumper dumper)
void	loop(int packetCount, RawPacketListener listener)	A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *).
void	loop(int packetCount, RawPacketListener listener, Executor executor)	A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *).
void	sendPacket(byte[] bytes)
void	sendPacket(byte[] bytes, int len)
void	sendPacket(Packet packet)
void	setBlockingMode(PcapHandle.BlockingMode mode)
void	setDirection(PcapHandle.PcapDirection direction)	Set direction flag, which controls whether we accept only incoming packets, only outgoing packets, or both.
void	setDlt(DataLinkType dlt)
void	setFilter(String bpfExpression, BpfProgram.BpfCompileMode mode)
void	setFilter(String bpfExpression, BpfProgram.BpfCompileMode mode, Inet4Address netmask)
void	setFilter(BpfProgram prog)
String	toString()

Methods inherited from class Object

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

Field Details

logger

private static final org.slf4j.Logger logger

dlt

private volatile DataLinkType dlt

timestampPrecision

private final PcapHandle.TimestampPrecision timestampPrecision

handle

private final com.sun.jna.Pointer handle

timestamps

private final ThreadLocal<Timestamp> timestamps

originalLengths

private final ThreadLocal<Integer> originalLengths

handleLock

private final ReentrantReadWriteLock handleLock

compileLock

private static final Object compileLock

open

private volatile boolean open

filteringExpression

private volatile String filteringExpression

PCAP_NETMASK_UNKNOWN

public static final Inet4Address PCAP_NETMASK_UNKNOWN

The netmask used for setFilter(String, BpfProgram.BpfCompileMode, Inet4Address) or compileFilter(String, BpfProgram.BpfCompileMode, Inet4Address) when you don't know what netmask you should use.

Constructor Details

PcapHandle

PcapHandle(com.sun.jna.Pointer handle,
 PcapHandle.TimestampPrecision timestampPrecision)

PcapHandle

private PcapHandle(PcapHandle.Builder builder)
            throws PcapNativeException

Throws:

PcapNativeException

Method Details

getDltByNative

private DataLinkType getDltByNative()

getDlt

public DataLinkType getDlt()

Returns:

the Data Link Type of this PcapHandle

setDlt

public void setDlt(DataLinkType dlt)
            throws PcapNativeException,
NotOpenException

Parameters:

dlt - a DataLinkType object to set

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

isOpen

public boolean isOpen()

Returns:

true if this PcapHandle object is open (i.e. not yet closed by close()); false otherwise.

getFilteringExpression

public String getFilteringExpression()

Returns:

the filtering expression of this PcapHandle

getTimestampPrecision

public PcapHandle.TimestampPrecision getTimestampPrecision()

Returns:

Timestamp precision

setDirection

public void setDirection(PcapHandle.PcapDirection direction)
                  throws PcapNativeException,
NotOpenException

Set direction flag, which controls whether we accept only incoming packets, only outgoing packets, or both. Note that, depending on the platform, some or all direction arguments might not be supported.

Parameters:

direction - direction to set.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

getTimestamp

public Timestamp getTimestamp()

Returns:

the timestamp of the last packet captured by this handle in the current thread.

getOriginalLength

public Integer getOriginalLength()

Returns:

the original length of the last packet captured by this handle in the current thread.

getSnapshot

public int getSnapshot()
                throws NotOpenException

Returns:

the dimension of the packet portion (in bytes) that is delivered to the application.

Throws:

NotOpenException - if this PcapHandle is not open.

isSwapped

public PcapHandle.SwappedType isSwapped()
                                 throws NotOpenException

Returns:

a SwappedType object.

Throws:

NotOpenException - if this PcapHandle is not open.

getMajorVersion

public int getMajorVersion()
                    throws NotOpenException

Returns:

the major version number of the pcap library used to write the savefile.

Throws:

NotOpenException - if this PcapHandle is not open.

getMinorVersion

public int getMinorVersion()
                    throws NotOpenException

Returns:

the minor version number of the pcap library used to write the savefile.

Throws:

NotOpenException - if this PcapHandle is not open.

compileFilter

public BpfProgram compileFilter(String bpfExpression,
 BpfProgram.BpfCompileMode mode,
 Inet4Address netmask)
                         throws PcapNativeException,
NotOpenException

Parameters:

bpfExpression - bpfExpression

mode - mode

netmask - netmask

Returns:

a BpfProgram object.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

setFilter

public void setFilter(String bpfExpression,
 BpfProgram.BpfCompileMode mode,
 Inet4Address netmask)
               throws PcapNativeException,
NotOpenException

Parameters:

bpfExpression - bpfExpression

mode - mode

netmask - netmask

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

NullPointerException - if any of arguments are null.

setFilter

public void setFilter(String bpfExpression,
 BpfProgram.BpfCompileMode mode)
               throws PcapNativeException,
NotOpenException

Parameters:

bpfExpression - bpfExpression

mode - mode

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

NullPointerException - if any of arguments are null.

setFilter

public void setFilter(BpfProgram prog)
               throws PcapNativeException,
NotOpenException

Parameters:

prog - prog

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

NullPointerException - if any of arguments are null.

setBlockingMode

public void setBlockingMode(PcapHandle.BlockingMode mode)
                     throws PcapNativeException,
NotOpenException

Parameters:

mode - mode

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

getBlockingMode

public PcapHandle.BlockingMode getBlockingMode()
                                        throws PcapNativeException,
NotOpenException

Returns:

blocking mode

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

getNextPacket

public Packet getNextPacket()
                     throws NotOpenException

Returns:

a Packet object created from a captured packet using the packet factory. May be null.

Throws:

NotOpenException - if this PcapHandle is not open.

getNextRawPacket

public byte[] getNextRawPacket()
                        throws NotOpenException

Returns:

a captured packet. May be null.

Throws:

NotOpenException - if this PcapHandle is not open.

getNextPacketEx

public Packet getNextPacketEx()
                       throws PcapNativeException,
EOFException,
TimeoutException,
NotOpenException

Returns:

a Packet object created from a captured packet using the packet factory. Not null.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

EOFException - if packets are being read from a pcap file and there are no more packets to read from the file.

TimeoutException - if packets are being read from a live capture and the timeout expired.

NotOpenException - if this PcapHandle is not open.

getNextRawPacketEx

public byte[] getNextRawPacketEx()
                          throws PcapNativeException,
EOFException,
TimeoutException,
NotOpenException

Returns:

a captured packet. Not null.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

EOFException - if packets are being read from a pcap file and there are no more packets to read from the file.

TimeoutException - if packets are being read from a live capture and the timeout expired.

NotOpenException - if this PcapHandle is not open.

loop

public void loop(int packetCount,
 PacketListener listener)
          throws PcapNativeException,
InterruptedException,
NotOpenException

A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). This method creates a Packet object from a captured packet using the packet factory and passes it to listener.gotPacket(Packet). When a packet is captured, listener.gotPacket(Packet) is called in the thread which called the loop() . And then this PcapHandle waits for the thread to return from the gotPacket() before it retrieves the next packet from the pcap buffer.

Parameters:

packetCount - the number of packets to capture. -1 is equivalent to infinity. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

loop

public void loop(int packetCount,
 PacketListener listener,
 Executor executor)
          throws PcapNativeException,
InterruptedException,
NotOpenException

A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). This method creates a Packet object from a captured packet using the packet factory and passes it to listener.gotPacket(Packet). When a packet is captured, the executor.execute() is called with a Runnable object in the thread which called the loop(). Then, the Runnable object calls listener.gotPacket(Packet). If listener.gotPacket(Packet) is expected to take a long time to process a packet, this method should be used with a proper executor instead of loop(int, PacketListener) in order to prevent the pcap buffer from overflowing.

Parameters:

packetCount - the number of packets to capture. -1 is equivalent to infinity. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

executor - executor

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

loop

public void loop(int packetCount,
 RawPacketListener listener)
          throws PcapNativeException,
InterruptedException,
NotOpenException

A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). When a packet is captured, listener.gotPacket(byte[]) is called in the thread which called the loop(). And then this PcapHandle waits for the thread to return from the gotPacket() before it retrieves the next packet from the pcap buffer.

Parameters:

packetCount - the number of packets to capture. -1 is equivalent to infinity. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

loop

public void loop(int packetCount,
 RawPacketListener listener,
 Executor executor)
          throws PcapNativeException,
InterruptedException,
NotOpenException

A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). When a packet is captured, the executor.execute() is called with a Runnable object in the thread which called the loop(). Then, the Runnable object calls listener.gotPacket(byte[]). If listener.gotPacket(byte[]) is expected to take a long time to process a packet, this method should be used with a proper executor instead of loop(int, RawPacketListener) in order to prevent the pcap buffer from overflowing.

Parameters:

packetCount - the number of packets to capture. -1 is equivalent to infinity. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

executor - executor

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

doLoop

private void doLoop(int packetCount,
 NativeMappings.pcap_handler handler)
             throws PcapNativeException,
InterruptedException,
NotOpenException

Throws:

PcapNativeException

InterruptedException

NotOpenException

dispatch

public int dispatch(int packetCount,
 PacketListener listener)
             throws PcapNativeException,
InterruptedException,
NotOpenException

Parameters:

packetCount - the maximum number of packets to process. If -1 is specified, all the packets in the pcap buffer or pcap file will be processed before returning. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

Returns:

the number of captured packets.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

dispatch

public int dispatch(int packetCount,
 PacketListener listener,
 Executor executor)
             throws PcapNativeException,
InterruptedException,
NotOpenException

Parameters:

packetCount - the maximum number of packets to process. If -1 is specified, all the packets in the pcap buffer or pcap file will be processed before returning. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

executor - executor

Returns:

the number of captured packets.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

dispatch

public int dispatch(int packetCount,
 RawPacketListener listener)
             throws PcapNativeException,
InterruptedException,
NotOpenException

Parameters:

packetCount - the maximum number of packets to process. If -1 is specified, all the packets in the pcap buffer or pcap file will be processed before returning. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

Returns:

the number of captured packets.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

dispatch

public int dispatch(int packetCount,
 RawPacketListener listener,
 Executor executor)
             throws PcapNativeException,
InterruptedException,
NotOpenException

Parameters:

packetCount - the maximum number of packets to process. If -1 is specified, all the packets in the pcap buffer or pcap file will be processed before returning. 0 may result in different behaviors between platforms and pcap library versions.

listener - listener

executor - executor

Returns:

the number of captured packets.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

doDispatch

private int doDispatch(int packetCount,
 NativeMappings.pcap_handler handler)
                throws PcapNativeException,
InterruptedException,
NotOpenException

Throws:

PcapNativeException

InterruptedException

NotOpenException

dumpOpen

public PcapDumper dumpOpen(String filePath)
                    throws PcapNativeException,
NotOpenException

Parameters:

filePath - "-" means stdout. The dlt of the PcapHandle which captured the packets you want to dump must be the same as this dlt.

Returns:

an opened PcapDumper.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

loop

public void loop(int packetCount,
 PcapDumper dumper)
          throws PcapNativeException,
InterruptedException,
NotOpenException

Parameters:

packetCount - packetCount

dumper - dumper

Throws:

PcapNativeException - if an error occurs in the pcap native library.

InterruptedException - if the loop terminated due to a call to breakLoop().

NotOpenException - if this PcapHandle is not open.

breakLoop

public void breakLoop()
               throws NotOpenException

Breaks a loop which this handle is working on.

The loop may not be broken immediately on some OSes because of buffering or something. As a workaround, letting this capture some bogus packets after calling this method may work.

Throws:

NotOpenException - if this PcapHandle is not open.

sendPacket

public void sendPacket(Packet packet)
                throws PcapNativeException,
NotOpenException

Parameters:

packet - packet

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

NullPointerException - if any of arguments are null.

sendPacket

public void sendPacket(byte[] bytes)
                throws NotOpenException,
PcapNativeException

Parameters:

bytes - raw bytes

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

NullPointerException - if any of arguments are null.

sendPacket

public void sendPacket(byte[] bytes,
 int len)
                throws NotOpenException,
PcapNativeException

Parameters:

bytes - raw bytes

len - length

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

NullPointerException - if any of arguments are null.

getStats

public PcapStat getStats()
                  throws PcapNativeException,
NotOpenException

Returns:

a PcapStat object.

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

listDatalinks

public List<DataLinkType> listDatalinks()
                                 throws PcapNativeException,
NotOpenException

Returns:

a list of DataLinkType

Throws:

PcapNativeException - if an error occurs in the pcap native library.

NotOpenException - if this PcapHandle is not open.

getError

public String getError()
                throws NotOpenException

Returns:

an error message.

Throws:

NotOpenException - if this PcapHandle is not open.

close

public void close()

Closes this PcapHandle.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

toString

public String toString()

Overrides:

toString in class Object

buildTimestamp

private Timestamp buildTimestamp(com.sun.jna.Pointer header)