|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jnetpcap.Pcap
org.jnetpcap.winpcap.WinPcap
public class WinPcap
Class peered with native pcap_t
structure providing WinPcap
specific extensions to libpcap library. To access WinPcap extensions, you
must use WinPcap class and its methods. WinPcap
class extends
Pcap class so you have all of the typeical Pcap
class
functionality. WinPcap provides many additional methods which are only
available on platforms what support WinPcap. First you must use static
WinPcap.isSupported()
method call which will return a boolean
that will indicate if WinPcap extensions are supported on this particular
platform. If you try and use any method in this class when WinPcap extensions
are not supported, another words WinPcap.isSupported()
returned false, every method in this calls will throw unchecked
. Of course,
PcapExtensionNotAvailableException
isSupported
call itself never throws an exception. So its safe
to use on any platform.
// Before using any WinPcap code if (WinPcap.isSupported() == false) { return; // Can't use WinPcap extensions }
WinPcap
the same way you would use
Pcap
class. WinPcap
class provides many
different static methods, and the same main three methods that
Pcap
does to open a capture session, plus one extra. They are:
Pcap.findAllDevs
which allows you to not only find network interfaces, but also PCAP files.
This can be done locally or remotely.
String source = "rpcap://"; List<PcapIf> alldevs = new ArrayList<PcapIf>(); int r = WinPcap.findAllDevsEx(source, auth, alldevs, errbuf); if (r != Pcap.OK) { fail(errbuf.toString()); return; } System.out.println("device list is " + alldevs);Now we have a list of PcapIf objects. You can use
PcapIf.getName()
which contains already properly formatted
name to be passed to WinPcap.open
call.
WinPcap pcap = WinPcap.openLive(device, snaplen, flags, timeout, errbuf); // Do something pcap.close();This is identical to
Pcap.openLive
method with the exception
that WinPcap
object is returned. WinPcap extends Pcap. Here is
the same example this time using WinPcap's source string code and
a bogus device name (you will need to substitute your own actual device
name):
String source = "rpcap://\\Device\\NPF_{BC81C4FC-242F-4F1C-9DAD-EA9523CC992D}"; int snaplen = 64 * 1024; int flags = Pcap.MODE_NON_PROMISCUOUS; int timeout = 1000; WinPcapRmtAuth auth = null; StringBuilder errbuf = new StringBuilder(); WinPcap pcap = WinPcap.open(source, snaplen, flags, timeout, auth, errbuf); if (pcap == null) { System.err.println(errbuf.toString()); return; } pcap.close(); }We use
open
method which takes a WinPcapRmtAuth
object. We could set username and password in it, but we chose the 'NULL'
authentication method. The remote server has to be configured with a '-n'
command line argument to access 'NULL' authentication.
Pcap
Field Summary | |
---|---|
static int |
MODE_CAPT
default capture mode |
static int |
MODE_MONITOR
monitor mode |
static int |
MODE_STAT
statistical mode |
static int |
OPENFLAG_DATATX_UDP
Defines if the data trasfer (in case of a remote capture) has to be done with UDP protocol and can only be used with WinPcap.open . |
static int |
OPENFLAG_MAX_RESPONSIVENESS
This flag configures the adapter for maximum responsiveness and can only be used with WinPcap.open . |
static int |
OPENFLAG_NOCAPTURE_LOCAL
Defines if the local adapter will capture its own generated traffic and can only be used with WinPcap.open . |
static int |
OPENFLAG_NOCAPTURE_RPCAP
Defines if the remote probe will capture its own generated traffic and can only be used with WinPcap.open . |
static int |
SRC_FILE
Used to create a source string using method createSrcStr , which will be used to open a local capture
file. |
static int |
SRC_IFLOCAL
Used to create a source string using method createSrcStr , which will be used to open a local network
interface. |
static int |
SRC_IFREMOTE
Used to create a source string using method createSrcStr ,which will be used to open a remote connection
(could be file, or network interface on remote system). |
static int |
TRANSMIT_SYNCH_ASAP
Flag used with sendQueueTransmit(WinPcapSendQueue, int) , to tell
kernel to send packets as fast as possible, without synchronizing with
packet timestamps found in headers. |
static int |
TRANSMIT_SYNCH_USE_TIMESTAMP
Flag used with sendQueueTransmit(WinPcapSendQueue, int) , to tell
kernel to send packets at the rate that is determined by the timestamp with
in the sendqueue. |
Fields inherited from class org.jnetpcap.Pcap |
---|
DISPATCH_BUFFER_FULL, JNETPCAP_LIBRARY_NAME, LOOP_INFINATE, LOOP_INTERRUPTED, MODE_BLOCKING, MODE_NON_BLOCKING, MODE_NON_PROMISCUOUS, MODE_PROMISCUOUS, NEXT_EX_EOF, NEXT_EX_NOT_OK, NEXT_EX_OK, NEXT_EX_TIMEDOUT, NOT_OK, OK |
Method Summary | |
---|---|
static int |
createSrcStr(java.lang.StringBuilder source,
int type,
java.lang.String host,
java.lang.String port,
java.lang.String name,
java.lang.StringBuilder errbuf)
Accept a set of strings (host name, port, ...), and it returns the complete source string according to the new format (e.g. |
static int |
findAllDevsEx(java.lang.String source,
WinPcapRmtAuth auth,
java.util.List<PcapIf> alldevs,
java.lang.StringBuilder errbuf)
Create a list of network devices that can be opened with pcap_open(). |
static boolean |
isSupported()
Checks if WinPcap extensions are available on this platform. |
int |
liveDump(java.lang.String fname,
int maxsize,
int maxpackets)
dumps the network traffic from an interface to a file. |
int |
liveDumpEnded(int sync)
Return the status of the kernel dump process, i.e. |
static int |
offlineFilter(PcapBpfProgram program,
PcapPktHdr header,
java.nio.ByteBuffer buf)
Returns if a given filter applies to an offline packet. |
static WinPcap |
open(java.lang.String source,
int snaplen,
int flags,
int timeout,
WinPcapRmtAuth auth,
java.lang.StringBuilder errbuf)
Open a generic source in order to capture/send (WinPcap only) traffic. |
static WinPcap |
openDead(int linktype,
int snaplen)
Create a pcap_t structure without starting a capture. |
static WinPcap |
openLive(java.lang.String device,
int snaplen,
int promisc,
int timeout,
java.lang.StringBuilder errbuf)
This method, overrides the generic libpcap based openLive
method, and allocates a peer pcap object that allows WinPcap extensions. |
static WinPcap |
openOffline(java.lang.String fname,
java.lang.StringBuilder errbuf)
Open a savefile in the tcpdump/libpcap format to read packets. |
static WinPcapSendQueue |
sendQueueAlloc(int size)
Allocate a send queue. |
static void |
sendQueueDestroy(WinPcapSendQueue queue)
Destroy a send queue. |
int |
sendQueueTransmit(WinPcapSendQueue queue,
int synch)
Send a queue of raw packets to the network. |
int |
setBuff(int dim)
Set the size of the kernel buffer associated with an adapter. |
int |
setMinToCopy(int size)
Set the minumum amount of data received by the kernel in a single call. |
int |
setMode(int mode)
Set the working mode of the interface p to mode. |
WinPcapSamp |
setSampling()
Define a sampling method for packet capture. |
WinPcapStat |
statsEx()
This method extends the Pcap.stats method and allows more
statistics to be returned. |
Methods inherited from class org.jnetpcap.Pcap |
---|
breakloop, checkIsActive, close, compile, compileNoPcap, datalink, datalinkNameToVal, datalinkValToDescription, datalinkValToName, dispatch, dumpOpen, finalize, findAllDevs, freeAllDevs, freecode, getErr, getNonBlock, inject, inject, inject, isInjectSupported, isSendPacketSupported, isSwapped, libVersion, lookupDev, lookupNet, loop, majorVersion, minorVersion, next, nextEx, sendPacket, sendPacket, sendPacket, setDatalink, setFilter, setNonBlock, snapshot, stats, toString |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int MODE_CAPT
public static final int MODE_STAT
public static final int MODE_MONITOR
public static final int TRANSMIT_SYNCH_ASAP
sendQueueTransmit(WinPcapSendQueue, int)
, to tell
kernel to send packets as fast as possible, without synchronizing with
packet timestamps found in headers.
public static final int TRANSMIT_SYNCH_USE_TIMESTAMP
sendQueueTransmit(WinPcapSendQueue, int)
, to tell
kernel to send packets at the rate that is determined by the timestamp with
in the sendqueue. The transmittion is synchronized with timestamps.
public static final int SRC_FILE
createSrcStr
, which will be used to open a local capture
file. Used with createSrcStr
for its type field. Used with
createSrcStr
for its type field.
public static final int SRC_IFLOCAL
createSrcStr
, which will be used to open a local network
interface. Used with createSrcStr
for its type field.
public static final int SRC_IFREMOTE
createSrcStr
,which will be used to open a remote connection
(could be file, or network interface on remote system). Used with
createSrcStr
for its type field.
public static final int OPENFLAG_DATATX_UDP
WinPcap.open
.
If it is '1' if you want a UDP data connection, '0' if you want a TCP data
connection; control connection is always TCP-based. A UDP connection is
much lighter, but it does not guarantee that all the captured packets
arrive to the client workstation. Moreover, it could be harmful in case of
network congestion. This flag is meaningless if the source is not a remote
interface. In that case, it is simply ignored.
public static final int OPENFLAG_NOCAPTURE_RPCAP
WinPcap.open
. In case the remote probe
uses the same interface to capture traffic and to send data back to the
caller, the captured traffic includes the RPCAP traffic as well. If this
flag is turned on, the RPCAP traffic is excluded from the capture, so that
the trace returned back to the collector is does not include this traffic.
public static final int OPENFLAG_NOCAPTURE_LOCAL
WinPcap.open
. This flag tells the
underlying capture driver to drop the packets that were sent by itself.
This is usefult when building applications like bridges, that should ignore
the traffic they just sent.
public static final int OPENFLAG_MAX_RESPONSIVENESS
WinPcap.open
. In presence of a large value for
nbytes, WinPcap waits for the arrival of several packets before copying the
data to the user. This guarantees a low number of system calls, i.e. lower
processor usage, i.e. better performance, which is good for applications
like sniffers. If the user sets the PCAP_OPENFLAG_MAX_RESPONSIVENESS flag,
the capture driver will copy the packets as soon as the application is
ready to receive them. This is suggested for real time applications (like,
for example, a bridge) that need the best responsiveness.
Method Detail |
---|
public static int findAllDevsEx(java.lang.String source, WinPcapRmtAuth auth, java.util.List<PcapIf> alldevs, java.lang.StringBuilder errbuf)
This function is a superset of the old 'pcap_findalldevs()', which is obsolete, and which allows listing only the devices present on the local machine. Vice versa, pcap_findalldevs_ex() allows listing the devices present on a remote machine as well. Additionally, it can list all the pcap files available into a given folder. Moreover, pcap_findalldevs_ex() is platform independent, since it relies on the standard pcap_findalldevs() to get addresses on the local machine.
In case the function has to list the interfaces on a remote machine, it opens a new control connection toward that machine, it retrieves the interfaces, and it drops the connection. However, if this function detects that the remote machine is in 'active' mode, the connection is not dropped and the existing socket is used.
The 'source' is a parameter that tells the function where the lookup has to be done and it uses the same syntax of the pcap_open().
Differently from the pcap_findalldevs(), the interface names (pointed by the alldevs->name and the other ones in the linked list) are already ready to be used in the pcap_open() call. Vice versa, the output that comes from pcap_findalldevs() must be formatted with the new pcap_createsrcstr() before passing the source identifier to the pcap_open().
The error message is returned in the 'errbuf' variable. An error could be due to several reasons:
Warning:
There may be network devices that cannot be opened with pcap_open() by the
process calling pcap_findalldevs(), because, for example, that process
might not have sufficient privileges to open them for capturing; if so,
those devices will not appear on the list. The interface list must be
deallocated manually by using the pcap_freealldevs().
source
- a char* buffer that keeps the 'source localtion', according to the
new WinPcap syntax. This source will be examined looking for
adapters (local or remote) (e.g. source can be 'rpcap://' for
local adapters or 'rpcap://host:port' for adapters on a remote
host) or pcap files (e.g. source can be 'file://c:/myfolder/').
The strings that must be prepended to the 'source' in order to
define if we want local/remote adapters or files is defined in the
new Source Specification Syntaxauth
- a pointer to a pcap_rmtauth structure. This pointer keeps the
information required to authenticate the RPCAP connection to the
remote host. This parameter is not meaningful in case of a query
to the local host: in that case it can be NULL.alldevs
- a list of all the network interfaceserrbuf
- error message (in case there is one)
public static boolean isSupported()
public static int offlineFilter(PcapBpfProgram program, PcapPktHdr header, java.nio.ByteBuffer buf)
program
- bpf filterheader
- packets headerbuf
- buffer containing packet data
public static WinPcap open(java.lang.String source, int snaplen, int flags, int timeout, WinPcapRmtAuth auth, java.lang.StringBuilder errbuf)
open
replaces all the openXxx()
methods with
a single call. This method hides the differences between the different
openXxx()
methods so that the programmer does not have to
manage different opening function. In this way, the 'true' open method is
decided according to the source type, which is included into the source
string (in the form of source prefix). This function can rely on the
createSrcStr
to create the string that keeps the capture
device according to the new syntax, and the parseSrcStr
for
the other way round.
Warning: The source cannot be larger than PCAP_BUF_SIZE. The following formats are not allowed as 'source' strings:
source
- The source name has to include the format prefix according to the
new Source Specification Syntax and it cannot be NULL. snaplen
- length of the packet that has to be retained. For each packet
received by the filter, only the first 'snaplen' bytes are stored
in the buffer and passed to the user application. For instance,
snaplen equal to 100 means that only the first 100 bytes of each
packet are stored.flags
- keeps several flags that can be needed for capturing packettimeout
- read timeout in milliseconds. The read timeout is used to arrange
that the read not necessarily return immediately when a packet is
seen, but that it waits for some amount of time to allow more
packets to arrive and to read multiple packets from the OS kernel
in one operation. Not all platforms support a read timeout; on
platforms that don't, the read timeout is ignored.auth
- a pointer to a 'struct pcap_rmtauth' that keeps the information
required to authenticate the user on a remote machine. In case
this is not a remote capture, this pointer can be set to NULL.errbuf
- a pointer to a user-allocated buffer which will contain the error
in case this function fails. The pcap_open() and findalldevs() are
the only two functions which have this parameter, since they do
not have (yet) a pointer to a pcap_t structure, which reserves
space for the error string. Since these functions do not have
(yet) a pcap_t pointer (the pcap_t pointer is NULL in case of
errors), they need an explicit 'errbuf' variable. 'errbuf' may
also be set to warning text when pcap_open_live() succeds; to
detect this case the caller should store a zero-length string in
'errbuf' before calling pcap_open_live() and display the warning
to the user if 'errbuf' is no longer a zero-length string.
public static int createSrcStr(java.lang.StringBuilder source, int type, java.lang.String host, java.lang.String port, java.lang.String name, java.lang.StringBuilder errbuf)
source
- will contain the complete source string wen the function returnstype
- its value tells the type of the source we want to createdhost
- an user-allocated buffer that keeps the host (e.g. "foo.bar.com")
we want to connect to. It can be NULL in case we want to open an
interface on a local hostport
- an user-allocated buffer that keeps the network port (e.g. "2002")
we want to use for the RPCAP protocol. It can be NULL in case we
want to open an interface on a local host.name
- an user-allocated buffer that keeps the interface name we want to
use (e.g. "eth0"). It can be NULL in case the return string (i.e.
'source') has to be used with the pcap_findalldevs_ex(), which
does not require the interface name.errbuf
- buffer that will contain the error message (in case there is one).
public static WinPcap openDead(int linktype, int snaplen)
linktype
- pcap DLT link type integer valuesnaplen
- filters generated using the pcap structure will truncate captured
packets to this length
Pcap.openDead(int, int)
public static WinPcap openLive(java.lang.String device, int snaplen, int promisc, int timeout, java.lang.StringBuilder errbuf)
This method, overrides the generic libpcap based openLive
method, and allocates a peer pcap object that allows WinPcap extensions.
Open a live capture associated with the specified network interface device. pcap_open_live() is used to obtain a packet capture descriptor 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. snaplen specifies the maximum number of bytes to capture. If this value is less than the size of a packet that is captured, only the first snaplen bytes of that packet will be captured and provided as packet data. A value of 65535 should be sufficient, on most if not all networks, to capture all the data available from the packet. promisc specifies if the interface is to be put into promiscuous mode. (Note that even if this parameter is false, the interface could well be in promiscuous mode for some other reason.)
For now, this doesn't work on the "any" device; if an argument of "any" or NULL is supplied, the promisc flag is ignored. to_ms specifies the read timeout in milliseconds. The read timeout is used to arrange that the read not necessarily return immediately when a packet is seen, but that it wait for some amount of time to allow more packets to arrive and to read multiple packets from the OS kernel in one operation. Not all platforms support a read timeout; on platforms that don't, the read timeout is ignored. A zero value for to_ms, on platforms that support a read timeout, will cause a read to wait forever to allow enough packets to arrive, with no timeout. errbuf is used to return error or warning text. It will be set to error text when pcap_open_live() fails and returns NULL. errbuf may also be set to warning text when pcap_open_live() succeds; to detect this case the caller should store a zero-length string in errbuf before calling pcap_open_live() and display the warning to the user if errbuf is no longer a zero-length string.
Special note about snaplen
argument. The behaviour
of this argument may be suprizing to some. The argument
is
only applied when there is a filter set using setFilter
method after the openLive
call. Otherwise snaplen, even non
zero is ignored. This is the behavior of all BSD systems utilizing BPF and
WinPcap. This may change in the future, but that is the current behavior.
(For more detailed explanation and discussion please see jNetPcap website
and its FAQs.)
device
- buffer containing a C, '\0' terminated string with the the name of
the devicesnaplen
- amount of data to capture per packet; (see special note in doc
comments about when this argument is ignored even when non-zero)promisc
- 1 means open in promiscious mode, a 0 means non-propmiscoustimeout
- timeout in mserrbuf
- a buffer that will contain any error messages if the call to open
failed
pcap_t
C structure as
returned by native libpcap call to openPcap.openLive(String, int, int, int, StringBuilder)
public static WinPcap openOffline(java.lang.String fname, java.lang.StringBuilder errbuf)
fname
- filename of the pcap fileerrbuf
- any error messages in UTC8 encoding
Pcap.openOffline(String, StringBuilder)
public static WinPcapSendQueue sendQueueAlloc(int size)
sendQueueTransmit(org.jnetpcap.winpcap.WinPcapSendQueue, int)
method.
size
- size of the sendqueue to allocate
sendQueueTransmit(WinPcapSendQueue, int)
public static void sendQueueDestroy(WinPcapSendQueue queue)
queue
- the queue to free uppublic int setMinToCopy(int size)
size
- minimum size
openLive(String, int, int, int, StringBuilder)
,
Pcap.loop(int, PcapHandler, Object)
,
Pcap.dispatch(int, PcapHandler, Object)
public int liveDump(java.lang.String fname, int maxsize, int maxpackets)
fname
- file namemaxsize
- maximum file sizemaxpackets
- maximum number of packets to store
public int liveDumpEnded(int sync)
sync
- if sync is nonzero, the function blocks until the dump is
finished, otherwise returns immediately
public int sendQueueTransmit(WinPcapSendQueue queue, int synch)
queue
- queue containing the data to be sentsynch
- if it is non-zero, the packets are sent respecting the timestamps,
otherwise they are sent as fast as possible
public int setBuff(int dim)
dim
- specifies the size of the buffer in bytes
openLive(String, int, int, int, StringBuilder)
,
Pcap.loop(int, PcapHandler, Object)
,
Pcap.dispatch(int, PcapHandler, Object)
public int setMode(int mode)
mode
- pcap capture mode
public WinPcapSamp setSampling()
Define a sampling method for packet capture. This function allows applying a sampling method to the packet capture process. The currently sampling methods (and the way to set them) are described into the struct pcap_samp. In other words, the user must set the appropriate parameters into it; these will be applied as soon as the capture starts.
Warning:
Sampling parameters cannot be changed when a capture is active. These
parameters must be applied before starting the capture. If they are applied
when the capture is in progress, the new settings are ignored. Sampling
works only when capturing data on Win32 or reading from a file. It has not
been implemented on other platforms. Sampling works on remote machines
provided that the probe (i.e. the capturing device) is a Win32 workstation.
public WinPcapStat statsEx()
Pcap.stats
method and allows more
statistics to be returned. Note, the signature of this method deviates
slightly from WinPcap implementation due to programming differences of
java. There is no need to deallocate any structures.
return stats structure which is
filled with statistics or null on error
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |