Main Content

pcapReader

PCAP file reader of protocol packets

Since R2021b

    Description

    The pcapReader object reads and decodes Ethernet and enhanced common public radio interface (eCPRI) protocol packets based on specific criteria. You can also plug in custom protocol decoders.

    Creation

    Description

    example

    pcap = pcapReader(filename) creates a PCAP file reader object to read protocol packets from the input PCAP file.

    example

    pcap = pcapReader(filename,OutputTimestampFormat='seconds') sets OutputTimestampFormat property to seconds.

    Input Arguments

    expand all

    Name of a PCAP file including the extension, specified as a character vector or a string scalar.

    Example: "ethernetSamplePackets.pcap"

    Data Types: char | string

    Properties

    expand all

    Output format for the packet timestamp, specified as 'microseconds', 'seconds', or 'datetime'. This value specifies the timestamp of the decoded protocol packet.

    Data Types: char | string

    This property is read-only.

    Major version of the PCAP file format, returned as a nonnegative scalar.

    Data Types: double

    This property is read-only.

    Minor version of the PCAP file format, returned as a nonnegative scalar.

    Data Types: double

    This property is read-only.

    Maximum length of the packet in the PCAP file, returned as a nonnegative scalar.

    Data Types: double

    This property is read-only.

    Link type in the PCAP global header, returned as a nonnegative scalar. For more information about this property, see Tcpdump/Libpcap Public Repository [1].

    Data Types: double

    This property is read-only.

    Name of the link type given by the PCAP file reader object, returned as a character vector.

    Data Types: char

    This property is read-only.

    Flag to indicate whether the PCAP file has nanosecond resolution for the packet timestamp, returned as 1 (true) or 0 (false).

    Data Types: logical

    Object Functions

    expand all

    addLinkTypeDecoderAdd custom link layer protocol decoder to PCAP file reader
    addUpperLayerDecoderAdd custom upper-layer protocol decoder to PCAP file reader
    readRead next protocol packet from PCAP file
    readAllRead all protocol packets from current position to end of PCAP file
    resetReset position of PCAP file reader to first protocol packet of PCAP file

    Examples

    collapse all

    Create a PCAP file reader object, specifying the name of a PCAP file.

    pcapReaderObj = pcapReader('ethernetSamplePackets.pcap');

    Read all of the packets from the PCAP file to the MATLAB® workspace.

    decodedPackets = readAll(pcapReaderObj);

    Clear the pcapReaderObj variable from the current workspace.

    clear pcapReaderObj

    Create a PCAP file reader object, specifying the name of a PCAP file and an output format for the packet timestamp.

    pcapReaderObj = pcapReader('ethernetSamplePackets.pcap', ...
        OutputTimestampFormat='datetime');

    Create a filter for the Ethernet source address and Ethernet type.

    filterString = ['eth.SourceAddress == 44FB5A9710AC && ' ...
        'eth.Type == 2048'];

    In streaming mode, read the Ethernet packets that match the specified filter to the MATLAB workspace.

    for packetCount = 1:3
        ethPacket = read(pcapReaderObj,filterString)
    end
    ethPacket = struct with fields:
                 SNo: 1
           Timestamp: 08-Feb-2021 03:27:18.043900
            LinkType: 1
            Protocol: 'eth'
        PacketLength: 171
              Packet: [1x1 struct]
            RawBytes: [1x0 double]
        TimestampSec: 1.6128e+09
    
    
    ethPacket = struct with fields:
                 SNo: 4
           Timestamp: 08-Feb-2021 03:27:19.098190
            LinkType: 1
            Protocol: 'eth'
        PacketLength: 120
              Packet: [1x1 struct]
            RawBytes: [1x0 double]
        TimestampSec: 1.6128e+09
    
    
    ethPacket = struct with fields:
                 SNo: 5
           Timestamp: 08-Feb-2021 03:27:20.145857
            LinkType: 1
            Protocol: 'eth'
        PacketLength: 171
              Packet: [1x1 struct]
            RawBytes: [1x0 double]
        TimestampSec: 1.6128e+09
    
    

    Clear the pcapReaderObj variable from the current workspace.

    clear pcapReaderObj

    Create a PCAP file reader object, specifying the name of a PCAP file.

    pcapReaderObj = pcapReader('ethernetSamplePackets.pcap');

    Create a filter for the eCPRI packets, specifying the eCPRI message types.

    filterString = ['ecpri.MessageType == IQData || ecpri.MessageType == BitSequence ' ...
        '|| ecpri.MessageType == RemoteReset'];

    Read the eCPRI packets that match the specified filters to the MATLAB workspace.

    ecpriFilteredFirstPacket = read(pcapReaderObj,filterString)
    ecpriFilteredFirstPacket = struct with fields:
                 SNo: 21
           Timestamp: 1.6128e+15
            LinkType: 1
            Protocol: 'eth'
        PacketLength: 64
              Packet: [1x1 struct]
            RawBytes: [1x0 double]
    
    
    ecpriFilteredSecondPacket = read(pcapReaderObj,filterString)
    ecpriFilteredSecondPacket = struct with fields:
                 SNo: 22
           Timestamp: 1.6128e+15
            LinkType: 1
            Protocol: 'eth'
        PacketLength: 64
              Packet: [1x1 struct]
            RawBytes: [1x0 double]
    
    
    ecpriFilteredRemainingPackets = readAll(pcapReaderObj,filterString)
    ecpriFilteredRemainingPackets=1×5 struct array with fields:
        SNo
        Timestamp
        LinkType
        Protocol
        PacketLength
        Packet
        RawBytes
    
    

    Reset the position of the PCAP file reader to the first packet of the PCAP file.

    reset(pcapReaderObj);

    Create a new filter on the same PCAP file, specifying the message type as in-phase and quadrature (IQ) data.

    filterString = 'ecpri.MessageType == IQData';

    Read the eCPRI packets that match the specified filter to the MATLAB workspace.

    ecpriFilteredPackets = readAll(pcapReaderObj,filterString)
    ecpriFilteredPackets = struct with fields:
                 SNo: 21
           Timestamp: 1.6128e+15
            LinkType: 1
            Protocol: 'eth'
        PacketLength: 64
              Packet: [1x1 struct]
            RawBytes: [1x0 double]
    
    

    Clear the pcapReaderObj variable from the current workspace.

    clear pcapReaderObj

    References

    [1] Group, The Tcpdump. “Tcpdump/Libpcap Public Repository.” Accessed May 20, 2020. https://www.tcpdump.org.

    [2] “Development/LibpcapFileFormat - The Wireshark Wiki.” Accessed May 20, 2020. https://www.wireshark.org.

    [3] “Common Public Radio Interface: eCPRI Interface Specification V1.2 ” Accessed June 22, 2021.

    Version History

    Introduced in R2021b