jnetpcap.capture
Interface FileCapture

All Superinterfaces:

Capture<FilePacket>, java.io.Closeable, FileIterator

All Known Subinterfaces:

MutableFileCapture, NapFile, PcapFile, SnoopFile

public interface FileCapture
extends Capture<FilePacket>, FileIterator, java.io.Closeable

Immutable interface to an open capture file. Use the factory method CaptureFactory.openFile(java.io.File) to get an instance of this interface.

Capture files contain network packet data captured from a network interface and stored in the file. The CaptureFile interface provides an abstraction to the possible formats for capture files.

FileCapture extends the standard Capture interface and adds several methods that provide file related information. Use the #hasNext and #next methods to iterate over packets within the file or call on getRecords(java.lang.Class) method to iterate over raw block records within the file. Block record (also called file header) contains a set of data records which contain captured packet data. The reason you have to iterate over block records, is that certain formats contain multiple block records while others can only contain one. getRecords(java.lang.Class) method is generic and you can request a more specific subclass of the block record. For example if you know you are working with a PCAP file, you can check using getFileType() method, you can request to retrieve the PCAP block records, and there should only be one for PCAP files.

 RecordIterator<PcapBlockRecord> fileHeader = fileCapture.getRecords(PcapBlockRecord.class);
  // Do something with the file header like get its magic number, timezone or accuracy
 

Another thing you can do once you have a block record is iterate over the block records child data records which contain packet data, as follows:

 RecordIterator<PcapBlockRecord> fileHeaders = fileCapture.getRecords(PcapBlockRecord.class);
 if (fileHeader.hasNext() == false) return; // Empty file
 RecordIterator<PcapPacketRecord> rawPackets = fileHeaders.next().getRecords(PcapPacketRecord.class):
 
 while (rawPackets.hasNext()) {
   PcapPacketRecord packet = rawPackets.next();
   // Do something with the raw packet record like extract its seconds or micros fields
   // Or more importantly access is data buffer using DataRecord.getDataBuffer()
   // PcapPacketRecord extends the DataRecord interface
 }
 

As you can see that various levels of access to file content is provided depending on what is needed. The simplest is using the top level IOIterator methods (extended by Capture interface) and simply iterate over the file, bypassing all of the complexity of its structure. When needed though, you can access any file formats exact structure. This level of access requires somewhat higher knowledge about file format, although that is also abstracted quiet a bit as well.

Note this is an immutable interface which does not allow any modification to the file. If you need to modify the file, you can use the Capture.isCaptureMutable() method to check if this FileCapture can be made mutable and call on Capture.getMutableCapture() to aquire a reference to MutableFileCapture which provides methods for modifying the underlying data store. All stream based FileCaptures are immutable and can not be turned into mutable versions as input streams are immutable.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Method Summary

<C extends FileCapture> C	asType(java.lang.Class<C> c) Converts the generic capture file into a more specific type.
void	close() Closes the capture session and underlying storage if it was opened.
FileType	getFileType() Returns file type of the currently open file.
java.nio.ByteOrder	getHeaderByteOrder()
byte[]	getMagicPattern() Returns the Magic number or pattern that is used to uniquely identify the file type of the capture file.
long	getPacketCount() Returns the number of packets within the file.
long	getPacketCount(PacketCounterModel model) Gets the packet count using a different algorithm.
<E extends BlockRecord> RecordIterator<E>	getRecords(java.lang.Class<E> c)
Version	getVersion() Returns the first file version found.
FilePacket	newPacket() Creates an empty packet record that is appropriate for the current file type.

Methods inherited from interface jnetpcap.capture.Capture

getFilter, getMutableCapture, getRemoteSession, isCaptureMutable, isCaptureRemote, setFilter

Methods inherited from interface jnetpcap.capture.FileIterator

getPosition

Method Detail

close

void close()
           throws java.io.IOException

Description copied from interface: Capture

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 Capture<FilePacket>

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException - any IO errors

getHeaderByteOrder

java.nio.ByteOrder getHeaderByteOrder()

getFileType

FileType getFileType()

Returns file type of the currently open file.

Returns:

file type of the open capture file

getMagicPattern

byte[] getMagicPattern()
                       throws java.io.IOException

Returns the Magic number or pattern that is used to uniquely identify the file type of the capture file. The magic number is not normalized so the pattern may be returned differently on big and small endian machines.

Returns:

pattern that is used to identify the file type

Throws:

java.io.IOException - any IO errors

getPacketCount

long getPacketCount()
                    throws java.io.IOException

Returns the number of packets within the file. This only includes records that hold packet data and not any additional meta data records. The method uses the default PacketCounter. If estimated packet counter is acceptable you can use one of of several other PacketCounterModels to calculate estimated packet count using the getPacketCount(PacketCounterModel) method.

The default PacketCounterModel is file type specific. The model at minimum returns an accurate count of packet records within the capture file, but no guarrantees about performance can be made and the performance will vary from format to format. You can use the more explicit getPacketCount(PacketCounterModel) method to counter packets.

Returns:

total number of packets within the file using the default model

Throws:

java.io.IOException - any io errors

getPacketCount

long getPacketCount(PacketCounterModel model)
                    throws java.io.IOException

Gets the packet count using a different algorithm. There are several different types of algorithms or PacketCounterModels to choose from, each has its own benefits and drawback. The reason that multiple algorithms are provided is that counting packets in a capture file can be extremely time consuming in large capture files since most capture files (with the exception of NAP) do not provide any sort of packet indexing or maintain a global count of packets within the entire file. Therefore the packets have to be in most cases iterated and counted. One of the models allows a statistical calculation upon the file which does not return a true packet count but is very close to the real number and in certain situations may be good enough.

Parameters:

model - model/algorithm to use to count packets

Returns:

number of packets calculated by the model

Throws:

java.io.IOException - any io exceptions

getRecords

<E extends BlockRecord> RecordIterator<E> getRecords(java.lang.Class<E> c)

getVersion

Version getVersion()

Returns the first file version found. There may be multiple blocks within the file at different versions.

Returns:

version of the file

newPacket

FilePacket newPacket()
                     throws java.io.IOException

Creates an empty packet record that is appropriate for the current file type. The record has not been written to file, does contain the appropriate record header; no packet buffer has been defined. So you must set a packet buffer.

Returns:

Throws:

java.io.IOException

asType

<C extends FileCapture> C asType(java.lang.Class<C> c)
                             throws CaptureFormatException

Converts the generic capture file into a more specific type. The type must be of the same type the open capture file is. That is this is not a cervesion method that converts from one format to the other, but simply returns the proper interface.

Here is an example that opens up a PCAP file and then aquires a reference to actual PCAPFile interface.

 CaptureFile file = CaptureFactory.openFile(new File("somefile.pcap"));
 PCAPFile pcap = file.asType(PCAPFile.class);
 

Type Parameters:

E -

Parameters:

c -

Returns:

Throws:

CaptureFormatException