Main Content

read

Read next protocol packet from PCAP file

Since R2021b

    Description

    example

    protocolPacket = read(pcap) reads the next protocol packet from the packet capture (PCAP) file specified by the input PCAP file reader and returns the decoded packet.

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

    Examples

    collapse all

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

    pcapReaderObj = pcapReader('ethernetSamplePackets.pcap');

    Create a filter for the message types of eCPRI packets.

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

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

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

    Input Arguments

    collapse all

    PCAP file reader, specified as a pcapReader object.

    Packet filter, specified as a character vector or a string scalar. Ignoring the white spaces, this object function reads the protocol packets that match this value. If the next packet does not match this value, the object function continues to read the next packet until one of these actions occurs.

    • The object function detects a packet that matches the specified filter.

    • The object function reaches the end of the PCAP file.

    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.

    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

    collapse all

    Decoded protocol packet, returned as a structure 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 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