|
SourceForge Jpcap | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.sourceforge.jpcap.capture.PacketDispatcher
net.sourceforge.jpcap.capture.PacketCaptureBase
net.sourceforge.jpcap.capture.PacketCapture
public class PacketCapture
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:
getInputStream()
(which corresponds to pcap_next_ex()
)
getOutputStream()
,
getOutputStream(File file)
captureTo(int, PacketOutputStream)
.
timeout
PacketCapture.LoopMode
setLoopMode()
, which defaults
to Loop
.
JWinPcap.getMinimumKernelCopy()
and setMinimumKernelCopy()
;
on non-Winpcap platforms it defaults to an unknown but probably similar value.
capture()
,
captureTo()
,
captureNext()
, or
PacketInputStream.readPacket()
.
count
capture()
.
capture()
in Loop
mode
loops doing the following until the specified count is reached:
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()
.
captureTo()
behaves the same as capture(),
i.e. it is subject to the LoopMode, MinimumKernelCopy, and timeout settings.
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
.
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:
PacketCaptureCapable
,
PacketInputStream
,
PacketOutputStream
,
PacketListener
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 |
---|
public static final String LIB_PCAP_WRAPPER
public static final int MAX_SNAPLEN
Constructor Detail |
---|
public PacketCapture()
public PacketCapture(CaptureDevice device, boolean promiscuous) throws CaptureDeviceOpenException
PacketCapture packetCapture = new PacketCapture();
packetCapture.open(device, DEFAULT_SNAPLEN, promiscuous, DEFAULT_TIMEOUT);
device
- CaptureDevice to capture from.promiscuous
- whether or not the device should be put into 'promiscuous' mode.
CaptureDeviceOpenException
- can't open the specified devicepublic PacketCapture(CaptureDevice device, int snaplen, boolean promiscuous, int timeout) throws CaptureDeviceOpenException
PacketCapture packetCapture = new PacketCapture();
packetCapture.open(device, snaplen, promiscuous, timeout);
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.
CaptureDeviceOpenException
- can't open the specified devicepublic PacketCapture(File file) throws CaptureFileOpenException
PacketCapture packetCapture = new PacketCapture();
packetCapture.openOffline(file.getPath());
file
- tcpdump-formatted savefile to capture from.
CaptureFileOpenException
- can't open capture fileMethod Detail |
---|
protected void finalize() throws Throwable
Releases the JNI 'instance' number so it can be reused.
finalize
in class Object
Throwable
public CompiledFilter compileFilter(String filter, boolean optimize) throws InvalidFilterException
filter
- Filter expression.optimize
- Controls whether the filter is optimized when compiled.
setFilter(CompiledFilter)
.
InvalidFilterException
- Invalid filter syntax, or capture device is not open.public void configureBlocking(boolean blocking) throws IOException
blocking
- If true, this channel will be placed in blocking mode;
if false, it will be placed non-blocking mode.
IOException
- I/O problem changing the blocking mode.public boolean isBlocking() throws IOException
IOException
- I/O problem determining the blocking mode (e.g. capture device not open).public void open(CaptureDevice device, boolean promiscuous) throws CaptureDeviceOpenException
open(device, DEFAULT_SNAPLEN, promiscuous, DEFAULT_TIMEOUT);
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.
CaptureDeviceOpenException
- can't open the specified deviceopen(CaptureDevice, int, boolean, int)
public void open(CaptureDevice device, int snaplen, boolean promiscuous, int timeout) throws CaptureDeviceOpenException
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.
CaptureDeviceOpenException
- can't open the specified devicepublic void open(String device, boolean promiscuous) throws CaptureDeviceOpenException
This call is equivalent to
open(device, DEFAULT_SNAPLEN, promiscuous, DEFAULT_TIMEOUT);
open
in interface PacketCaptureCapable
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.
CaptureDeviceOpenException
PacketCaptureCapable.open(String, int, boolean, int)
public void open(String device, int snaplen, boolean promiscuous, int timeout) throws CaptureDeviceOpenException
open
in interface PacketCaptureCapable
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.
CaptureDeviceOpenException
- can't open the specified devicepublic void openOffline(String fileName) throws CaptureFileOpenException
openOffline
in interface PacketCaptureCapable
fileName
- the name of the savefile.
CaptureFileOpenException
- can't open the specified filepublic void setFilter(String filterExpression, boolean optimize) throws InvalidFilterException
This is a shorthand for setFilter(compileFilter(filterExpression, optimize));
setFilter
in interface PacketCaptureCapable
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.
InvalidFilterException
- invalid filter specificationpublic void setFilter(CompiledFilter filter) throws InvalidFilterException
filter
- CompiledFilter, from compileFilter(java.lang.String, boolean)
InvalidFilterException
- Capture device is not openpublic void capture(int count) throws CapturePacketException
capture
in interface PacketCaptureCapable
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.
CapturePacketException
- Capture problempublic Packet captureNext() throws CapturePacketException, SocketTimeoutException, EOFException, IOException
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.public int captureTo(int count, PacketOutputStream out) throws CapturePacketException, IOException, IllegalArgumentException
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.
count
- Maximum count of packets to capture, or -1 for infinity.out
- PacketOutputStream to dump to.
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.public CaptureStatistics getStatistics()
PacketCaptureCapable.capture(int)
was previously called,
with capture occurring from a network device.
getStatistics
in interface PacketCaptureCapable
public void close()
PacketCaptureCapable
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()
.
close
in interface Closeable
close
in interface PacketCaptureCapable
public boolean isClosed()
public CaptureDevice getDevice()
public void endCapture()
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.
endCapture
in interface PacketCaptureCapable
public static CaptureDevice findCaptureDevice() throws CaptureDeviceNotFoundException, CaptureConfigurationException
lookupCaptureDevices()
that isn't a loopback device.
CaptureDeviceNotFoundException
- No usable capture device found
CaptureConfigurationException
- Capture device configuration problempublic String findDevice() throws CaptureDeviceNotFoundException
findCaptureDevice()
.
This API should be static; does not work reliably; and will be removed in a future release.
findDevice
in interface PacketCaptureCapable
CaptureDeviceNotFoundException
- No capture devices foundpublic static CaptureDevice[] lookupCaptureDevices() throws CaptureDeviceLookupException, CaptureConfigurationException
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.
CaptureDevices
, possibly zero-length, never null.
Devices that aren't 'up' or don't have IP addresses are not returned.
CaptureDeviceLookupException
- Capture device lookup problem
CaptureConfigurationException
- Capture device configuration problempublic static String[] lookupDevices() throws CaptureDeviceLookupException
lookupCaptureDevices()
.
This API will be removed in a future release.
CaptureDeviceLookupException
- Capture device lookup problempublic int getNetwork(String name) throws CaptureConfigurationException
lookupCaptureDevices()
.
This API:
For these reasons it will be removed in a future release.
getNetwork
in interface PacketCaptureCapable
name
- the name of the network device.
CaptureConfigurationException
- Capture device not foundpublic int getNetmask(String name) throws CaptureConfigurationException
lookupCaptureDevices()
.
This API:
For these reasons it will be removed in a future release.
getNetmask
in interface PacketCaptureCapable
name
- the name of the network device.
CaptureConfigurationException
- Capture device not foundpublic String getLinkLayerDescription() throws CaptureConfigurationException
PacketCaptureCapable
PacketCaptureCapable.getLinkLayerType()
.
getLinkLayerDescription
in interface PacketCaptureCapable
CaptureConfigurationException
- Unknown link layer type.public String getLinkLayerDescription(int linkType) throws CaptureConfigurationException
linkType
- Link type.
CaptureConfigurationException
- I/O problem getting description.public String getLinkLayerName() throws CaptureConfigurationException
CaptureConfigurationException
- Error finding the namepublic String getLinkLayerName(int linkType) throws CaptureConfigurationException
linkType
- link type.
CaptureConfigurationException
- Error finding the namepublic int getLinkLayerType() throws CaptureConfigurationException
getLinkLayerType
in interface PacketCaptureCapable
CaptureConfigurationException
- Capture configuration lookup problempublic int[] getLinkLayerTypes() throws CaptureConfigurationException
setLinkLayerType(int)
.
CaptureConfigurationException
- Problem getting the link layer types.public void setLinkLayerType(int linkType) throws CaptureConfigurationException
linkType
- Link layer type: must be a supported type for the
current adapter, e.g. as returned by getLinkLayerTypes()
.
CaptureConfigurationException
- Problem setting the link layer type.public int getSnapshotLength()
getSnapshotLength
in interface PacketCaptureCapable
public static String getLibVersion()
public PacketCapture.LoopMode getLoopMode()
public void setLoopMode(PacketCapture.LoopMode loopMode)
Calling this method while a capture is in progress may or may not alter the mode.
loopMode
- New loop mode.public PacketInputStream getInputStream() throws IOException
IOException
- I/O problem creating the stream.public PacketOutputStream getOutputStream() throws IOException
IOException
- I/O problem, e.g. the capture device or file is closed.public PacketOutputStream getOutputStream(File file) throws IOException
file
- File to dump packets to, in tcpdump format.
IOException
- I/O problem opening the dump file, or a packet saveOutputStream is currently open.public void setDirection(PacketCapture.Direction direction) throws IOException, UnsupportedOperationException
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.
direction
- PacketCapture.Direction
of packet capture.
IOException
- Problem setting the capture direction.
UnsupportedOperationException
- Operation not supported on this platformPacketCapture.Direction
|
Copyright © Patrick Charles & Jonas Lehmann, 2001; Esmond Pitt, 2008. | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |