org.pcap4j.core

Class PcapHandle

java.lang.Object

org.pcap4j.core.PcapHandle

All Implemented Interfaces:

java.lang.AutoCloseable

public final class PcapHandle
extends java.lang.Object
implements java.lang.AutoCloseable

A wrapper class for struct pcap_t.

Since:

pcap4j 0.9.1

Author:

Kaito Yamada

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field and Description
static java.net.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.

Method Summary

Modifier and Type	Method and Description
void	breakLoop() Breaks a loop which this handle is working on.
void	close() Closes this PcapHandle.
BpfProgram	compileFilter(java.lang.String bpfExpression, BpfProgram.BpfCompileMode mode, java.net.Inet4Address netmask)
int	dispatch(int packetCount, PacketListener listener)
int	dispatch(int packetCount, PacketListener listener, java.util.concurrent.Executor executor)
PcapDumper	dumpOpen(java.lang.String filePath)
PcapHandle.BlockingMode	getBlockingMode()
DataLinkType	getDlt()
java.lang.String	getError()
java.lang.String	getFilteringExpression()
int	getMajorVersion()
int	getMinorVersion()
PcapPacket	getNextPacket()
PcapPacket	getNextPacketEx()
int	getSnapshot()
PcapStat	getStats()
PcapHandle.TimestampPrecision	getTimestampPrecision()
boolean	isOpen()
PcapHandle.SwappedType	isSwapped()
java.util.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, java.util.concurrent.Executor executor) A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *).
void	loop(int packetCount, PcapDumper dumper)
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(BpfProgram prog)
void	setFilter(java.lang.String bpfExpression, BpfProgram.BpfCompileMode mode)
void	setFilter(java.lang.String bpfExpression, BpfProgram.BpfCompileMode mode, java.net.Inet4Address netmask)
java.util.stream.Stream<PcapPacket>	stream() Returns a Stream instance representing a stream of captured packets.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

PCAP_NETMASK_UNKNOWN

public static final java.net.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.

Method Detail

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 java.lang.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.

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(java.lang.String bpfExpression,
                                BpfProgram.BpfCompileMode mode,
                                java.net.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(java.lang.String bpfExpression,
                      BpfProgram.BpfCompileMode mode,
                      java.net.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.

java.lang.NullPointerException - if any of arguments are null.

setFilter

public void setFilter(java.lang.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.

java.lang.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.

java.lang.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 PcapPacket getNextPacket()
                         throws NotOpenException

Returns:

a PcapPacket object that contains captured packet. May be null.

Throws:

NotOpenException - if this PcapHandle is not open.

getNextPacketEx

public PcapPacket getNextPacketEx()
                           throws PcapNativeException,
                                  java.io.EOFException,
                                  java.util.concurrent.TimeoutException,
                                  NotOpenException

Returns:

a PcapPacket object that contains captured packet. Not null.

Throws:

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

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

java.util.concurrent.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,
                 java.lang.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.

java.lang.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,
                 java.util.concurrent.Executor executor)
          throws PcapNativeException,
                 java.lang.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.

java.lang.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)
             throws PcapNativeException,
                    java.lang.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.

java.lang.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,
                    java.util.concurrent.Executor executor)
             throws PcapNativeException,
                    java.lang.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.

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

NotOpenException - if this PcapHandle is not open.

dumpOpen

public PcapDumper dumpOpen(java.lang.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,
                 java.lang.InterruptedException,
                 NotOpenException

Parameters:

packetCount - packetCount

dumper - dumper

Throws:

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

java.lang.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.

stream

public java.util.stream.Stream<PcapPacket> stream()
                                           throws NotOpenException

Returns a Stream instance representing a stream of captured packets. When this handle become unable to capture packets anymore (e.g. reaches EOF of the pcap file), the stream starts to supply nulls. This method locks this handle. Call BaseStream.close() to unlock.

Returns:

a stream of captured packets.

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.

java.lang.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.

java.lang.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.

java.lang.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 java.util.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 java.lang.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 java.lang.AutoCloseable

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object