Main Content

addLinkTypeDecoder

Add custom link layer protocol decoder to PCAP file reader

Since R2021b

collapse all in page

    Syntax

    addLinkTypeDecoder(pcap,linkType,linkName,protocolDecoder)
    addLinkTypeDecoder(pcap,linkType,linkName,protocolDecoder,protocolFields)

    Description

    You can use the addLinkTypeDecoder object function to plug in a custom link layer protocol decoder to the pcapReader object based on the link type of the packet capture (PCAP) global header. For example, to add a Bluetooth low energy (LE) link layer decoder for decoding Bluetooth LE link layer packets, specify the link type as 251. For information on link layer header types and the corresponding link type values, see Tcpdump/Libpcap Public Repository [1].

    example

    addLinkTypeDecoder(pcap,linkType,linkName,protocolDecoder) adds a custom link layer protocol decoder function handle, protocolDecoder, to the PCAP file reader, pcap, based on the link type of the PCAP global header, linkType. The linkName input specifies a name for the link type.

    addLinkTypeDecoder(pcap,linkType,linkName,protocolDecoder,protocolFields) additionally specifies protocol fields to filter packets based on the specified fields of the protocol decoder output.

    Examples

    collapse all

    Open Live Script

    Create a protocol decoder function handle for decoding Bluetooth LE link layer packets.

    bleDecoderHandle = @decodeBLEPacket;

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

    pcapReaderObj = pcapReader('blePackets.pcap');

    Add the Bluetooth LE link layer decoder to the PCAP file reader.

    addLinkTypeDecoder(pcapReaderObj,251,'ble',bleDecoderHandle, ...
    {'AccessAddress','hexadecimal'});

    Display the Bluetooth LE link layer decoder.

    pcapReaderObj.LinkTypeDecoders(end)
    ans = struct with fields:
    ProtocolName: 'ble'
        LinkType: 251
         Decoder: @decodeBLEPacket

    Read all of the Bluetooth LE link layer packets from the PCAP file to the MATLAB® workspace.

    blePackets = readAll(pcapReaderObj)
    blePackets=1×15 struct array with fields:
    SNo
    Timestamp
    LinkType
    Protocol
    PacketLength
    Packet
    RawBytes

    Display the decoded Bluetooth LE link layer packet structure.

    blePackets(1).Packet
    ans = struct with fields:
    ble: [1x1 struct]

    Reset the position of the PCAP file reader to the first packet of the PCAP file.

    reset(pcapReaderObj);

    Read the Bluetooth LE link layer packets that match the filter criteria.

    blePackets = readAll(pcapReaderObj,'ble.AccessAddress == 8E89BED6')
    blePackets=1×13 struct array with fields:
    SNo
    Timestamp
    LinkType
    Protocol
    PacketLength
    Packet
    RawBytes

    Display the decoded Bluetooth LE link layer packet structure.

    blePackets(1).Packet
    ans = struct with fields:
    ble: [1x1 struct]

    Input Arguments

    collapse all

    PCAP file reader, specified as a pcapReader object.

    Link type in the PCAP global header, specified as a nonnegative integer. If the link type in the PCAP file matches the specified link type value, the read or readAll object functions calls the decoder function handle.

    Data Types: double

    Link layer protocol decoder name, specified as a character vector or a string scalar. To store the decoded packet of the link 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

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

    [outputPacket,processedLength] = linkTypeDecoderFunction(payload);
protocolDecoder = @linkTypeDeocderFunction
    The linkTypeDecoderFunction is the function that decodes the payload. The outputPacket output contains the decoded packet as a structure. 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

    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. 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

    See Also

    Objects

    Functions