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

Syntax

pcap = pcapReader(filename)

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

Description

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

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

Input Arguments

filename — Name of PCAP file

character vector | string scalar

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

OutputTimestampFormat — Output format for packet timestamp

'microseconds' (default) | 'seconds' | 'datetime'

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

MajorVersion — Major version of PCAP file format

nonnegative scalar

This property is read-only.

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

Data Types: double

MinorVersion — Minor version of PCAP file format

nonnegative scalar

This property is read-only.

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

Data Types: double

SnapLength — Maximum length of packet in PCAP file

nonnegative scalar

This property is read-only.

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

Data Types: double

LinkType — Link type in PCAP global header

nonnegative scalar

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

LinkName — Name of link type given by PCAP file reader object

character vector

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

NanoSecResolution — Flag to indicate whether PCAP file has nanosecond resolution for packet timestamp

1 or true | 0 or false

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

Specific to This Object

addLinkTypeDecoder	Add custom link layer protocol decoder to PCAP file reader
addUpperLayerDecoder	Add custom upper-layer protocol decoder to PCAP file reader
read	Read next protocol packet from PCAP file
readAll	Read all protocol packets from current position to end of PCAP file
reset	Reset position of PCAP file reader to first protocol packet of PCAP file

Examples

Read Ethernet Packets from PCAP File

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

Read Ethernet Packets in Streaming Mode from PCAP File

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

Read eCPRI Packets from PCAP File

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

Algorithms

The pcapReader object performs these operations, as illustrated in this diagram.

1. Read a packet from the PCAP file.

2. Select a decoder from the list of link layer decoders and decode the link layer header of the packet.

3. Proceed to the payload, which contains the packet for the next upper-layer protocol.

4. Select a decoder from the list of upper layer decoders and decode the header of the packet.

5. Continue selecting and using decoders for subsequent layers until decoding all headers in the entire packet or finding no suitable upper layer decoder.

The pcapReader object repeats these 5 steps for all packets in the PCAP file.

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