write

Write protocol packet data to PCAP or PCAPNG file

collapse all in page

    Syntax

    write(pcapObj,packet,timestamp)
    write(pcapngObj,packet,timestamp,interfaceID)
    write(___,Name,Value)

    Description

    write(pcapObj,packet,timestamp) writes the protocol packet data to the PCAP file specified in the PCAP file writer object, pcapObj. Input packet specifies the protocol packet and input timestamp specifies the packet arrival time.

    write(pcapngObj,packet,timestamp,interfaceID) writes protocol packet data to a PCAPNG file specified in the PCAPNG file writer object, pcapngObj. Input packet, timestamp, and interfaceID specifies the protocol packet, packet arrival time, and interface identifier, respectively.

    example

    write(___,Name,Value) specifies options using one or more name-value pair arguments in addition to the input argument combinations from any of the previous syntaxes. For example, 'PacketFormat','bits' sets the format of the protocol packets to bits.

    Examples

    collapse all

    This example uses:

    Open Live Script

    Create a PCAP file writer object, specifying the name of the PCAP file. Specify the Bluetooth low energy (BLE) link type.

    pcapObj = pcapWriter('FileName','writeBLEpacket');
bleLinkType = 251;

    Write a global header to the PCAP file.

    writeGlobalHeader(pcapObj,bleLinkType);

    Specify the BLE link layer (LL) packet.

    llpacket = '42BC13E206120E00050014010A001F0040001700170000007D47C0';

    Write BLE LL packet to the PCAP file.

    timestamp = 129100; % Number of microseconds
write(pcapObj,llpacket,timestamp);

    This example uses:

    Open Live Script

    Create a PCAPNG file writer object, specifying the name of the PCAPNG file.

    pcapngObj = pcapngWriter('FileName','writeBLEpacket');

    Write an interface description block for BLE.

    interfaceName = 'BLE interface';
bleLinkType = 251;
interfaceId = writeInterfaceDescriptionBlock(pcapngObj,bleLinkType, ...
    interfaceName);

    Specify the BLE LL packet.

    llpacket = '42BC13E206120E00050014010A001F0040001700170000007D47C0';

    Write BLE LL packet to the PCAPNG format file.

    timestamp = 0; % Number of microseconds
packetComment = 'This is BLE packet';
write(pcapngObj, llpacket,timestamp,interfaceId,'PacketComment', ...
    packetComment);

    Input Arguments

    collapse all

    Note

    The pcapWriter and pcapngWriter objects do not overwrite the existing PCAP or PCAPNG files, respectively. During each call of these objects, specify a unique PCAP or PCAPNG file name.

    PCAP file writer object, specified as a pcapWriter object.

    Protocol packet, specified as one of these values.

    • Binary-valued vector – This value represents bits.

    • Character vector – This value represents octets in hexadecimal format.

    • String scalar – This value represents octets in hexadecimal format.

    • Numeric vector with each element in the range [0, 255] – This value represents octets in decimal format.

    • n-by-2 character array – In this value, each row represents an octet in hexadecimal format .

    Data Types: char | string | double

    Packet arrival time since 1/1/1970, specified as a nonnegative integer. This value must be expressed in microseconds.

    Data Types: double

    PCAPNG file writer object, specified as a pcapngWriter object.

    Unique identifier for an interface, specified as a nonnegative scalar.

    Data Types: double

    Name-Value Pair Arguments

    Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

    Example: 'PacketFormat','bits' sets the format of the protocol packets to bits.

    Format of the protocol packet, specified as the comma-separated pair consisting of PacketFormat and 'octets' or 'bits'. If this value is specified as 'octets', packet is specified as one of these values.

    • Binary-valued vector – This value represents bits.

    • Character vector – This value represents octets in hexadecimal format.

    • String scalar – This value represents octets in hexadecimal format.

    • Numeric vector with each element in the range [0, 255] – This value represents octets in decimal format.

    • n-by-2 character array – In this value, each row represents an octet in hexadecimal format .

    Data Types: char | string | double

    Comment for the protocol packet, specified as the comma-separated pair consisting of PacketComment and a character vector or a string scalar.

    Dependencies

    To enable this name-value pair argument, specify the pcapngObj input argument.

    Data Types: char | string

    References

    [1] Tuexen, M. “PCAP Next Generation (Pcapng) Capture File Format.” 2020. https://www.ietf.org/.

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

    [3] “Development/LibpcapFileFormat - The Wireshark Wiki.” Accessed May 20, 2020. https://www.wireshark.org/.

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    See Also

    Functions

    Objects

    Introduced in R2020b

    Communications Toolbox Documentation

    Support