org.jnetstream.capture
Interface LiveCapture

All Superinterfaces:

Capture<LivePacket>, java.io.Closeable, java.lang.Iterable<LivePacket>

public interface LiveCapture
extends Capture<LivePacket>, java.io.Closeable

A network packet cature on a live network interface. To obtain an instance of a class implementing this interface, use one of the Captures.openLive() methods which open up a network interface live capture.

 
 LiveCapture capture = Captures.openLive(); while (capture.hasNext()) {
 CapturePacket packet = capture.next(); // Do something with the packet now }
 
 

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

static class

LiveCapture.Option Options which can be set on open captures.

Field Summary

static LiveCapture.Option

DEFAULT_CAPTURE_OPTION The default option when none are specified by the user.

Method Summary

Filter<ProtocolFilterTarget>	getFilter() Gets the currently active filter that has been applied to all the currently open capture devices.
LiveCaptureDevice[]	getOpenCaptureDevices() Gets the list of currently open capture devices by this capture session.
LiveIterator	getPacketIterator() An iterator that iterates over captured LivePackets.
int	getSnaplen() Gets the current snap length that this capture session is using.
int	getTimeout() Gets the timeout value that before this capture session stop capturing packets.
boolean	isPromisuous() Returns the state of the currently open network interface.
void	setFilter(Filter<ProtocolFilterTarget> filter) Applies a filter to a network interface globally.

Methods inherited from interface org.jnetstream.capture.Capture

getType, isMutable, iterator

Methods inherited from interface java.io.Closeable

close

Field Detail

DEFAULT_CAPTURE_OPTION

static final LiveCapture.Option DEFAULT_CAPTURE_OPTION

The default option when none are specified by the user.

Method Detail

getPacketIterator

LiveIterator getPacketIterator()
                               throws java.io.IOException

An iterator that iterates over captured LivePackets. The iterator provides 2 additional methods, skip and close. Skip efficiently skips over the current packet discarding any data that was captured and close closes the capture session associated with this iterator.

Each iterator maintains its own queue of packets from which it draws packets to be returned via its next method. If the user instantiates more than one LiveIterator, each iterator will return packets irrispective of any other iterator. If the iterator's packet queue becomes full and no more packets can be received, the packets will not be added to the iterator's queue, but may be added to other iterators' queues it there are others and the iterator's queue drop counter will be incremented.

Specified by:

getPacketIterator in interface Capture<LivePacket>

Returns:

Iterator capable of throwing IO exceptions

Throws:

java.io.IOException - Any IO errors while retrieving a packet

setFilter

void setFilter(Filter<ProtocolFilterTarget> filter)
               throws java.io.IOException

Applies a filter to a network interface globally. The filter will be applied to the open network interfaces by this live capture session. The underlying operating system applies the filter to each interface globally. Meaning that if other live capture sessions or even other programs applied a filter to an interface that filter is active for all other live capture sessions on the same interface.

Parameters:

filter - packet filter to apply all open network interfaces

Throws:

java.io.IOException - any IO errors while applying the filter.

isPromisuous

boolean isPromisuous()

Returns the state of the currently open network interface. Determines if the network interface is currently set in promiscuous mode. Normally network interfaces reject packets that are not broadcast or have their destination MAC address set to the address of the network's interface. In promiscuous mode, all packets are captured by the network interface, allowing greater inspection of network traffic.

Note: This version of implementation uses libraries which can no check the actual status of the interface, but will return the status of the flag as it was originally invoked by the user. Future versions will have capability to check promiscuous mode status directly with the network interface. This will allow detection of promiscuous mode, even when this particular LiveCapture did not enable it. The promiscuous flag is a global on a network interface, meaning that it can be enabled by any process and will affect all other processes capturing that interface. A promisuous flag can change state from false to true in unexpected ways and unpredictable times.

Returns:

getSnaplen

int getSnaplen()

Gets the current snap length that this capture session is using. Snap len truncates the length of the packets from their original length as they were captured on live network. Since its not always neccessary to have entire packet, including its data portions, for analysis, it is common practice to trucate the length of the actual data retained, to some length that captures enough data to decode the packet headers only.

Returns:

the maximum number of bytes that will be retained by this captures session on a per packet basis

getTimeout

int getTimeout()

Gets the timeout value that before this capture session stop capturing packets. The capture session is not closed upon timeout, it simply stop capturing packets at which time it can be instructed to capture more packets or possibly close the capture session.

Returns:

maximum number of milli seconds to wait for a packet to arrive before stopping packet capture and unblocking any waiting operations for new packets to arrive

getOpenCaptureDevices

LiveCaptureDevice[] getOpenCaptureDevices()

Gets the list of currently open capture devices by this capture session. LiveCapture object allow more than one capture device to be open for capture at the same time.

Returns:

an array of currently open capture devices

getFilter

Filter<ProtocolFilterTarget> getFilter()

Gets the currently active filter that has been applied to all the currently open capture devices.

Specified by:

getFilter in interface Capture<LivePacket>

Returns:

currently active filter or null if none was set