SourceForge Jpcap

Package net.sourceforge.jpcap.capture

Provides an interface for capturing packets and a layer of abstraction around libpcap, a portable native system library for capturing network packets.

See:
          Description

Interface Summary
PacketCaptureCapable This is the packet capture interface.
PacketDispatchCapable An interface for classes capable of dispatching captured network packets.
PacketListener Packet data listener.
RawPacketListener Raw packet data listener.
StatisticsListener StatisticsListener is the callback that is used when a capture device is in JWinPcap.CaptureMode.Statistical mode.
 

Class Summary
CaptureDevice Encapsulates a capture-capable device.
CaptureDevice.Address The Address class encapsulates addressing information for a CaptureDevice.
CaptureStatistics Packet capture statistics.
CaptureTest Class to exercise PacketCapture.
CompiledFilter The CompiledFilter class encapsulates a compiled packet filter expression.
JWinPcap The JWinPcap class encapsulates the extended functions supported by the WinPcap native library.
JWinPcapTest Class to exercise JWinPcap.
PacketCapture This class is the core of packet capture in jpcap.
PacketCaptureBase This class contains base functionality shared by both the simulator and the actual packet capture system.
PacketDispatcher This class encapsulates a mechanism for dispatching network data and packets to a listener who has subscribed to such events.
PacketInputStream PacketInputStream provides an easy way of reading packets from the network or a savefile without having to define and register PacketListeners.
PacketOutputStream PacketOutputStream is an I/O stream used for sending Packets to the network, or dumping them to a tcpdump-formatted file, depending on how the stream was created.
StatisticsEvent StatisticsEvent encapsulates the statistics generated by JWinPcap.CaptureMode.Statistical.
 

Enum Summary
JWinPcap.CaptureMode Capture mode, for use with setCaptureMode().
JWinPcap.OpenFlags Open flags, for use with open().
JWinPcap.SamplingMethod Sampling method for use with setSamplingMethod().
PacketCapture.Direction Capture Direction enumeration.
PacketCapture.LoopMode LoopModes determine how the PacketCapture.capture(int) and PacketCapture.captureTo(int, net.sourceforge.jpcap.capture.PacketOutputStream) methods behave in the presence of timeouts.
 

Exception Summary
CaptureConfigurationException This exception occurs when the capture client tries to specify a capture device that does not exist or if the capture device specified is illegal.
CaptureDeviceInvalidException This exception occurs when the capture client tries to specify a capture device that does not exist or if the capture device specified is illegal.
CaptureDeviceLookupException This exception occurs when no capture devices are detected.
CaptureDeviceNotFoundException This exception occurs when no capture devices are detected.
CaptureDeviceOpenException This exception occurs when the capture device cannot be opened.
CaptureFileOpenException This exception occurs when a tcpdump-formatted savefile cannot be opened.
CapturePacketException This exception occurs when an error occurs while capturing data.
InvalidFilterException This exception occurs when an error occurs while capturing data.
JpcapException JpcapException is the base class for all Jpcap exceptions.
 

Package net.sourceforge.jpcap.capture Description

Provides an interface for capturing packets and a layer of abstraction around libpcap, a portable native system library for capturing network packets.

The PacketCapture class is the core of the packet capture system provided by jpcap.

Applications wishing to capture network packets create an instance of PacketCapture and call its methods in order to open a network device, set packet filters and ultimately receive packet data from the network.

PacketCapture utilizes an event-listener pattern to broadcast packets to all objects which have registered as listeners for events of interest. Applications capturing network data must implement PacketListener or RawPacketListener and register with an instance of the capture system in order to receive packets.

The JWinPcap class encapsulates the WinPcap extension API.

Coverage of libpcap and Winpcap

Between them, the PacketCapture and JWinPcap classes provide an almost complete coverage of the libpcap/Winpcap APIs, as described in the following subsections.

The mapping is as Java-like as possible, e.g. using InputStream and OutputStream where appropriate, rather than just mapping every 'C' method into a Java method. This approach also has the advantage of making the Java interface much smaller, as we don't have to add lots of interface data structures, or re-document well-known methods like constructors, finalize(), close(), flush(), etc. However, no efficiency is sacrificed by this approach: indeed, some operations, like the captureTo() methods, are more efficient than they would be if the underyling 'C' methods were mapped directly.

Unix-compatible Functions

These functions are part of the libpcap library, and therefore work both on Windows and on Unix-compatible systems.
pcap_handler
See PacketDispatcher.addPacketListener(net.sourceforge.jpcap.capture.PacketListener), PacketDispatcher.addRawPacketListener(net.sourceforge.jpcap.capture.RawPacketListener).
pcap_open_live()
PacketCapture.open().
pcap_open_dead()
Not supported: not required as a public method; called internally as required.
pcap_open_offline()
PacketCapture.openOffline().
pcap_dump_open()
PacketCapture.getOutputStream(File).
pcap_setnonblock(), pcap_getnonblock()
PacketCapture.configureBlocking(boolean), PacketCapture.isBlocking().
pcap_findalldevs()
PacketCapture.lookupDevices(), PacketCapture.lookupCaptureDevices().
pcap_freealldevs()
Automatic.
pcap_lookupdev()
The purpose of this function is met by PacketCapture.findDevice(), PacketCapture.findCaptureDevice(), JWinPcap.findCaptureDevice().
However, pcap_lookupdev() doesn't work correctly on Win32 platforms, so it is not used. Instead, it is simulated, on all platforms, by returning the first device returned by pcap_findalldevs() that is 'up' and isn't a loop-back. That's what pcap_lookupdev() is supposed to do, but it doesn't.
pcap_lookupnet()
This API is used indirectly by the deprecated methods PacketCapture.getNetmask() and PacketCapture.getNetwork().
However the pcap_lookupnet() method is obsolete, as it can't handle devices with more than one IP address, or IPv6 addresses; and furthermore the corresponding Java methods have unresolved word-order issues on some platforms.
The purpose of this method is correctly and completely implemented by CaptureDevice.
pcap_dispatch(), pcap_loop()
PacketCapture.capture(), PacketCapture.captureTo(), PacketCapture.LoopMode, PacketCapture.getLoopMode(), PacketCapture.setLoopMode().
pcap_next()
Not mapped, as there is no way to determine whether an error occurred, but see next item.
pcap_next_ex()
PacketCapture.captureNext(), PacketInputStream.readPacket().
pcap_breakloop()
PacketCapture.endCapture().
pcap_sendpacket(), pcap_inject()
PacketOutputStream.writePacket(net.sourceforge.jpcap.net.Packet)
pcap_dump()
PacketCapture.getOutputStream(File), PacketCapture.captureTo().
pcap_dump_ftell()
PacketOutputStream.getFilePointer().
pcap_compile(), pcap_freecode()
PacketCapture.compileFilter(java.lang.String, boolean), CompiledFilter.finalize().
pcap_compile_nopcap()
Unused; redundant.
pcap_setfilter()
PacketCapture.setFilter().
pcap_datalink()
PacketCapture.getLinkLayerType().
pcap_list_datalinks()
PacketCapture.getLinkLayerTypes().
pcap_set_datalink()
PacketCapture.setLinkLayerType(int).
pcap_datalink_val_to_name()
PacketCapture.getLinkLayerName().
pcap_datalink_val_to_description()
PacketCapture.getLinkLayerDescription().
pcap_snapshot()
This function is not used, but its purpose is met by PacketCapture.getSnapshotLength(): the data is saved and returned at the Java level.
pcap_is_swapped(), pcap_major_version(), pcap_minor_version()
Not supported: can't see the point.
pcap_file(), pcap_dump_file()
Not supported: no possible use in Java..
pcap_stats()
PacketCapture.getStatistics().
pcap_perror(), pcap_geterr(), pcap_strerror()
These are used automatically when throwing exceptions.
pcap_lib_version()
PacketCapture.getLibVersion().
pcap_close()
PacketCapture.close().
pcap_dump_flush()
PacketOutputStream.flush().
pcap_dump_close()
PacketOutputStream.close().

WinPcap Windows-specific Extensions

The functions in this section extend libpcap to offer advanced functionalities (like remote packet capture, packet buffer size variation or high-precision packet injection). Howerver, at the moment they can be used only in Windows.
pcap_get_air_pcap_handle()
Not supported: no real point without the extra product it requires.
pcap_offline_filter()
JWinPcap.isFilteredOffline().
pcap_live_dump(), pcap_live_dump_ended()
As these functions '[do] not work in current version of WinPcap' they are not used, but their purpose is met via PacketCapture.captureTo(), and not just on Windows platforms.
pcap_stats_ex()
PacketCapture.getStatistics().
pcap_setbuff()
JWinPcap.setBufferSize(int).
We've also provided JWinPcap.getBufferSize(), which is missing from the WinPcap API, but by knowing it is initially 1 megabyte and tracking changes we can implement it at the Java level.
pcap_setmode()
JWinPcap.CaptureMode, JWinPcap.setCaptureMode(), StatisticsListener, StatisticsEvent, JWinPcap.addStatisticsListener(), JWinPcap.removeStatisticsListener().
pcap_setmintocopy()
JWinPcap.setMinimumKernelCopy(int)
Note that the Winpcap documentation of this function is incorrect: it defines the minimum amount of data to copy from the kernel. Note also that, having discovered the initial value from the WinPcap authors, we have also been able to implement a JWinPcap.getMinimumKernelCopy() method, as per JWinPcap.getBufferSize() above.
pcap_getevent()
Not supported: the HANDLE has no possible use in Java (e.g. it can't be integrated with Selector).
pcap_sendqueue_alloc(), pcap_sendqueue_destroy(), pcap_sendqueue_queue(), pcap_sendqueue_transmit()
Send queues are supported as buffered PacketOutputStreams, without having to define any new API methods. Specifically, these pcap_sendqueue_*() methods are mapped to the PacketOutputStream constructor, PacketOutputStream.close(), PacketOutputStream.writePacket(net.sourceforge.jpcap.net.Packet), PacketOutputStream.flush(), respectively, when called on a PacketOutputStream obtained from JWinPcap.getOutputStream(). Note: when a Winpcap send-queue has been transmitted it cannot be reused for further queueing; when this happens in JWinPcap, a new send-queue is constructed automatically if necessary. Send queues are automatically destroyed on closure of the stream, or via garbage collection.
pcap_findalldevs_ex()
JWinPcap.lookupCaptureDevices().
pcap_createsrcstr(), pcap_parsesrcstr()
These are not supported in the Java API, where they would be redundant: use URI
pcap_open()
JWinPcap constructors, JWinPcap.open(), JWinPcap.openOffline().
pcap_setsampling()
JWinPcap.SamplingMethod, JWinPcap.setSamplingMethod().
pcap_remoteact_accept(), pcap_remoteact_close(), pcap_remoteact_cleanup(), pcap_remoteact_list()
Not supported.


Copyright © Patrick Charles & Jonas Lehmann, 2001; Esmond Pitt, 2008.