Module org.jnetpcap

Package org.jnetpcap

Class Pcap0_8

java.lang.Object

org.jnetpcap.Pcap

org.jnetpcap.Pcap0_4

org.jnetpcap.Pcap0_5

org.jnetpcap.Pcap0_6

org.jnetpcap.Pcap0_7

org.jnetpcap.Pcap0_8

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

Pcap0_9

public sealed class Pcap0_8
extends Pcap0_7
permits Pcap0_9

Provides Pcap API method calls for up to libpcap version 0.8

Author:

Sly Technologies Inc, repos@slytechs.com, mark

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	Pcap0_8.Unix0_8	Symbol container for lazy initialization.

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

Pcap0_4.PcapSupplier<T extends Pcap>

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

Pcap.LibraryPolicy, Pcap.Linux, Pcap.Unix

Field Summary

Fields inherited from class org.jnetpcap.Pcap0_4

dispatcher

Fields inherited from class org.jnetpcap.Pcap

closed, pcapHeaderABI, POINTER_TO_POINTER1, POINTER_TO_POINTER2, POINTER_TO_POINTER3, VERSION

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Pcap0_8(MemorySegment pcapHandle, String name, PcapHeaderABI abi)	Instantiates a new pcap 080.

Method Summary

Modifier and Type	Method	Description
final void	breakloop()	Breakloop.
static PcapDlt	datalinkNameToVal(String name)	Translates a link-layer header type name, which is a DLT_ name with the DLT_ removed, to the corresponding link-layer header type value.
static String	dataLinkValToDescription(PcapDlt pcapDlt)	Translates a link-layer header type value to a short description of that link-layer header type.
static String	dataLinkValToName(PcapDlt pcapDlt)	Translates a link-layer header type value to the corresponding link-layer header type name, which is the DLT_ name for the link-layer header type value with the DLT_ removed.
protected int	getSelectableFd()	Get a file descriptor on which a select() can be done for a live capture.
static boolean	isSupported()	Checks if the Pcap subclass at a specific libpcap API version is natively supported.
static String	libVersion()	Returns a string identifying the libpcap library, implementation information and version.
final List<PcapDlt>	listDataLinks()	List data links.
PcapPacketRef	nextEx()	Next ex.
static Pcap0_8	openDead(PcapDlt linktype, int snaplen)	Open a fake pcap_t for compiling filters or opening a capture for output.
static Pcap0_8	openLive(String device, int snaplen, boolean promisc, long timeout, TimeUnit unit)	Open a device for capturing.
static Pcap0_8	openOffline(String fname)	Open a saved capture file for reading.
void	sendPacket(MemorySegment packet, int length)	Send packet.
final Pcap0_8	setDatalink(int dlt)	Sets the datalink.

Methods inherited from class org.jnetpcap.Pcap0_7

findAllDevs, getNonBlock, setNonBlock

Methods inherited from class org.jnetpcap.Pcap0_6

openDead

Methods inherited from class org.jnetpcap.Pcap0_5

compileNoPcap

Methods inherited from class org.jnetpcap.Pcap0_4

close, compile, datalink, datalinkGetAsInt, dispatch, dispatch, dispatch, dispatch, dumpOpen, file, fileno, getDispatcher, geterr, isInitialized, isSwapped, lookupDev, lookupNet, loop, loop, loop, loop, majorVersion, minorVersion, next, openLive, openOffline, perror, setDispatcher, setFilter, setUncaughtExceptionHandler, snapshot, stats, strerror

Methods inherited from class org.jnetpcap.Pcap

activate, canSetRfmon, checkPcapVersion, compile, create, create, dataLinkExt, datalinkValToDescription, datalinkValToName, findAllDevsEx, getErrorString, getName, getPcapHandle, getPcapHeaderABI, getTstampPrecision, init, init, inject, inject, inject, inject, listAllPcapIf, listTstampTypes, loadNativePcapLibrary, lookupErrorString, lookupNet, newArena, offlineFilter, openDeadWithTstampPrecision, openLive, openLive, openOffline, order, sendPacket, sendPacket, sendPacket, setBufferSize, setDatalink, setDatalink, setDirection, setDirection, setDirection, setFilter, setImmediateMode, setPromisc, setRfmon, setSnaplen, setTimeout, setTstampPrecision, setTstampType, setUncaughtExceptionHandler, statusToStr, statusToStr, toString

Methods inherited from class java.lang.Object

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

Constructor Details

Pcap0_8

protected Pcap0_8(MemorySegment pcapHandle,
 String name,
 PcapHeaderABI abi)

Instantiates a new pcap 080.

Parameters:

pcapHandle - the pcap handle

name - the handle name

abi - the abi

Method Details

datalinkNameToVal

public static PcapDlt datalinkNameToVal(String name)

Translates a link-layer header type name, which is a DLT_ name with the DLT_ removed, to the corresponding link-layer header type value. The translation is case-insensitive.

Parameters:

name - link-layer header type name

Returns:

the pcap data link type

Since:

libpcap 0.8

dataLinkValToDescription

public static String dataLinkValToDescription(PcapDlt pcapDlt)

Translates a link-layer header type value to a short description of that link-layer header type. NULL is returned if the type value does not correspond to a known DLT_ value..

Parameters:

pcapDlt - link-layer header type

Returns:

short description of that link-layer header type

Since:

libpcap 0.8

dataLinkValToName

public static String dataLinkValToName(PcapDlt pcapDlt)

Translates a link-layer header type value to the corresponding link-layer header type name, which is the DLT_ name for the link-layer header type value with the DLT_ removed. NULL is returned if the type value does not correspond to a known DLT_ value..

Parameters:

pcapDlt - link-layer header type

Returns:

corresponding link-layer header type name

Since:

libpcap 0.8

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)

libVersion

public static String libVersion()

Returns a string identifying the libpcap library, implementation information and version.

Returns:

a descriptive library string

openDead

public static Pcap0_8 openDead(PcapDlt linktype,
 int snaplen)
                        throws PcapException

Open a fake pcap_t for compiling filters or opening a capture for output.

openDead(org.jnetpcap.constant.PcapDlt, int) and pcap_open_dead_with_tstamp_precision() are used for creating a pcap_t structure to use when calling the other functions in libpcap. It is typically used when just using libpcap for compiling BPF full; it can also be used if using pcap_dump_open(3PCAP), pcap_dump(3PCAP), and pcap_dump_close(3PCAP) to write a savefile if there is no pcap_t that supplies the packets to be written.

When pcap_open_dead_with_tstamp_precision(), is used to create a pcap_t for use with pcap_dump_open(), precision specifies the time stamp precision for packets; PCAP_TSTAMP_PRECISION_MICRO should be specified if the packets to be written have time stamps in seconds and microseconds, and PCAP_TSTAMP_PRECISION_NANO should be specified if the packets to be written have time stamps in seconds and nanoseconds. Its value does not affect pcap_compile(3PCAP).

Parameters:

linktype - specifies the link-layer type for the pcap handle

snaplen - specifies the snapshot length for the pcap handle

Returns:

A dead pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.6

openLive

public static Pcap0_8 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_8 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

breakloop

public final void breakloop()

Breakloop.

Overrides:

breakloop in class Pcap

See Also:

• Pcap.breakloop()

getSelectableFd

protected int getSelectableFd()
                       throws PcapException

Get a file descriptor on which a select() can be done for a live capture.

pcap_get_selectable_fd() returns, on UNIX, a file descriptor number for a file descriptor on which one can do a select(2), poll(2), epoll_wait(2), kevent(2), or other such call to wait for it to be possible to read packets without blocking, if such a descriptor exists, or -1, if no such descriptor exists. Some network devices opened with pcap_create(3PCAP) and pcap_activate(3PCAP), or with pcap_open_live(3PCAP), do not support those calls (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace DAG devices), so -1 is returned for those devices. In that case, those calls must be given a timeout less than or equal to the timeout returned by pcap_get_required_select_timeout(3PCAP) for the device for which pcap_get_selectable_fd() returned -1, the device must be put in non-blocking mode with a call to pcap_setnonblock(3PCAP), and an attempt must always be made to read packets from the device when the call returns. If pcap_get_required_select_timeout() returns NULL, it is not possible to wait for packets to arrive on the device in an event loop.

Note that a device on which a read can be done without blocking may, on some platforms, not have any packets to read if the packet buffer timeout has expired. A call to pcap_dispatch(3PCAP) or pcap_next_ex(3PCAP) will return 0 in this case, but will not block.

Note that in:

FreeBSD prior to FreeBSD 4.6;

NetBSD prior to NetBSD 3.0;

OpenBSD prior to OpenBSD 2.4;

Mac OS X prior to Mac OS X 10.7;

select(), poll(), and kevent() do not work correctly on BPF devices; pcap_get_selectable_fd() will return a file descriptor on most of those versions (the exceptions being FreeBSD 4.3 and 4.4), but a simple select(), poll(), or kevent() call will not indicate that the descriptor is readable until a full buffer's worth of packets is received, even if the packet timeout expires before then. To work around this, full that uses those calls to wait for packets to arrive must put the pcap_t in non-blocking mode, and must arrange that the call have a timeout less than or equal to the packet buffer timeout, and must try to read packets after that timeout expires, regardless of whether the call indicated that the file descriptor for the pcap_t is ready to be read or not. (That workaround will not work in FreeBSD 4.3 and later; however, in FreeBSD 4.6 and later, those calls work correctly on BPF devices, so the workaround isn't necessary, although it does no harm.)

Note also that poll() and kevent() doesn't work on character special files, including BPF devices, in Mac OS X 10.4 and 10.5, so, while select() can be used on the descriptor returned by pcap_get_selectable_fd(), poll() and kevent() cannot be used on it those versions of Mac OS X. poll(), but not kevent(), works on that descriptor in Mac OS X releases prior to 10.4; poll() and kevent() work on that descriptor in Mac OS X 10.6 and later.

pcap_get_selectable_fd() is not available on Windows.

Returns:

the selectable fd

Throws:

PcapException - the pcap exception

Since:

libpcap 1.8 (Unix only)

listDataLinks

public final List<PcapDlt> listDataLinks()
                                  throws PcapException

List data links.

Overrides:

listDataLinks in class Pcap

Returns:

the list

Throws:

PcapException - the pcap exception

See Also:

• Pcap.listDataLinks()

nextEx

public PcapPacketRef nextEx()
                     throws PcapException,
TimeoutException

Next ex.

Overrides:

nextEx in class Pcap

Returns:

the pcap packet ref

Throws:

PcapException - the pcap exception

TimeoutException - the timeout exception

See Also:

• Pcap.nextEx()

sendPacket

public void sendPacket(MemorySegment packet,
 int length)
                throws PcapException

Send packet.

Overrides:

sendPacket in class Pcap

Parameters:

packet - the packet

length - the length

Throws:

PcapException - the pcap exception

See Also:

• Pcap.sendPacket(java.lang.foreign.MemorySegment, int)

setDatalink

public final Pcap0_8 setDatalink(int dlt)
                          throws PcapException

Sets the datalink.

Overrides:

setDatalink in class Pcap

Parameters:

dlt - the dlt

Returns:

the pcap 0 8

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setDatalink(int)