jpcap
Class JpcapCaptor

java.lang.Object
  extended by jpcap.JpcapCaptor

public class JpcapCaptor
extends java.lang.Object

This class is used to capture packets or read packets from a captured file.


Field Summary
 int dropped_packets
          Number of dropped packets
 int received_packets
          Number of received packets
 
Method Summary
 void breakLoop()
          Set a flag that will force processPacket() and loopPacket() to return rather than looping.
 void close()
          Closes the opened interface of dump file.
 int dispatchPacket(int count, PacketReceiver handler)
          Deprecated. 
static NetworkInterface[] getDeviceList()
          Returns the interfaces that can be used for capturing.
 java.lang.String getErrorMessage()
          Returns an error message
 JpcapSender getJpcapSenderInstance()
          Obtains an instance of JpcapSender that uses the same interface to send packets.
 Packet getPacket()
          Captures a single packet.
 int getPacketReadTimeout()
          Returns the socket read timeout (SO_RCVTIMEO) for the socket used to read packets from the kernel.
 boolean isNonBlockinMode()
          Checks if the current setting is in "non-blocking" mode or not.
 int loopPacket(int count, PacketReceiver handler)
          Captures the specified number of packets consecutively.
static JpcapCaptor openDevice(NetworkInterface intrface, int snaplen, boolean promisc, int to_ms)
          Opens the specified network interface, and returns an instance of this class.
static JpcapCaptor openFile(java.lang.String filename)
          Opens a dump file created by tcpdump or Ethereal, and returns an instance of this class.
 int processPacket(int count, PacketReceiver handler)
          Captures the specified number of packets consecutively.
Unlike loopPacket(), this method returns (althrough not guaranteed) when the timeout expires.
 void setFilter(java.lang.String condition, boolean optimize)
          Sets a filter.
 void setNonBlockingMode(boolean nonblocking)
          Sets/unsets "non-blocking" mode
 boolean setPacketReadTimeout(int millis)
          Sets the socket read timeout (SO_RCVTIMEO) for the socket used to read packets from the kernel.
 void updateStat()
          Updates received_packets and dropped_packets.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

received_packets

public int received_packets
Number of received packets

See Also:
updateStat()

dropped_packets

public int dropped_packets
Number of dropped packets

See Also:
updateStat()
Method Detail

getDeviceList

public static NetworkInterface[] getDeviceList()
Returns the interfaces that can be used for capturing.

Returns:
List of Interface objects

openDevice

public static JpcapCaptor openDevice(NetworkInterface intrface,
                                     int snaplen,
                                     boolean promisc,
                                     int to_ms)
                              throws java.io.IOException
Opens the specified network interface, and returns an instance of this class.

Parameters:
intrface - The network interface to capture packets
snaplen - Max number of bytes captured at once
promisc - If true, the inferface becomes promiscuous mode
to_ms - Timeout of processPacket(). Not all platforms support a timeout; on platforms that don't, the timeout is ignored. On platforms that support a timeout, a zero value will cause Jpcap to wait forever to allow enough packets to arrive, with no timeout.
Returns:
an instance of this class Jpcap.
Throws:
java.io.IOException - Raised when the specified interface cannot be opened

openFile

public static JpcapCaptor openFile(java.lang.String filename)
                            throws java.io.IOException
Opens a dump file created by tcpdump or Ethereal, and returns an instance of this class.

Parameters:
filename - File name of the dump file
Returns:
an instance of this class Jpcap
Throws:
java.io.IOException - If the file cannot be opened

close

public void close()
Closes the opened interface of dump file.


getPacket

public Packet getPacket()
Captures a single packet.

Returns:
a captured packet.
null if an error occured or timeout has elapsed.
Packet.EOF is EOF was reached when reading from a offline file.

processPacket

public int processPacket(int count,
                         PacketReceiver handler)
Captures the specified number of packets consecutively.
Unlike loopPacket(), this method returns (althrough not guaranteed) when the timeout expires. Also, in "non-blocking" mode, this method returns immediately when there is no packet to capture.

Parameters:
count - Number of packets to be captured
You can specify -1 to capture packets parmanently until timeour, EOF or an error occurs.
handler - an instnace of JpcapHandler that analyzes the captured packets
Returns:
Number of captured packets

loopPacket

public int loopPacket(int count,
                      PacketReceiver handler)
Captures the specified number of packets consecutively.

Unlike processPacket(), this method ignores the timeout. This method also does not support "non-blocking" mode.

Parameters:
count - Number of packets to be captured
You can specify -1 to capture packets parmanently until EOF or an error occurs.
handler - an instnace of JpcapHandler that analyzes the captured packets
Returns:
Number of captured packets

dispatchPacket

@Deprecated
public int dispatchPacket(int count,
                                     PacketReceiver handler)
Deprecated. 

Same as processPacket()


setNonBlockingMode

public void setNonBlockingMode(boolean nonblocking)
Sets/unsets "non-blocking" mode

Parameters:
nonblocking - TRUE to set "non-blocking" mode. FALSE to set "blocking" mode

isNonBlockinMode

public boolean isNonBlockinMode()
Checks if the current setting is in "non-blocking" mode or not.

Returns:
TRUE if it is in "non-blocking" mode. FALSE otherwise.

breakLoop

public void breakLoop()
Set a flag that will force processPacket() and loopPacket() to return rather than looping.

Note that processPacket() and loopPacket() will not return after this flag is set UNTIL a packet is received or a read timeout occurs. By default, there is no read timeout. See comments in setPacketReadTimeout().


setPacketReadTimeout

public boolean setPacketReadTimeout(int millis)
Sets the socket read timeout (SO_RCVTIMEO) for the socket used to read packets from the kernel. Setting this timeout is useful if using processPacket() or loopPacket() in blocking mode and you expect breakLoop() to work. breakLoop() will only have an effect if (a) you are actually getting packets or (b) if the read on the socket times out occasionally.

This is currently only supported on UNIX.

Parameters:
millis - Timeout in milliseconds; 0 for no timeout.
Returns:
true upon success; false upon failure or if unsupported.

getPacketReadTimeout

public int getPacketReadTimeout()
Returns the socket read timeout (SO_RCVTIMEO) for the socket used to read packets from the kernel.

This is currently only supported on UNIX.

Returns:
Read timeout in milliseconds; 0 for no timeout; -1 if an error occurred or this feature is unsupported.

setFilter

public void setFilter(java.lang.String condition,
                      boolean optimize)
               throws java.io.IOException
Sets a filter. This filter is same as tcpdump.

Parameters:
condition - a string representation of the filter
optimize - If true, the filter is optimized
Throws:
java.io.IOException - Raised if the filter condition cannot be compiled or installed

updateStat

public void updateStat()
Updates received_packets and dropped_packets.


getErrorMessage

public java.lang.String getErrorMessage()
Returns an error message

Returns:
error message

getJpcapSenderInstance

public JpcapSender getJpcapSenderInstance()
Obtains an instance of JpcapSender that uses the same interface to send packets. You can use this method only if you opened an interface with openDevice() method.

Returns:
returns an instance of JpcapSender