Struct pcap_parser::PcapNGReader

pub struct PcapNGReader<R> where
    R: Read,  { /* private fields */ }

Parsing iterator over pcap-ng data (streaming version)

Pcap-NG Reader

This reader is a streaming parser based on a circular buffer, which means memory usage is constant, and that it can be used to parse huge files or infinite streams. It creates an abstraction over any input providing the Read trait, and takes care of managing the circular buffer to provide an iterator-like interface.

The first call to next should return the a Section Header Block (SHB), marking the start of a new section. For each section, calls to next will return blocks, some of them containing data (SPB, EPB), and others containing information (IDB, NRB, etc.).

Some information must be stored (for ex. the data link type from the IDB) to be able to parse following block contents. Usually, a list of interfaces must be stored, with the data link type and capture length, for each section. These values are used when parsing Enhanced Packet Blocks (which gives an interface ID - the index, starting from 0) and Simple Packet Blocks (which assume an interface index of 0).

The size of the circular buffer has to be big enough for at least one complete block. Using a larger value (at least 65k) is advised to avoid frequent reads and buffer shifts.

There are precautions to take when reading multiple blocks before consuming data. See PcapReaderIterator for details.

Example

use pcap_parser::*;
use pcap_parser::traits::PcapReaderIterator;
use std::fs::File;

let file = File::open(path).unwrap();
let mut num_blocks = 0;
let mut reader = PcapNGReader::new(65536, file).expect("PcapNGReader");
let mut if_linktypes = Vec::new();
loop {
    match reader.next() {
        Ok((offset, block)) => {
            println!("got new block");
            num_blocks += 1;
            match block {
            PcapBlockOwned::NG(Block::SectionHeader(ref _shb)) => {
                // starting a new section, clear known interfaces
                if_linktypes = Vec::new();
            },
            PcapBlockOwned::NG(Block::InterfaceDescription(ref idb)) => {
                if_linktypes.push(idb.linktype);
            },
            PcapBlockOwned::NG(Block::EnhancedPacket(ref epb)) => {
                assert!((epb.if_id as usize) < if_linktypes.len());
                let linktype = if_linktypes[epb.if_id as usize];
                #[cfg(feature="data")]
                let res = pcap_parser::data::get_packetdata(epb.data, linktype, epb.caplen as usize);
            },
            PcapBlockOwned::NG(Block::SimplePacket(ref spb)) => {
                assert!(if_linktypes.len() > 0);
                let linktype = if_linktypes[0];
                let blen = (spb.block_len1 - 16) as usize;
                #[cfg(feature="data")]
                let res = pcap_parser::data::get_packetdata(spb.data, linktype, blen);
            },
            PcapBlockOwned::NG(_) => {
                // can be statistics (ISB), name resolution (NRB), etc.
                eprintln!("unsupported block");
            },
            PcapBlockOwned::Legacy(_)
            | PcapBlockOwned::LegacyHeader(_) => unreachable!(),
            }
            reader.consume(offset);
        },
        Err(PcapError::Eof) => break,
        Err(PcapError::Incomplete) => {
            eprintln!("Could not read complete data block.");
            eprintln!("Hint: the reader buffer size may be too small, or the input file nay be truncated.");
            break;
        },
        Err(e) => panic!("error while reading: {:?}", e),
    }
}
println!("num_blocks: {}", num_blocks);

Implementations

impl<R> PcapNGReader<R> where
    R: Read, 

pub fn new(
    capacity: usize,
    reader: R
) -> Result<PcapNGReader<R>, PcapError<&'static [u8]>>

Creates a new PcapNGReader<R> with the provided buffer capacity.

pub fn from_buffer(
    buffer: Buffer,
    reader: R
) -> Result<PcapNGReader<R>, PcapError<&'static [u8]>>

Creates a new PcapNGReader<R> using the provided Buffer.

Trait Implementations

impl<R> PcapReaderIterator for PcapNGReader<R> where
    R: Read, 

fn next(&mut self) -> Result<(usize, PcapBlockOwned<'_>), PcapError<&[u8]>>

Get the next pcap block, if possible. Returns the number of bytes read and the block.

fn consume(&mut self, offset: usize)

Consume data, and shift buffer if needed.

fn consume_noshift(&mut self, offset: usize)

Consume date, but do not change the buffer. Blocks already read are still valid.

fn consumed(&self) -> usize

Get the number of consumed bytes

fn refill(&mut self) -> Result<(), PcapError<&[u8]>>

Refill the internal buffer, shifting it if necessary.

fn position(&self) -> usize

Get the position in the internal buffer. Can be used to determine if refill is required.

fn grow(&mut self, new_size: usize) -> bool

Grow size of the internal buffer.

fn data(&self) -> &[u8]

Returns a slice with all the available data

fn reader_exhausted(&self) -> bool

Returns true if underlying reader is exhausted