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

The {@link net.sourceforge.jpcap.capture.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 {@link net.sourceforge.jpcap.capture.PacketListener} or {@link net.sourceforge.jpcap.capture.RawPacketListener} and register with an instance of the capture system in order to receive packets.

The {@link net.sourceforge.jpcap.capture.JWinPcap} class encapsulates the WinPcap extension API.

Important note on snaplen

'snaplen is used only if you use a capture filter, as the snaplen feature is implemented as a filter. This is the standard behavior of snaplen on libpcap/winpcap. If you want to use snaplen and you don't need a filter, please compile an empty filter (i.e. the string "").' (Gianluca Varenni, Winpcap mailing list, 'Re: [Winpcap-users] snaplen in pcap_open_live', winpcap-users@winpcap.org, 19 September 2008).

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 {@link java.io.InputStream} and {@link java.io.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, {@link java.lang.Object#finalize() finalize()}, {@link java.io.Closeable#close close()}, {@link java.io.Flushable#flush flush()}, etc. However, no efficiency is sacrificed by this approach: indeed, some operations, like the {@link net.sourceforge.jpcap.capture.PacketCapture#captureTo 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 {@link net.sourceforge.jpcap.capture.PacketCapture#addPacketListener}, {@link net.sourceforge.jpcap.capture.PacketCapture#addRawPacketListener}.
pcap_open_live()
{@link net.sourceforge.jpcap.capture.PacketCapture#open PacketCapture.open()}.
pcap_open_dead()
Not supported: not required as a public method; called internally as required.
pcap_open_offline()
{@link net.sourceforge.jpcap.capture.PacketCapture#openOffline PacketCapture.openOffline()}.
pcap_dump_open()
{@link net.sourceforge.jpcap.capture.PacketCapture#getOutputStream(File)}.
pcap_setnonblock(), pcap_getnonblock()
{@link net.sourceforge.jpcap.capture.PacketCapture#configureBlocking}, {@link net.sourceforge.jpcap.capture.PacketCapture#isBlocking}.
pcap_findalldevs()
{@link net.sourceforge.jpcap.capture.PacketCapture#lookupDevices}, {@link net.sourceforge.jpcap.capture.PacketCapture#lookupCaptureDevices}.
pcap_freealldevs()
Automatic.
pcap_lookupdev()
The purpose of this function is met by {@link net.sourceforge.jpcap.capture.PacketCapture#findDevice}, {@link net.sourceforge.jpcap.capture.PacketCapture#findCaptureDevice}, {@link net.sourceforge.jpcap.capture.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 {@link net.sourceforge.jpcap.capture.PacketCapture#getNetmask PacketCapture.getNetmask()} and {@link net.sourceforge.jpcap.capture.PacketCapture#getNetwork 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 {@link net.sourceforge.jpcap.capture.CaptureDevice}.
pcap_dispatch(), pcap_loop()
{@link net.sourceforge.jpcap.capture.PacketCapture#capture PacketCapture.capture()}, {@link net.sourceforge.jpcap.capture.PacketCapture#captureTo PacketCapture.captureTo()}, {@link net.sourceforge.jpcap.capture.PacketCapture.LoopMode}, {@link net.sourceforge.jpcap.capture.PacketCapture#getLoopMode()}, {@link net.sourceforge.jpcap.capture.PacketCapture#setLoopMode PacketCapture.setLoopMode()}.
pcap_next()
Not mapped, as there is no way to determine whether an error occurred, but see next item.
pcap_next_ex()
{@link net.sourceforge.jpcap.capture.PacketCapture#captureNext}, {@link net.sourceforge.jpcap.capture.PacketInputStream#readPacket}.
pcap_breakloop()
{@link net.sourceforge.jpcap.capture.PacketCapture#endCapture()}.
pcap_sendpacket(), pcap_inject()
{@link net.sourceforge.jpcap.capture.PacketOutputStream#writePacket}
pcap_dump()
{@link net.sourceforge.jpcap.capture.PacketCapture#getOutputStream(File)}, {@link net.sourceforge.jpcap.capture.PacketCapture#captureTo PacketCapture.captureTo()}.
pcap_dump_ftell()
{@link net.sourceforge.jpcap.capture.PacketOutputStream#getFilePointer}.
pcap_compile(), pcap_freecode()
{@link net.sourceforge.jpcap.capture.PacketCapture#compileFilter}, {@link net.sourceforge.jpcap.capture.CompiledFilter#finalize}.
pcap_compile_nopcap()
Unused; redundant.
pcap_setfilter()
{@link net.sourceforge.jpcap.capture.PacketCapture#setFilter PacketCapture.setFilter()}.
pcap_datalink()
{@link net.sourceforge.jpcap.capture.PacketCapture#getLinkLayerType}.
pcap_list_datalinks()
{@link net.sourceforge.jpcap.capture.PacketCapture#getLinkLayerTypes}.
pcap_set_datalink()
{@link net.sourceforge.jpcap.capture.PacketCapture#setLinkLayerType}.
pcap_datalink_val_to_name()
{@link net.sourceforge.jpcap.capture.PacketCapture#getLinkLayerName}.
pcap_datalink_val_to_description()
{@link net.sourceforge.jpcap.capture.PacketCapture#getLinkLayerDescription}.
pcap_snapshot()
This function is not used, but its purpose is met by {@link net.sourceforge.jpcap.capture.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()
{@link net.sourceforge.jpcap.capture.PacketCapture#getStatistics}.
pcap_perror(), pcap_geterr(), pcap_strerror()
These are used automatically when throwing exceptions.
pcap_lib_version()
{@link net.sourceforge.jpcap.capture.PacketCapture#getLibVersion}.
pcap_close()
{@link net.sourceforge.jpcap.capture.PacketCapture#close()}.
pcap_dump_flush()
{@link net.sourceforge.jpcap.capture.PacketOutputStream#flush PacketOutputStream.flush()}.
pcap_dump_close()
{@link net.sourceforge.jpcap.capture.PacketOutputStream#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()
{@link net.sourceforge.jpcap.capture.JWinPcap#isFilteredOffline 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 {@link net.sourceforge.jpcap.capture.PacketCapture#captureTo PacketCapture.captureTo()}, and not just on Windows platforms.
pcap_stats_ex()
{@link net.sourceforge.jpcap.capture.PacketCapture#getStatistics}.
pcap_setbuff()
{@link net.sourceforge.jpcap.capture.JWinPcap#setBufferSize}.
We've also provided {@link net.sourceforge.jpcap.capture.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()
{@link net.sourceforge.jpcap.capture.JWinPcap.CaptureMode}, {@link net.sourceforge.jpcap.capture.JWinPcap#setCaptureMode JWinPcap.setCaptureMode()}, {@link net.sourceforge.jpcap.capture.StatisticsListener}, {@link net.sourceforge.jpcap.capture.StatisticsEvent}, {@link net.sourceforge.jpcap.capture.JWinPcap#addStatisticsListener JWinPcap.addStatisticsListener()}, {@link net.sourceforge.jpcap.capture.JWinPcap#removeStatisticsListener JWinPcap.removeStatisticsListener()}.
pcap_setmintocopy()
{@link net.sourceforge.jpcap.capture.JWinPcap#setMinimumKernelCopy}
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 {@link net.sourceforge.jpcap.capture.JWinPcap#getMinimumKernelCopy()} method, as per {@link net.sourceforge.jpcap.capture.JWinPcap#getBufferSize} above.
pcap_getevent()
Not supported: the HANDLE has no possible use in Java (e.g. it can't be integrated with {@link java.nio.channels.Selector}).
pcap_sendqueue_alloc(), pcap_sendqueue_destroy(), pcap_sendqueue_queue(), pcap_sendqueue_transmit()
Send queues are supported as buffered {@link net.sourceforge.jpcap.capture.PacketOutputStream PacketOutputStreams}, without having to define any new API methods. Specifically, these pcap_sendqueue_*() methods are mapped to the {@link net.sourceforge.jpcap.capture.PacketOutputStream} constructor, {@link net.sourceforge.jpcap.capture.PacketOutputStream#close PacketOutputStream.close()}, {@link net.sourceforge.jpcap.capture.PacketOutputStream#writePacket}, {@link net.sourceforge.jpcap.capture.PacketOutputStream#flush PacketOutputStream.flush()}, respectively, when called on a PacketOutputStream obtained from {@link net.sourceforge.jpcap.capture.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()
{@link net.sourceforge.jpcap.capture.JWinPcap#lookupCaptureDevices}.
pcap_createsrcstr(), pcap_parsesrcstr()
These are not supported in the Java API, where they would be redundant: use {@link java.net.URI}
pcap_open()
{@link net.sourceforge.jpcap.capture.JWinPcap} constructors, {@link net.sourceforge.jpcap.capture.JWinPcap#open JWinPcap.open()}, {@link net.sourceforge.jpcap.capture.JWinPcap#openOffline JWinPcap.openOffline()}.
pcap_setsampling()
{@link net.sourceforge.jpcap.capture.JWinPcap.SamplingMethod}, {@link net.sourceforge.jpcap.capture.JWinPcap#setSamplingMethod JWinPcap.setSamplingMethod()}.
pcap_remoteact_accept(), pcap_remoteact_close(), pcap_remoteact_cleanup(), pcap_remoteact_list()
Not supported.