readAll

Read all protocol packets from current position to end of PCAP file

Since R2021b

Syntax

protocolPackets = readAll(pcap)

protocolPackets = readAll(pcap,packetFilter)

Description

protocolPackets = readAll(pcap) reads all of the protocol packets from the current position to the end of the packet capture (PCAP) file specified by the input PCAP file reader and returns the decoded packets.

protocolPackets = readAll(pcap,packetFilter) returns only the decoded packets that match the specified filter, packetFilter.

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

Input Arguments

pcap — PCAP file reader

pcapReader object

PCAP file reader, specified as a pcapReader object.

packetFilter — Packet filter

character vector | string scalar

Packet filter, specified as a character vector or a string scalar. Ignoring the white spaces, this object function reads and decodes packets from a PCAP file and returns the packets that match the configured filters, packetFilter.

You can specify this argument as a combination of one or more filters connected by logical AND (& or &&) or logical OR (| or ||). This syntax shows a typical packet filter. The object function evaluates the specified filters from left to right.

protocolName.FieldName RELATIONALOPERATOR value

The valid values for protocolName are pcap, eth, and ecpri.

This table shows the valid values of FieldName and the data type of the corresponding value if protocolName is pcap.

FieldName Value	value Value
SNo	Integer
TimestampSec	Integer
PacketLength	Integer

This table shows the valid values of FieldName and the data type of the corresponding value if protocolName is eth.

FieldName Value	value Value
SourceAddress	Character vector or string scalar representing hexadecimal bytes
DestinationAddress	Character vector or string scalar representing hexadecimal bytes
Type	Integer

This table shows the valid values of FieldName and the data type of the corresponding value if protocolName is ecpri.

FieldName Value	value Value
ProtocolRevision	Integer
MessageType	Character vector or string scalar representing eCPRI message type
PC_ID	Integer
SEQ_ID	Integer

Note

For more information about the FieldName values, see the protocolPacket output.

The valid values for RELATIONALOPERATOR are <=, >=, >, <, ==, ~=, and ~.

Example: ‘pcap.PacketLength == 100’ filters the protocol packets of size 100 bytes.

Example: ‘eth.SourceAddress == 44FB5A9710AC & eth.Type == 2048’ filters the Ethernet packets with the specified source address and type of upper-layer protocol.

Example: ‘ecpri.MessageType == IQData || ecpri.MessageType == RemoteReset || ecpri.MessageType == EventIndication’ filters the eCPRI packets with message type IQ data, remote reset, or event indication.

Data Types: char | string

Output Arguments

protocolPackets — Decoded protocol packets

array of structures

Decoded protocol packets, returned as an array of structures containing these fields.

Field	Description
SNo	Serial number of the protocol packet
Timestamp	Timestamp of the packet in the format specified by the OutputTimestampFormat property.
TimestampSec	Timestamp of the packet in seconds. To enable this field, set the OutputTimestampFormat property of the pcap input to 'datetime'.
Protocol	Name of the link type
LinkType	Link type specified in the PCAP global header
PacketLength	Original length of the packet transmitted in the network, in bytes If this value is greater than the SnapLength property of the pcapReader object, the length of the decoded protocol packet is truncated to contain SnapLength bytes.
Packet	Decoded packet structure or packet bytes If the PCAP file includes Ethernet packets or eCPRI packets encapsulated in Ethernet, this field contains a decoded packet structure. Otherwise, this field contains packet bytes.
RawBytes	Undecoded bytes because of padding or decode error

If the PCAP file includes Ethernet packets, the Packet field of this argument contains a structure, eth, containing these fields.

Field	Description
SourceAddress	Medium access control (MAC) address of the source host in decimal bytes, returned as a column vector. You can access the source address of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.SourceAddress.
DestinationAddress	MAC address of the destination host in decimal bytes, returned as a column vector. You can access the destination address of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.DestinationAddress.
Type	Field in the Ethernet header that identifies the upper-layer protocol. You can access the upper-layer protocol type of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.Type.
Payload	Upper-layer protocol packet, returned as a vector of octets where each element is in the range [0, 255]. You can access the upper-layer protocol payload of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.Payload.
RawBytes	Undecoded bytes returned by the Ethernet decoder because of padding or decode error. If the Ethernet decoder does not return any undecoded bytes, this field is not present in the eth structure. You can access the raw bytes of the first Ethernet packet by using the command protocolPacket(1).Packet.eth.RawBytes.

If the PCAP file includes eCPRI packets encapsulated in Ethernet, the Packet field of this argument also contains a structure or a cell array of structures, ecpri, containing these fields.

Field	Description
ProtocolRevision	Protocol version of eCPRI, specified as a nonnegative integer.
Concatenation	Concatenation indicator of eCPRI messages, specified as 0 or 1. A value of 0 indicates the corresponding eCPRI message is the last one inside the eCPRI protocol data unit (PDU). A value of 1 indicates that another eCPRI message follows this one within the eCPRI PDU.
MessageType	Type of service supported by the eCPRI message, specified as a character vector or a string scalar.

The output of the eCPRI decoder varies according to the MessageType value. This table shows the MessageType values and the corresponding additional fields supported by the ecpri structure.

MessageType Value	MessageType Description	Additional Fields Supported by ecpri Structure
IQData	Transfer time domain or frequency domain in-phase and quadrature (IQ) samples	PC_ID, SEQ_ID, UserData, and Payload
BitSequence	Transfer user data in the form of bit sequence	PC_ID, SEQ_ID, UserData, and Payload
RealTimeControlData	Transfer vendor specific real-time control messages	PC_ID, SEQ_ID, UserData, and Payload
GenericDataTransfer	Transfer user plane data or related control	PC_ID, SEQ_ID, UserData, and Payload
RemoteMemoryAccess	Enable reading or writing from or to a specific memory address	RemoteMemoryAccessID, ReadWrite, RequestResponse, ElementID, Address, DataLength, UserData, and Payload
OnewayDelayMeasurement	Estimate the one-way delay between two eCPRI ports in one direction	MeasurementID, ActionType, TimestampSec, TimestampNanoSec, CompensationValue, UserData, and Payload
RemoteReset	Request to reset an eCPRI node	ResetID, ResetCodeOp, UserData, and Payload
EventIndication	Indicates an event has occurred	EventID, EventType, SequenceNumber, NumberOfFaultsOrNotifications, and Elements

Note

For more information on the message types and the corresponding additional fields supported in the ecpri structure, see Section 3.2.4 of the eCPRI Specification V1.2 [1].

Data Types: struct

References

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

Version History

Introduced in R2021b