Module org.jnetpcap

Package org.jnetpcap

Class Pcap1_0

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

org.jnetpcap.Pcap0_9

org.jnetpcap.Pcap1_0

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

Pcap1_2

public sealed class Pcap1_0
extends Pcap0_9
permits Pcap1_2

Pcap1_0 relies on preview features of the Java platform:

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

Programs can only use Pcap1_0 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 1.0

Author:

Sly Technologies Inc, repos@slytechs.com, mark

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	activate()	Activate.
final boolean	canSetRfmon()	Can set rfmon.
static Pcap1_0	create(String device)	Create a live capture handle.
final PcapDlt	dataLinkExt()	Data link ext.
static void	init(int opts)	Initialize the native libpcap library.
static boolean	isSupported()	Checks if the Pcap subclass at a specific libpcap API version is natively supported.
static boolean	offlineFilter(BpFilter bpFilter, MemorySegmentPREVIEW pktHdr, MemorySegmentPREVIEW pktData)	Check whether a filter matches a packet.
static Pcap1_0	openDead(PcapDlt linktype, int snaplen)	Open a fake pcap_t for compiling filters or opening a capture for output.
static Pcap1_0	openLive(String device, int snaplen, boolean promisc, long timeout, TimeUnit unit)	Open a device for capturing.
static Pcap1_0	openOffline(String fname)	Open a saved capture file for reading.
final Pcap1_0	setBufferSize(int bufferSize)	Sets the buffer size for a not-yet- activated capture handle.
final Pcap1_0	setPromisc(boolean b)	Sets the promisc.
final Pcap1_0	setPromisc(int enable)	Set promiscuous mode for a not-yet-activated capture handle.
final Pcap1_0	setRfmon(boolean enableRfmon)	Sets the rfmon.
final Pcap1_0	setRfmon(int enableRfmon)	Set monitor mode for a not-yet-activated capture handle.
final Pcap1_0	setSnaplen(int snaplen)	Sets the snaplen.
final Pcap1_0	setTimeout(int timeout)	Sets the timeout.
static String	statusToStr(int error)	Convert an error full value to a string.

Methods inherited from class org.jnetpcap.Pcap0_9

inject, setDirection

Methods inherited from class org.jnetpcap.Pcap0_8

breakloop, datalinkNameToVal, dataLinkValToDescription, dataLinkValToName, libVersion, listDataLinks, nextEx, sendPacket, setDatalink

Methods inherited from class org.jnetpcap.Pcap0_7

findAllDevs, getNonBlock, setNonBlock

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, geterr, isInitialized, isSwapped, lookupDev, lookupNet, loop, loop, loop, loop, majorVersion, minorVersion, next, perror, setFilter, setUncaughtExceptionHandler, snapshot, stats, strerror

Methods inherited from class org.jnetpcap.Pcap

checkPcapVersion, compile, create, datalinkValToDescription, datalinkValToName, findAllDevsEx, getName, getPcapHeaderABI, getTstampPrecision, init, inject, inject, inject, listTstampTypes, loadNativePcapLibrary, lookupNet, openDeadWithTstampPrecision, openLive, openOffline, order, sendPacket, sendPacket, sendPacket, setDatalink, setDatalink, setDirection, setDirection, setFilter, setImmediateMode, setTstampPrecision, setTstampType, setUncaughtExceptionHandler, statusToStr, toString

Methods inherited from class java.lang.Object

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

Method Details

create

public static Pcap1_0 create(String device)
                      throws PcapException

Create a live capture handle. create is used to create a packet capture handle to look at packets on the network. source is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a source argument of "any" or NULL can be used to capture packets from all interfaces. The returned handle must be activated with pcap_activate() before pack' ets can be captured with it; options for the capture, such as promiscu' ous mode, can be set on the handle before activating it.

Parameters:

device - a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a source argument of "any" or NULL can be used to capture packets from all interfaces.

Returns:

a new pcap object that needs to be activated using activate() call

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

init

public static void init(int opts)
                 throws PcapException

Initialize the native libpcap library.

Used to initialize the Packet Capture library. opts specifies options for the library; currently, the options are:

PcapConstants.PCAP_CHAR_ENC_LOCAL

Treat all strings supplied as arguments, and return all strings to the caller, as being in the local character encoding.

PcapConstants.PCAP_CHAR_ENC_UTF_8

Treat all strings supplied as arguments, and return all strings to the caller, as being in UTF-8.

On UNIX-like systems, the local character encoding is assumed to be UTF-8, so no character encoding transformations are done.

On Windows, the local character encoding is the local ANSI full page.

If init(int) is not called, strings are treated as being in the local ANSI full page on Windows, Pcap0_4.lookupDev() will succeed if there is a device on which to capture, and create(String) makes an attempt to check whether the string passed as an argument is a UTF-16LE string - note that this attempt is unsafe, as it may run past the end of the string - to handle pcap_lookupdev() returning a UTF-16LE string. Programs that don't call init(int) should, on Windows, call native pcap_wsockinit() to initialize Winsock; this is not necessary if init(int) is called, as init(int) will initialize Winsock itself on Windows.

Parameters:

opts - Pcap initialization option flags

Throws:

PcapException - the pcap exception

Since:

libpcap 1.9

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)

offlineFilter

public static boolean offlineFilter(BpFilter bpFilter,
 MemorySegmentPREVIEW pktHdr,
 MemorySegmentPREVIEW pktData)

Check whether a filter matches a packet.

checks whether a filter matches a packet. fp is a pointer to a bpf_program struct, usually the result of a call to pcap_compile(3PCAP). h points to the pcap_pkthdr structure for the packet, and pkt points to the data in the packet.

Parameters:

bpFilter - the BPF program or filter program

pktHdr - the packet header

pktData - the packet data

Returns:

true, if filter matched packet otherwise false

Since:

libpcap 1.0

openDead

public static Pcap1_0 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 Pcap1_0 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 Pcap1_0 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

statusToStr

public static String statusToStr(int error)

Convert an error full value to a string.

Parameters:

error - the error

Returns:

the error string for the given full

Since:

libpcap 1.0

activate

public void activate()
              throws PcapActivatedException,
PcapException

Activate.

Overrides:

activate in class Pcap

Throws:

PcapActivatedException - the pcap activated exception

PcapException - the pcap exception

See Also:

• Pcap.activate()

canSetRfmon

public final boolean canSetRfmon()
                          throws PcapException

Can set rfmon.

Overrides:

canSetRfmon in class Pcap

Returns:

true, if successful

Throws:

PcapException - the pcap exception

See Also:

• Pcap.canSetRfmon()

dataLinkExt

public final PcapDlt dataLinkExt()
                          throws PcapException

Data link ext.

Overrides:

dataLinkExt in class Pcap

Returns:

the pcap dlt

Throws:

PcapException - the pcap exception

See Also:

• Pcap.dataLinkExt()

setBufferSize

public final Pcap1_0 setBufferSize(int bufferSize)
                            throws PcapException

Description copied from class: Pcap

Sets the buffer size for a not-yet- activated capture handle.

sets the buffer size that will be used on a capture handle when the handle is activated to buffer_size, which is in units of bytes

Overrides:

setBufferSize in class Pcap

Parameters:

bufferSize - the buffer size in units of bytes

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setBufferSize(int)

setPromisc

public final Pcap1_0 setPromisc(boolean b)
                         throws PcapException

Sets the promisc.

Overrides:

setPromisc in class Pcap

Parameters:

b - the b

Returns:

the pcap 1 0

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setPromisc(boolean)

setPromisc

public final Pcap1_0 setPromisc(int enable)
                         throws PcapException

Set promiscuous mode for a not-yet-activated capture handle.

pcap_set_promisc() sets whether promiscuous mode should be set on a capture handle when the handle is activated. If promisc is non-zero, promiscuous mode will be set, otherwise it will not be set.

Parameters:

enable - if true enable promiscous mode, otherwise disable it

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

setRfmon

public final Pcap1_0 setRfmon(boolean enableRfmon)
                       throws PcapException

Sets the rfmon.

Overrides:

setRfmon in class Pcap

Parameters:

enableRfmon - the enable rfmon

Returns:

the pcap 1 0

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setRfmon(boolean)

setRfmon

public final Pcap1_0 setRfmon(int enableRfmon)
                       throws PcapException

Set monitor mode for a not-yet-activated capture handle.

Sets whether monitor mode should be set on a capture handle when the handle is activated. If rfmon is true, monitor mode will be set, otherwise it will not be set.

Parameters:

enableRfmon - the enable rfmon

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

setSnaplen

public final Pcap1_0 setSnaplen(int snaplen)
                         throws PcapException

Sets the snaplen.

Overrides:

setSnaplen in class Pcap

Parameters:

snaplen - the snaplen

Returns:

the pcap 1 0

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setSnaplen(int)

setTimeout

public final Pcap1_0 setTimeout(int timeout)
                         throws PcapException

Sets the timeout.

Overrides:

setTimeout in class Pcap

Parameters:

timeout - the timeout

Returns:

the pcap 1 0

Throws:

PcapException - the pcap exception

See Also:

• Pcap.setTimeout(int)