Main Content

pcapReader

PCAP file reader of protocol packets

Since R2021b

expand all in page

    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

    Syntax

    pcap = pcapReader(filename)
    pcap = pcapReader(filename,OutputTimestampFormat='seconds')

    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

    Open Live Script

    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)
    decodedPackets=1×35 struct array with fields:
    SNo
    Timestamp
    LinkType
    Protocol
    PacketLength
    Packet
    RawBytes
    Open Live Script

    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
    Open Live Script

    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]

    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

    See Also

    Objects