Module org.jnetpcap

Package org.jnetpcap

Class Pcap0_4

java.lang.Object

org.jnetpcap.Pcap

org.jnetpcap.Pcap0_4

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

Pcap0_5

public sealed class Pcap0_4
extends Pcap
permits Pcap0_5

Pcap0_4 relies on preview features of the Java platform:

• Pcap0_4 refers to one or more preview APIs: MemorySegment.

Programs can only use Pcap0_4 when preview features are enabled.

Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.

Provides Pcap API method calls for up to libpcap version 0.4

Author:

Sly Technologies, repos@slytechs.com

Nested Class Summary

Nested classes/interfaces inherited from class org.jnetpcap.Pcap

Pcap.LibraryPolicy, Pcap.Linux, Pcap.Unix

Field Summary

Fields inherited from class org.jnetpcap.Pcap

VERSION

Method Summary

Modifier and Type	Method	Description
void	close()	Close.
final BpFilter	compile(String str, boolean optimize, int netmask)	Compile.
final PcapDlt	datalink()	Datalink.
final int	datalinkGetAsInt()	Get the link-layer header type.
final int	dispatch(int count, PcapDumper pcapDumper)	Dispatch.
int	dispatch(int count, PcapHandler.NativeCallback handler, MemorySegmentPREVIEW user)	Process packets from a live capture or savefile and dispatch using low level callback.
final <U> int	dispatch(int count, PcapHandler.OfArray<U> handler, U user)	Dispatch.
<U> int	dispatch(int count, PcapHandler.OfMemorySegment<U> handler, U user)	Dispatch.
final PcapDumper	dumpOpen(String fname)	Dump open.
final MemorySegmentPREVIEW	file()	Get the OS standard I/O stream for a savefile being read.
final int	fileno()	Get the file descriptor for a live capture.
final String	geterr()	Gets the err.
static boolean	isInitialized()	Checks if this is a Windows based platform.
static boolean	isSupported()	Checks if the Pcap subclass at a specific libpcap API version is natively supported.
final boolean	isSwapped()	Checks if is swapped.
static String	lookupDev()	Find the default device on which to capture.
static NetIp4Address	lookupNet(String device)	Find the IPv4 network number and netmask for a device.
final int	loop(int count, PcapDumper pcapDumper)	Loop.
int	loop(int count, PcapHandler.NativeCallback handler, MemorySegmentPREVIEW user)	Process packets from a live capture or savefile and dispatch using low level callback.
<U> int	loop(int count, PcapHandler.OfArray<U> handler, U user)	Loop.
<U> int	loop(int count, PcapHandler.OfMemorySegment<U> handler, U user)	Process packets from a live capture or savefile and dispatch directly to handler.
final int	majorVersion()	Major version.
final int	minorVersion()	Minor version.
PcapPacketRefPREVIEW	next()	Next.
static Pcap0_4	openLive(String device, int snaplen, boolean promisc, long timeout, TimeUnit unit)	Open a device for capturing.
static Pcap0_4	openOffline(String fname)	Open a saved capture file for reading.
final Pcap0_4	perror(String prefix)	Perror.
final Pcap0_4	setFilter(BpFilter bpfProgram)	Sets the filter.
Pcap	setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler exceptionHandler)	Sets the uncaught exception handler for loop(int, org.jnetpcap.PcapDumper) and dispatch(int, org.jnetpcap.PcapHandler.OfMemorySegment<U>, U) methods.
final int	snapshot()	Snapshot.
final PcapStat	stats()	Stats.
static String	strerror(int code)	Convert an error full value to a string.

Methods inherited from class org.jnetpcap.Pcap

activate, breakloop, canSetRfmon, checkPcapVersion, compile, compileNoPcap, create, create, dataLinkExt, datalinkNameToVal, datalinkValToDescription, datalinkValToName, findAllDevs, findAllDevsEx, getName, getNonBlock, getPcapHeaderABI, getTstampPrecision, init, init, inject, inject, inject, inject, libVersion, listDataLinks, listTstampTypes, loadNativePcapLibrary, lookupNet, nextEx, offlineFilter, openDead, openDeadWithTstampPrecision, openLive, openOffline, order, sendPacket, sendPacket, sendPacket, sendPacket, setBufferSize, setDatalink, setDatalink, setDatalink, setDirection, setDirection, setDirection, setFilter, setImmediateMode, setNonBlock, setPromisc, setRfmon, setSnaplen, setTimeout, setTstampPrecision, setTstampType, setUncaughtExceptionHandler, statusToStr, statusToStr, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

isInitialized

public static boolean isInitialized()

Checks if this is a Windows based platform.

Returns:

true, if is runtime is on windows

isSupported

public static boolean isSupported()

Checks if the Pcap subclass at a specific libpcap API version is natively supported. This is a safe method to use anytime on any platform, weather native library is present or not.

For example, Pcap1_0.isSupported() will accurately ascertain if libpcap API version 1.0 level calls are supported by the system runtime. Also a call such as WinPcap.isSupported() will determine if WinPcap related calls, ie. native WinPcap 4.1.3 or less, are supported and by extension if this is a Microsoft Windows platform.

Due to libpcap API versioning, it is safe to assume that if Pcap1_10.isSupported() returns true, that at least libpcap API version 1.0 is installed on this platform, and that all lower version calls such as libpcap 0.8 and 0.9 are available as well. The subclass hierarchy of jNetPcap module reflects the versioning of libpcap and its derivatives and the public releases of the native libraries. For example Npcap class extends WinPcap class because Npcap project took over the support for WinPcap where it left off.

Implementation notes: The check is performed by verifying that certain, subclass specific native symbols were linked with Pcap full which was introduced at a specific libpcap or related API levels.

Returns:

true, if pcap is supported up to this specific version level, otherwise false

See Also:

• Pcap.LibraryPolicy.setDefault(LibraryPolicy)

lookupDev

public static String lookupDev()
                        throws PcapException

Find the default device on which to capture.

Returns:

the string

Throws:

PcapException - the pcap exception

lookupNet

public static NetIp4Address lookupNet(String device)
                               throws PcapException

Find the IPv4 network number and netmask for a device. pcap_lookupnet() is used to determine the IPv4 network number and mask associated with the network device device. Both netp and maskp are bpf_u_int32 pointers.

Parameters:

device - the network device name

Returns:

A netmasked IPv4 address

Throws:

PcapException - any LibpcapApi errors

Since:

libpcap 0.4

openLive

public static Pcap0_4 openLive(String device,
 int snaplen,
 boolean promisc,
 long timeout,
 TimeUnit unit)
                        throws PcapException

Open a device for capturing.

openLive is used to obtain a packet capture handle to look at packets on the network. device is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a device argument of "any" or NULL can be used to capture packets from all interfaces.

Parameters:

device - the device name

snaplen - specifies the snapshot length to be set on the handle

promisc - specifies whether the interface is to be put into promiscuous mode. If promisc is non-zero, promiscuous mode will be set, otherwise it will not be set

timeout - the packet buffer timeout, as a non-negative value, in units

unit - time timeout unit

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

openOffline

public static Pcap0_4 openOffline(String fname)
                           throws PcapException

Open a saved capture file for reading.

pcap_open_offline() and pcap_open_offline_with_tstamp_precision() are called to open a ``savefile'' for reading.

Parameters:

fname - specifies the name of the file to open. The file can have the pcap file format as described in pcap-savefile(5), which is the file format used by, among other programs, tcpdump(1) and tcpslice(1), or can have the pcapng file format, although not all pcapng files can be read

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

strerror

public static String strerror(int code)

Convert an error full value to a string.

Parameters:

code - the code

Returns:

the error string for the given full

close

public void close()

Close.

Specified by:

close in interface AutoCloseable

Overrides:

close in class Pcap

See Also:

• Pcap.close()

compile

public final BpFilter compile(String str,
 boolean optimize,
 int netmask)
                       throws PcapException

Compile.

Overrides:

compile in class Pcap

Parameters:

str - the str

optimize - the optimize

netmask - the netmask

Returns:

the bp filter

Throws:

PcapException - the pcap exception

See Also:

• Pcap.compile(java.lang.String, boolean, int)

datalink

public final PcapDlt datalink()
                       throws PcapException

Datalink.

Overrides:

datalink in class Pcap

Returns:

the pcap dlt

Throws:

PcapException - the pcap exception

See Also:

• Pcap.datalink()

datalinkGetAsInt

public final int datalinkGetAsInt()
                           throws PcapException

Get the link-layer header type.

It must not be called on a pcap descriptor created by pcap_create(3PCAP) that has not yet been activated by pcap_activate.

https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values.

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Returns:

link-layer header type

Throws:

PcapException - any pcap errors

Since:

libpcap 0.4

dispatch

public <U> int dispatch(int count,
 PcapHandler.OfMemorySegment<U> handler,
 U user)
                 throws PcapException

Dispatch.

Overrides:

dispatch in class Pcap

Type Parameters:

U - the generic type

Parameters:

count - the count

handler - the handler

user - the user

Returns:

the int

Throws:

PcapException - the pcap exception

See Also:

• Pcap.dispatch(int, org.jnetpcap.PcapHandler.OfMemorySegment, java.lang.Object)

dispatch

public final int dispatch(int count,
 PcapDumper pcapDumper)

Dispatch.

Overrides:

dispatch in class Pcap

Parameters:

count - the count

pcapDumper - the pcap dumper

Returns:

the int

See Also:

• Pcap.dispatch(int, org.jnetpcap.PcapDumper)

dispatch

public int dispatch(int count,
 PcapHandler.NativeCallback handler,
 MemorySegmentPREVIEW user)

Description copied from class: Pcap

Process packets from a live capture or savefile and dispatch using low level callback. The native callback is low level, and is only capable of passing native user objects and not compatible with java user objects.

Processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a ``savefile''.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

Callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Overrides:

dispatch in class Pcap

Parameters:

count - maximum number of packets to process before returning

handler - the handler

user - TODO

Returns:

the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a packet buffer timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read) or if no more packets are available in a ``savefile.''

See Also:

• Pcap.dispatch(int, org.jnetpcap.PcapHandler.NativeCallback, java.lang.foreign.MemorySegment)^PREVIEW

dispatch

public final <U> int dispatch(int count,
 PcapHandler.OfArray<U> handler,
 U user)

Dispatch.

Overrides:

dispatch in class Pcap

Type Parameters:

U - the generic type

Parameters:

count - the count

handler - the handler

user - the user

Returns:

the int

See Also:

• Pcap.dispatch(int, org.jnetpcap.PcapHandler.OfArray, java.lang.Object)

dumpOpen

public final PcapDumper dumpOpen(String fname)
                          throws PcapException

Dump open.

Overrides:

dumpOpen in class Pcap

Parameters:

fname - the fname

Returns:

the pcap dumper

Throws:

PcapException - the pcap exception

See Also:

• Pcap.dumpOpen(java.lang.String)

file

public final MemorySegmentPREVIEW file()
                                throws PcapException

Get the OS standard I/O stream for a savefile being read.

Returns the OS's standard I/O stream of the ``savefile,'' if a ``savefile'' was opened with Pcap.openOffline(String), or NULL, if a network device was opened with Pcap.create(String) and Pcap.activate(), or with Pcap.openLive(String, int, boolean, long, TimeUnit). Note that the Packet Capture library is usually built with large file support, so the standard I/O stream of the ``savefile'' might refer to a file larger than 2 gigabytes; applications that use file()^PREVIEW should, if possible, use calls that support large files on the return value of file()^PREVIEW or the value returned by file()^PREVIEW when passed the return value of file()^PREVIEW.

Returns:

the OS standard I/O stream, only suitable with OS calls

Throws:

PcapException - the pcap exception

fileno

public final int fileno()
                 throws PcapException

Get the file descriptor for a live capture.

If Pcap refers to a network device that was opened for a live capture using a combination of Pcap.create(String) and Pcap.activate(), or using Pcap.openLive(String, int, boolean, long, TimeUnit) returns the OS file descriptor from which captured packets are read.

Returns:

the OS file descriptor, only suitable with OS calls

Throws:

PcapException - the pcap exception

geterr

public final String geterr()

Gets the err.

Overrides:

geterr in class Pcap

Returns:

the err

See Also:

• Pcap.geterr()

isSwapped

public final boolean isSwapped()
                        throws PcapException

Checks if is swapped.

Overrides:

isSwapped in class Pcap

Returns:

true, if is swapped

Throws:

PcapException - the pcap exception

See Also:

• Pcap.isSwapped()

loop

public final int loop(int count,
 PcapDumper pcapDumper)

Loop.

Overrides:

loop in class Pcap

Parameters:

count - the count

pcapDumper - the pcap dumper

Returns:

the int

See Also:

• Pcap.loop(int, org.jnetpcap.PcapDumper)

loop

public int loop(int count,
 PcapHandler.NativeCallback handler,
 MemorySegmentPREVIEW user)

Description copied from class: Pcap

Process packets from a live capture or savefile and dispatch using low level callback. The native callback is low level, and is only capable of passing native user objects and not compatible with java user objects.

pcap_loop() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or an error occurs. It does not return when live packet buffer timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are processed until another ending condition occurs.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Overrides:

loop in class Pcap

Parameters:

count - A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs

handler - the native handler which receives packets

user - native user object

Returns:

returns 0 if count is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns PCAP_ERROR_BREAK if the loop terminated due to a call to pcap_breakloop() before any packets were processed

See Also:

• Pcap.loop(int, org.jnetpcap.PcapHandler.NativeCallback, java.lang.foreign.MemorySegment)^PREVIEW

loop

public <U> int loop(int count,
 PcapHandler.OfArray<U> handler,
 U user)

Loop.

Overrides:

loop in class Pcap

Type Parameters:

U - the generic type

Parameters:

count - the count

handler - the handler

user - the user

Returns:

the int

See Also:

• Pcap.loop(int, org.jnetpcap.PcapHandler.OfArray, java.lang.Object)

loop

public <U> int loop(int count,
 PcapHandler.OfMemorySegment<U> handler,
 U user)

Description copied from class: Pcap

Process packets from a live capture or savefile and dispatch directly to handler. The scope of each memory segment dispatched by this call is only valid for the duration of the dispatch to handler. After that, the packet memory is reused by libpcap and its contents no longer valid if retained.

pcap_loop() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or an error occurs. It does not return when live packet buffer timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are processed until another ending condition occurs.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Overrides:

loop in class Pcap

Type Parameters:

U - the generic type

Parameters:

count - A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs

handler - array handler which will receive packets

user - the user opaque java object

Returns:

returns 0 if count is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns PCAP_ERROR_BREAK if the loop terminated due to a call to pcap_breakloop() before any packets were processed

See Also:

• Pcap.loop(int, org.jnetpcap.PcapHandler.OfMemorySegment, java.lang.Object)

majorVersion

public final int majorVersion()
                       throws PcapException

Major version.

Overrides:

majorVersion in class Pcap

Returns:

the int

Throws:

PcapException - the pcap exception

See Also:

• Pcap.majorVersion()

minorVersion

public final int minorVersion()
                       throws PcapException

Minor version.

Overrides:

minorVersion in class Pcap

Returns:

the int

Throws:

PcapException - the pcap exception

See Also:

• Pcap.minorVersion()

next

public PcapPacketRefPREVIEW next()
                          throws PcapException

Next.

Overrides:

next in class Pcap

Returns:

the pcap packet ref

Throws:

PcapException - the pcap exception

See Also:

• Pcap.next()

perror

public final Pcap0_4 perror(String prefix)

Perror.

Overrides:

perror in class Pcap

Parameters:

prefix - the prefix

Returns:

the pcap 0 4

See Also:

• Pcap.perror(java.lang.String)

setFilter

public final Pcap0_4 setFilter(BpFilter bpfProgram)
                        throws PcapException

Sets the filter.

Overrides:

setFilter in class Pcap

Parameters:

bpfProgram - the bpf program

Returns:

the pcap 0 4

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setFilter(org.jnetpcap.BpFilter)

snapshot

public final int snapshot()
                   throws PcapException

Snapshot.

Overrides:

snapshot in class Pcap

Returns:

the int

Throws:

PcapException - the pcap exception

See Also:

• Pcap.snapshot()

stats

public final PcapStat stats()
                     throws PcapException

Stats.

Overrides:

stats in class Pcap

Returns:

the pcap stat

Throws:

PcapException - the pcap exception

See Also:

• Pcap.stats()

setUncaughtExceptionHandler

public Pcap setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler exceptionHandler)

Sets the uncaught exception handler for loop(int, org.jnetpcap.PcapDumper) and dispatch(int, org.jnetpcap.PcapHandler.OfMemorySegment<U>, U) methods. Any exception thrown within the user callback methods, will be caught and sent to the specified user exception handler.

Overrides:

setUncaughtExceptionHandler in class Pcap

Parameters:

exceptionHandler - the exception handler

Returns:

this pcap