addUpperLayerDecoder

Add custom upper-layer protocol decoder to PCAP file reader

Since R2021b

Syntax

addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder)

addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder,protocolFields)

Description

You can use the addUpperLayerDecoder object function to plug in a custom upper-layer protocol decoder to the pcapReader object for decoding the payload of an existing protocol decoder. For example, you can add an upper-layer protocol decoder, such as internet protocol (IP), to decode the payload in the output of an existing protocol decoder, Ethernet.

addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder) adds a custom upper-layer protocol decoder function handle, upperLayerDecoder, to the packet capture (PCAP) file reader, pcap, for decoding the payload in the output of an existing protocol decoder, protocolName. The fieldName input specifies the field in the output structure of the existing protocol decoder, and the fieldValue input specifies the value of this field name. The upperLayerProtocolName input specifies a name for the upper-layer protocol decoder.

addUpperLayerDecoder(pcap,protocolName,fieldName,fieldValue,upperLayerProtocolName,upperLayerDecoder,protocolFields) additionally specifies protocol fields to filter packets based on the specified fields of the protocol decoder output.

Examples

Add Internet Protocol Packet Decoder to PCAP File Reader

Create a protocol decoder function handle for decoding IP packets.

ipDecoderHandle = @helperIPDecode;

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

pcapReaderObj = pcapReader("ethernetSamplePackets.pcap");

Add IP packet decoder to the PCAP file reader for decoding the payload in the output of an existing protocol decoder, Ethernet.

addUpperLayerDecoder(pcapReaderObj,"eth","Type",2048,"ip",ipDecoderHandle)

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

packets = pcapReaderObj.readAll()

packets=1×35 struct array with fields:
    SNo
    Timestamp
    LinkType
    Protocol
    PacketLength
    Packet
    RawBytes

Input Arguments

pcap — PCAP file reader

pcapReader object

PCAP file reader, specified as a pcapReader object.

protocolName — Name of existing protocol decoder

character vector | string scalar

Name of the existing protocol decoder, specified as a character vector or a string scalar. The existing protocol decoder can be an Ethernet decoder, an eCPRI decoder, or any other newly added protocol decoder.

Data Types: char | string

fieldName — Field name in output structure of existing protocol decoder

character vector | string scalar

Field name in the output structure of the existing protocol decoder, specified as a character vector or a string scalar. For more information about the field names of Ethernet and eCPRI protocol decoders, see the protocolPackets output of the read or readAll object functions.

Data Types: char | string

fieldValue — Value of field name

nonnegative integer | character vector | string scalar

Value of the field name, specified as a nonnegative integer, character vector, or string scalar. If the fieldName input has this value, then this object function passes the payload to the upper-layer protocol decoder handle.

Data Types: double | char | string

upperLayerProtocolName — Name of upper-layer protocol decoder

character vector | string scalar

Name of the upper-layer protocol decoder, specified as a character vector or a string scalar. To store the decoded packet of the upper-layer protocol decoder, the read or readAll object functions use this value to create a new field in the Packet field of the output decoded protocol packet structure.

Data Types: char | string

upperLayerDecoder — Upper-layer protocol decoder

function handle

Upper-layer protocol decoder that decodes the payload of the existing protocol decoder and returns the decoded packet with the processed length, specified as a function handle. This code shows the syntax of this argument.

[outputPacket,processedLength] = upperLayerDecoderFunction(existingProtocolPayload);
upperLayerDecoder = @upperLayerDeocderFunction

The upperLayerDecoderFunction is the function that decodes the payload of the existing protocol decoder. The outputPacket output contains the decoded packet as a structure or a cell array of structures. The processedLength output is the number of decoded bytes. A negative value of the processed length indicates failed packet decoding. If packet decoding fails, the output decoded packet structure is empty.

Data Types: function_handle

protocolFields — Protocol fields and data types

two-column cell array

Protocol fields and data types, specified as a two-column cell array that indicates the protocol fields and their respective data types. Specify these fields and data types as character vectors or string scalars. The first column of the cell array specifies the field name. The second column of the cell array specifies the data type of the corresponding field name. The valid values for the data type are numeric, string, and hexadecimal. This value specifies the fields (of the protocol decoder output structure) on which the read or readAll object functions can specify the packetFilter input. When you specify the packetFilter input of read or readAll object functions, this object function uses the protocolFields value for:

• Tab completion of packetFilter string

• Validating packetFilter string

For more information about how to use this value to filter packets, see the packetFilter input of the read or readAll object functions.

Data Types: cell

References

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

Version History

Introduced in R2021b