org.jnetpcap.winpcap
Class WinPcap

java.lang.Object
  org.jnetpcap.Pcap
      org.jnetpcap.winpcap.WinPcap

public class WinPcap
extends Pcap

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 PcapExtensionNotAvailableException. Of course, 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
 }
 

Using WinPcap class

For the most part, you use 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:

• openLive - opens a live capture from network interface
• openOffline - opens a capture file
• openDead - opens a dummy capture for filter compiling
• open - special open command that uses the source string syntax to accomplish the same tasks as the three openXXX methods before it.

There are also several addition methods:

• findAllDevsEx - extended version of Pcap.findAllDevs which allows you to not only find network interfaces, but also PCAP files. This can be done locally or remotely.
• liveDump - which can dump captured packets to a savefile automatically at the kernel level.
• sendQueueTransmit - and related method, which allow raw packets to be sent in bulk, efficiently.
• setMinToCopy, setMode and setBuf - allow tweaking of kernel buffers and enable/disable statistical captures
• offlineFilter - ability to apply the BPF filter on your own packets without a capture
• setSampling - changes the mode of the capture where only samples of a capture are retruend. packets
• statEx - extended statistics that include counters on RPCAP remote connection

Using WinPcap.findAllDevsEx

The new method uses source string and WinPcapRmtAuth object and allows remote lookups of interfraces and files. A local lookup:

 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.

Using WinPcap.open method

Once you have a reference to a WinPcap object, you can then call any of its dynamic methods. Here is a straight forward example how to open a capture session and then close it:

 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.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

See Also:

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

MODE_CAPT

public static final int MODE_CAPT

default capture mode

See Also:

Constant Field Values

MODE_STAT

public static final int MODE_STAT

statistical mode

See Also:

Constant Field Values

MODE_MONITOR

public static final int MODE_MONITOR

monitor mode

See Also:

Constant Field Values

TRANSMIT_SYNCH_ASAP

public static final 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.

See Also:

Constant Field Values

TRANSMIT_SYNCH_USE_TIMESTAMP

public static final 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. The transmittion is synchronized with timestamps.

See Also:

Constant Field Values

SRC_FILE

public static final int SRC_FILE

Used to create a source string using method 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.

See Also:

Constant Field Values

SRC_IFLOCAL

public static final int SRC_IFLOCAL

Used to create a source string using method createSrcStr, which will be used to open a local network interface. Used with createSrcStr for its type field.

See Also:

Constant Field Values

SRC_IFREMOTE

public static final 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). Used with createSrcStr for its type field.

See Also:

Constant Field Values

OPENFLAG_DATATX_UDP

public static final 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. 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.

See Also:

Constant Field Values

OPENFLAG_NOCAPTURE_RPCAP

public static final int OPENFLAG_NOCAPTURE_RPCAP

Defines if the remote probe will capture its own generated traffic and can only be used with 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.

See Also:

Constant Field Values

OPENFLAG_NOCAPTURE_LOCAL

public static final int OPENFLAG_NOCAPTURE_LOCAL

Defines if the local adapter will capture its own generated traffic and can only be used with 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.

See Also:

Constant Field Values

OPENFLAG_MAX_RESPONSIVENESS

public static final int OPENFLAG_MAX_RESPONSIVENESS

This flag configures the adapter for maximum responsiveness and can only be used with 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.

See Also:

Constant Field Values

Method Detail

findAllDevsEx

public 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().

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:

• libpcap/WinPcap was not installed on the local/remote host
• the user does not have enough privileges to list the devices / files
• a network problem
• the RPCAP version negotiation failed
• other errors (not enough memory and others).

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().

Parameters:

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 Syntax

auth - 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 interfaces

errbuf - error message (in case there is one)

Returns:

'0' if everything is fine, '-1' if some errors occurred; this function returns '-1' also in case the system does not have any interface to list

isSupported

public static boolean isSupported()

Checks if WinPcap extensions are available on this platform.

Returns:

true means WinPcap extensions are available and loaded, otherwise false

offlineFilter

public static int offlineFilter(PcapBpfProgram program,
                                PcapPktHdr header,
                                java.nio.ByteBuffer buf)

Returns if a given filter applies to an offline packet. This function is used to apply a filter to a packet that is currently in memory. This process does not need to open an adapter; we need just to create the proper filter (by settings parameters like the snapshot length, or the link-layer type) by means of the pcap_compile_nopcap(). The current API of libpcap does not allow to receive a packet and to filter the packet after it has been received. However, this can be useful in case you want to filter packets in the application, instead of into the receiving process. This function allows you to do the job.

Parameters:

program - bpf filter

header - packets header

buf - buffer containing packet data

Returns:

snaplen of the packet or 0 if packet should be rejected

open

public 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. The 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:

• rpcap:// [to open the first local adapter]
• rpcap://hostname/ [to open the first remote adapter]

Parameters:

source - The source name has to include the format prefix according to the new Source Specification Syntax and it cannot be NULL.
On on Linux systems with 2.2 or later kernels, a device argument of "any" (i.e. rpcap://any) can be used to capture packets from all interfaces. In order to makes the source syntax easier, please remember that:

• the adapters returned by the pcap_findalldevs_ex() can be used immediately by the pcap_open()
• in case the user wants to pass its own source string to the pcap_open(), the pcap_createsrcstr() helps in creating the correct source identifier.

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 packet

timeout - 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.

Returns:

in case of problems, it returns null and the 'errbuf' variable keeps the error message.

createSrcStr

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)

Accept a set of strings (host name, port, ...), and it returns the complete source string according to the new format (e.g. 'rpcap://1.2.3.4/eth0'). This function is provided in order to help the user creating the source string according to the new format. An unique source string is used in order to make easy for old applications to use the remote facilities. Think about tcpdump, for example, which has only one way to specify the interface on which the capture has to be started. However, GUI-based programs can find more useful to specify hostname, port and interface name separately. In that case, they can use this function to create the source string before passing it to the pcap_open() function.

Parameters:

source - will contain the complete source string wen the function returns

type - its value tells the type of the source we want to created

host - 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 host

port - 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).

Returns:

'0' if everything is fine, '-1' if some errors occurred. The string containing the complete source is returned in the 'source' variable.

openDead

public static WinPcap openDead(int linktype,
                               int snaplen)

Create a pcap_t structure without starting a capture. pcap_open_dead() is 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 code.

Parameters:

linktype - pcap DLT link type integer value

snaplen - filters generated using the pcap structure will truncate captured packets to this length

Returns:

WinPcap structure that can only be used to generate filter code and none of its other capture methods should be called or null if error occured

See Also:

Pcap.openDead(int, int)

openLive

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.)

Parameters:

device - buffer containing a C, '\0' terminated string with the the name of the device

snaplen - 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-propmiscous

timeout - timeout in ms

errbuf - a buffer that will contain any error messages if the call to open failed

Returns:

a raw structure the data of pcap_t C structure as returned by native libpcap call to open

See Also:

Pcap.openLive(String, int, int, int, StringBuilder)

openOffline

public static WinPcap openOffline(java.lang.String fname,
                                  java.lang.StringBuilder errbuf)

Open a savefile in the tcpdump/libpcap format to read packets. pcap_open_offline() is called to open a "savefile" for reading. fname specifies the name of the file to open. The file has the same format as those used by tcpdump(1) and tcpslice(1). The name "-" in a synonym for stdin. Alternatively, you may call pcap_fopen_offline() to read dumped data from an existing open stream fp. Note that on Windows, that stream should be opened in binary mode. errbuf is used to return error text and is only set when pcap_open_offline() or pcap_fopen_offline() fails and returns NULL.

Parameters:

fname - filename of the pcap file

errbuf - any error messages in UTC8 encoding

Returns:

WinPcap structure or null if error occured

See Also:

Pcap.openOffline(String, StringBuilder)

sendQueueAlloc

public static WinPcapSendQueue sendQueueAlloc(int size)

Allocate a send queue. This method allocats a send queue, i.e. a buffer containing a set of raw packets that will be transmittted on the network with sendQueueTransmit(org.jnetpcap.winpcap.WinPcapSendQueue, int) method.

Parameters:

size - size of the sendqueue to allocate

Returns:

allocated sendqueue

See Also:

sendQueueTransmit(WinPcapSendQueue, int)

sendQueueDestroy

public static void sendQueueDestroy(WinPcapSendQueue queue)

Destroy a send queue. Deletes a send queue and frees all the memory associated with it.

Parameters:

queue - the queue to free up

setMinToCopy

public int setMinToCopy(int size)

Set the minumum amount of data received by the kernel in a single call. pcap_setmintocopy() changes the minimum amount of data in the kernel buffer that causes a read from the application to return (unless the timeout expires). If the value of size is large, the kernel is forced to wait the arrival of several packets before copying the data to the user. This guarantees a low number of system calls, i.e. low processor usage, and is a good setting for applications like packet-sniffers and protocol analyzers. Vice versa, in presence of a small value for this variable, the kernel will copy the packets as soon as the application is ready to receive them. This is useful for real time applications that need the best responsiveness from the kernel.

Parameters:

size - minimum size

Returns:

the return value is 0 when the call succeeds, -1 otherwise

See Also:

openLive(String, int, int, int, StringBuilder), Pcap.loop(int, PcapHandler, Object), Pcap.dispatch(int, PcapHandler, Object)

liveDump

public int liveDump(java.lang.String fname,
                    int maxsize,
                    int maxpackets)

dumps the network traffic from an interface to a file. Using this function the dump is performed at kernel level, therefore it is more efficient than using Pcap.dump(). The parameters of this function are an interface descriptor (obtained with openLive()), a string with the name of the dump file, the maximum size of the file (in bytes) and the maximum number of packets that the file will contain. Setting maxsize or maxpacks to 0 means no limit. When maxsize or maxpacks are reached, the dump ends. liveDump() is non-blocking, threfore Return immediately. liveDumpEnded() can be used to check the status of the dump process or to wait until it is finished. Pcap.close() can instead be used to end the dump process. Note that when one of the two limits is reached, the dump is stopped, but the file remains opened. In order to correctly flush the data and put the file in a consistent state, the adapter must be closed with Pcap.close().

Parameters:

fname - file name

maxsize - maximum file size

maxpackets - maximum number of packets to store

Returns:

0 on success otherwise -1

liveDumpEnded

public int liveDumpEnded(int sync)

Return the status of the kernel dump process, i.e. tells if one of the limits defined with pcap_live_dump() has been reached. pcap_live_dump_ended() informs the user about the limits that were set with a previous call to pcap_live_dump() on the interface pointed by p: if the return value is nonzero, one of the limits has been reched and the dump process is currently stopped. If sync is nonzero, the function blocks until the dump is finished, otherwise Return immediately. Warning: if the dump process has no limits (i.e. if the maxsize and maxpacks arguments of pcap_live_dump() were both 0), the dump process will never stop, therefore setting sync to TRUE will block the application on this call forever.

Parameters:

sync - if sync is nonzero, the function blocks until the dump is finished, otherwise returns immediately

Returns:

non zero value means that dump process has finished, a zero means its still in progress

sendQueueTransmit

public int sendQueueTransmit(WinPcapSendQueue queue,
                             int synch)

Send a queue of raw packets to the network. This function transmits the content of a queue to the wire. p is a pointer to the adapter on which the packets will be sent, queue points to a pcap_send_queue structure containing the packets to send (see pcap_sendqueue_alloc() and pcap_sendqueue_queue()), sync determines if the send operation must be synchronized: if it is non-zero, the packets are sent respecting the timestamps, otherwise they are sent as fast as possible. The return value is the amount of bytes actually sent. If it is smaller than the size parameter, an error occurred during the send. The error can be caused by a driver/adapter problem or by an inconsistent/bogus send queue. Note: Using this function is more efficient than issuing a series of pcap_sendpacket(), because the packets are buffered in the kernel driver, so the number of context switches is reduced. Therefore, expect a better throughput when using pcap_sendqueue_transmit. When Sync is set to TRUE, the packets are synchronized in the kernel with a high precision timestamp. This requires a non-negligible amount of CPU, but allows normally to send the packets with a precision of some microseconds (depending on the accuracy of the performance counter of the machine). Such a precision cannot be reached sending the packets with pcap_sendpacket().

Parameters:

queue - queue containing the data to be sent

synch - if it is non-zero, the packets are sent respecting the timestamps, otherwise they are sent as fast as possible

Returns:

amount of bytes actually sent; error if less then queues len parameter

setBuff

public int setBuff(int dim)

Set the size of the kernel buffer associated with an adapter. If an old buffer was already created with a previous call to pcap_setbuff(), it is deleted and its content is discarded. pcap_open_live() creates a 1 MByte buffer by default.

Parameters:

dim - specifies the size of the buffer in bytes

Returns:

the return value is 0 when the call succeeds, -1 otherwise

See Also:

openLive(String, int, int, int, StringBuilder), Pcap.loop(int, PcapHandler, Object), Pcap.dispatch(int, PcapHandler, Object)

setMode

public int setMode(int mode)

Set the working mode of the interface p to mode. Valid values for mode are MODE_CAPT (default capture mode) and MODE_STAT (statistical mode).

Parameters:

mode - pcap capture mode

Returns:

the return value is 0 when the call succeeds, -1 otherwise

setSampling

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.

Returns:

an object through which you can change the capture algorithm

statsEx

public WinPcapStat statsEx()

This method extends the 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.

See Also:

return stats structure which is filled with statistics or null on error