org.pcap4j.core

Class PcapHandle

java.lang.Object

org.pcap4j.core.PcapHandle

public final class PcapHandle
extends Object

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

Method Summary

Methods

Modifier and Type	Method and Description
void	breakLoop() Breaks a loop which this handle is working on.
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)
PcapDumper	dumpOpen(String filePath)
PcapHandle.BlockingMode	getBlockingMode()
DataLinkType	getDlt()
String	getError()
String	getFilteringExpression()
int	getMajorVersion()
int	getMinorVersion()
Packet	getNextPacket()
Packet	getNextPacketEx()
byte[]	getNextRawPacket()
byte[]	getNextRawPacketEx()
int	getSnapshot()
PcapStat	getStats()
Long	getTimestampInts()
Integer	getTimestampMicros()
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(Packet packet)
void	setBlockingMode(PcapHandle.BlockingMode mode)
void	setDlt(DataLinkType dlt)
void	setFilter(BpfProgram prog)
void	setFilter(String bpfExpression, BpfProgram.BpfCompileMode mode)
void	setFilter(String bpfExpression, BpfProgram.BpfCompileMode mode, Inet4Address netmask)
String	toString()

Methods inherited from class java.lang.Object

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

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

NotOpenException

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

getTimestampInts

public Long getTimestampInts()

Returns:

an integer part of a timestamp of a packet captured in a current thread.

getTimestampMicros

public Integer getTimestampMicros()

Returns:

a fraction part of a timestamp of a packet captured in a current thread. The value represents the number of microseconds.

getSnapshot

public int getSnapshot()
                throws NotOpenException

Returns:

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

Throws:

NotOpenException

isSwapped

public PcapHandle.SwappedType isSwapped()
                                 throws NotOpenException

Returns:

a SwappedType object.

Throws:

NotOpenException

getMajorVersion

public int getMajorVersion()
                    throws NotOpenException

Returns:

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

Throws:

NotOpenException

getMinorVersion

public int getMinorVersion()
                    throws NotOpenException

Returns:

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

Throws:

NotOpenException

compileFilter

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

Parameters:

bpfExpression -

mode -

netmask -

Returns:

a BpfProgram object.

Throws:

PcapNativeException

NotOpenException

setFilter

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

Parameters:

bpfExpression -

mode -

netmask -

Throws:

PcapNativeException

NotOpenException

NullPointerException

setFilter

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

Parameters:

bpfExpression -

mode -

Throws:

PcapNativeException

NotOpenException

NullPointerException

setFilter

public void setFilter(BpfProgram prog)
               throws PcapNativeException,
                      NotOpenException

Parameters:

prog -

Throws:

PcapNativeException

NotOpenException

setBlockingMode

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

Parameters:

mode -

Throws:

PcapNativeException

NotOpenException

getBlockingMode

public PcapHandle.BlockingMode getBlockingMode()
                                        throws PcapNativeException,
                                               NotOpenException

Returns:

blocking mode

Throws:

PcapNativeException

NotOpenException

getNextPacket

public Packet getNextPacket()
                     throws NotOpenException

Returns:

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

Throws:

NotOpenException

getNextRawPacket

public byte[] getNextRawPacket()
                        throws NotOpenException

Returns:

a captured packet. May be null.

Throws:

NotOpenException

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

EOFException

TimeoutException

NotOpenException

getNextRawPacketEx

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

Returns:

a captured packet. Not null.

Throws:

PcapNativeException

EOFException

TimeoutException

NotOpenException

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 -

Throws:

PcapNativeException

InterruptedException

NotOpenException

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 -

executor -

Throws:

PcapNativeException

InterruptedException

NotOpenException

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 -

Throws:

PcapNativeException

InterruptedException

NotOpenException

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 -

executor -

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 -

Returns:

the number of captured packets.

Throws:

PcapNativeException

InterruptedException

NotOpenException

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 -

executor -

Returns:

the number of captured packets.

Throws:

PcapNativeException

InterruptedException

NotOpenException

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 -

Returns:

the number of captured packets.

Throws:

PcapNativeException

InterruptedException

NotOpenException

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 -

executor -

Returns:

the number of captured packets.

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

NotOpenException

loop

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

Parameters:

packetCount -

dumper -

Throws:

PcapNativeException

InterruptedException

NotOpenException

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

sendPacket

public void sendPacket(Packet packet)
                throws PcapNativeException,
                       NotOpenException

Parameters:

packet -

Throws:

PcapNativeException

NotOpenException

NullPointerException

getStats

public PcapStat getStats()
                  throws PcapNativeException,
                         NotOpenException

Returns:

a PcapStat object.

Throws:

PcapNativeException

NotOpenException

listDatalinks

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

Returns:

a list of DataLinkType

Throws:

PcapNativeException

NotOpenException

getError

public String getError()
                throws NotOpenException

Returns:

an error message.

Throws:

NotOpenException

close

public void close()

Closes this PcapHandle.

toString

public String toString()

Overrides:

toString in class Object