jnetpcap.capture
Interface Capture<T extends CapturePacket>

All Superinterfaces:

java.io.Closeable

All Known Subinterfaces:

FileCapture, LiveCapture, MutableCapture<T>, MutableFileCapture, NapFile, PcapFile, SnoopFile

public interface Capture<T extends CapturePacket>
extends java.io.Closeable

A high level, active either a live network or offline file session. You use one of the CaptureFactory (with an 's') or RemoteSession factory methods to open up a capture session to aquire a reference to a Capture. This interface extends the IOIterator which allows iteration over all of the packets using simple IOIterator#hasNext and IOIterator#next method calls. In addition you can perform some capture session specific operations such as setting a filter or checking if the session is local, remote, immutable or mutable.

Capture interface is immutable but does provide the method isCaptureMutable() and getMutableCapture() for converting into a mutable capture which provides many additional methods for adding, removing, moving and seeking (searching) around the mutable capture session. Mutable capture sessions are typically file based, but other circumstances may exist as well to allow mutable capture sessions.

Capture interface methods work the same locally or remotely. You can start up a remote session using one of the RemoteSession method calls which return a reference to Capture interface. All methods available locally are also available for remote sessions. You can inquire if the capture session is local or remote by invoking isCaptureRemote() and then aquire the RemoteSession that initiated this capture by getRemoteSession(). Remote sessions are very easy and intuitive way to manipulate capture files remotely and initiate live network captures on remote systems.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Method Summary

void	close() Closes the capture session and underlying storage if it was opened.
Filter	getFilter() Gets the currently active filter set on this capture session.
MutableCapture<T>	getMutableCapture() Converts this capture session from immutable Capture to MutableCapture which provides methods for adding, removing, moving and seeking (searching) around the underlying storage and packet dataset.
RemoteSession	getRemoteSession() Gets a reference to the RemoteSession instance that initated this capture session.
boolean	isCaptureMutable() Tells if this capture session is mutable.
boolean	isCaptureRemote() Tells if this capture session is local or remote.
void	setFilter(Filter filter) Sets a new filter on this active capture session.

Method Detail

isCaptureMutable

boolean isCaptureMutable()

Tells if this capture session is mutable. Capture interface does not provide any mutable methods on the underlying capture session but you can convert to a MutableCapture using getMutableCapture() method call.

Returns:

true means this session is mutable and you can call getMutableCapture() or false which means this session is immutable.

getMutableCapture

MutableCapture<T> getMutableCapture()

Converts this capture session from immutable Capture to MutableCapture which provides methods for adding, removing, moving and seeking (searching) around the underlying storage and packet dataset. The MutableCapture may or may not be a sub-class of the same Capture. The returned MutableCapture may an instance of new MutableCapture session and the previous Capture reference should be discarded.

Returns:

instance to MutableCapture that is using the same capture session as the original Capture object

isCaptureRemote

boolean isCaptureRemote()

Tells if this capture session is local or remote. Local sessions are local to the system the calls are being made on such as one of its files or live network captures. Remote sessions are such that the capture sessions (file or live network interface) were opened on a remote system, a system other then where these methods are being invoked. Remote sessions utilize a communication protocol between this client and a remote server (RemoteServer class) which executes the user requests made on this local system (the client). If the capture is remote, this method returns true, then you can safely call on getRemoteSession() to retrieve the RemoteSession instance that initiated this capture and this capture is connected to.

Returns:

true means this capture session is proxying its commands through a remote server, otherwise this is a local session which executes everything locally on this system

getRemoteSession

RemoteSession getRemoteSession()

Gets a reference to the RemoteSession instance that initated this capture session. The RemoteSession is connected to a RemoteServer on another server which executes the commands on behalf of this Capture instance. Using RemoteSession interface the user can open other capture sessions and issue certain remote commands to be executed on the remote server.

Returns:

reference to the active remote session connected to a remote server

getFilter

Filter getFilter()

Gets the currently active filter set on this capture session. Filters allow efficient way of filtering, or rejecting certain packets while allowing the rest that match the filter criteria to be returned. Filters are usually very efficient at rejecting packets at the source of the packets such as right at the live network interface where typically the kernel accepts or rejects the incomming packets without any copying of packet data. For files filters again are used to efficiently map portions of the capture files so that packets in the file can be accepted or rejected as efficiently as possible, usually with just the single kernel level copies into its buffers.

Returns:

currently active filter

setFilter

void setFilter(Filter filter)
               throws java.io.IOException

Sets a new filter on this active capture session. Filters allow efficient way of filtering, or rejecting certain packets while allowing the rest that match the filter criteria to be returned. Filters are usually very efficient at rejecting packets at the source of the packets such as right at the live network interface where typically the kernel accepts or rejects the incomming packets without any copying of packet data. For files filters again are used to efficiently map portions of the capture files so that packets in the file can be accepted or rejected as efficiently as possible, usually with just the single kernel level copies into its buffers.

Parameters:

filter - filter to apply to this capture session

Throws:

java.io.IOException - any IO errors

close

void close()
           throws java.io.IOException

Closes the capture session and underlying storage if it was opened. The close call does not close the underlying RemoteSession if one was opened, only the capture session is closed and flushed if appropriate.

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException - any IO errors