jNetPcap version 1.0 Production
Introduction
See:
Description
Packages |
org.jnetpcap |
Core libpcap functionality available on all platforms. |
org.jnetpcap.winpcap |
WinPcap extensions to libpcap avialable on a limited set of
platforms. |
Introduction
jNetPcap is a java wrapper around Libpcap and WinPcap native
libraries found on various unix and windows platforms. jNetPcap exposes
the functionality as a java programming interface (API) which this
documentation describes.
Feature highlights:
- Follows native Libpcap programming model. This makes
learning jNetPcap API easy.
- No packet buffer copies between Libpcap and java
space. Existing native in-memory buffer is wrapped inside a
java.nio.ByteBuffer
object.
- Low level and efficient JNI implementation.
- Provides some very low level functions previously not
available in Java space. i.e.
setBuffer
for changing
buffer size and others.
Project website and the native Libpcap connection
Since jNetPcap is very closely mapped to native Libpcap
library functions, users are encouraged to read libpcap documentation at
libpcap website
(former http://tcpdump.org). You can visit jNetPcap project
website for for more information and a user guide with tutorials at http://jnetpcap.sf.net .
About Libpcap native library
Pcap is an application programming interface for packet
capturing. The implementation of pcap for Unix-like systems is known as
libpcap; the Windows port of libpcap is called WinPcap. libpcap and
WinPcap may be used by a program to capture packets travelling over a
network and, in newer versions, to transmit packets on a network at the
link layer, as well as to get a list of network interfaces that can be
used with libpcap or WinPcap. libpcap and WinPcap are the packet capture
and filtering engines of many open source and commercial network tools,
including protocol analyzers, network monitors, network intrusion
detection systems, packet sniffers, traffic generators and network
testers. The pcap API is designed for use from C and C++, so, for other
languages such as scripting languages, Java, and .NET languages, a
wrapper is generally used. (Credit: wikipedia.org)
About WinPcap windows libpcap implementation
WinPcap WinPcap consists of:
- drivers for Windows 95/98/Me, and for the Windows NT family
(Windows NT 4.0, Windows 2000, Windows XP, Windows Server 2003, Windows
Vista, etc.), that use NDIS to read packets directly from a network
adapter
- implementations of a lower-level library for those OSes, to
communicate with those drivers
- a port of libpcap that uses the API offered by the low-level
library implementations. It was originally created at the Politecnico
di Torino. Now it's maintained by CACE Technologies, a company created
by some of the WinPcap developers.
(
Credit: wikipedia.org
)
About jNetPcap a java wrapper
jNetPcap
is a java wrapper based on both libpcap and WinPcap. jNetPcap's API
provides core implementation based on unix libpcap API library (
org.jnetpcap
) while also providing the WinPcap extra functionality as an extension (
org.jnetpcap.winpcap
). The main classes which implement libpcap and WinPcap functinality
are:
org.jnetpcap.Pcap
class - core libpcap methods
available on all platforms
org.jnetpcap.winpcap.WinPcap
class - extensions
based on WinPcap library typically only available on windows based
system
The core libpcap implementation of jNetPcap, provides methods to do the
following functions
- Find a complete list of network interfaces the system has
- open either a network interface or a PCAP capture file for
reading packets
- apply a packet filter
- dump packets into a PCAP capture file
- transmit raw link layer packets over a network interface
- gather statistics on network interface counters
About jNetPcap's WinPcap extension
WinPcap library from (
http://winpcap.org), provides support for all of the core libpcap functions. It also
provides numerous functions that are not part of the core libpcap
functionality and are only available on platforms that support WinPcap.
These extra functions greatly enhance libpcap calls, and generally don't
provide features not found in the core. They simply provide enhanced
versions of the functions that are more efficient or provide greater
control over lets say the behaviour of the NPF driver within a windows
kernel. This is great news for windows platforms.
Checking for WinPcap extension support
Since java can be run on nearly any platform and WinPcap extensions are
only available on windows platforms, the user must check first if the
extension is available before using it. The check is done using a static
method call
WinPcap.isSupported
which will return a boolean value. Returned value of
true
means that the extension is supported otherwise
false
. WinPcap extension can not be used on a platform that does not support
the extension. Any method used with
WinPcap
on an unsupported platform, will throw an immediate
PcapExtensionNotAvailableException
, to indicate that its more then just this one particular operation that
is disabled. Therefore it is very important to always do a check first
before relying on an extension.
Other extensions?
Currently no other extensions are supported, but can easily be added
once suitable candidates are found such as (AirPcap from
http://cacetech.com), as long licensing terms permit it.
Java requirements
jNetPcap
Requires Java JRE 1.5. It also requires the binary WinPcap package to be
installed on the system (downloadable from
WinPcap website
.) jUnit tests are distributed in source form found in the
tests/java
directory. No compiled classes are supplied of jUnit tests with the
binary release. Any
jUnit library
is sufficient to compile and run all jUnit test cases. Build environment
requires ANT, ANT's contrib
cpptasks
, and a C++ compiler. Currently jNetPcap compiles using
MinGW
gcc compiler and environment on win32 platform and under regular gnu gcc
on linux. No
Makefiles
are used nor required.