Frame Header *

pcapkit.protocols.pcap.frame contains Frame only, which implements extractor for frame headers of PCAP, whose structure is described as below:

typedef struct pcaprec_hdr_s {
    guint32 ts_sec;     /* timestamp seconds */
    guint32 ts_usec;    /* timestamp microseconds */
    guint32 incl_len;   /* number of octets of packet saved in file */
    guint32 orig_len;   /* actual length of packet */
} pcaprec_hdr_t;

class pcapkit.protocols.pcap.frame.Frame(file=None, length=None, **kwargs)[source]

Bases: pcapkit.protocols.protocol.Protocol

Per packet frame header extractor.

__proto__: DefaultDict[int, Tuple[str, str]]

Protocol index mapping for decoding next layer, c.f. self._decode_next_layer & self._import_next_layer. The values should be a tuple representing the module name and class name.

Code

Module

Class

1

pcapkit.protocols.link.ethernet

Ethernet

228

pcapkit.protocols.link.internet.ipv4

IPv4

229

pcapkit.protocols.link.internet.ipv6

IPv6
__contains__(name)[source]

Returns if name is in self._info or in the frame packet self._protos.

Parameters

name (Any) – name to search

Returns

if name exists

Return type

bool

__getitem__(key)[source]

Subscription (getitem) support.

This method fist checks if key exists in self._info. If so, returns the corresponding value, else calls the original __getitem__() method.

Parameters

key (Union[str, Protocol, Type[Protocol]]) – Indexing key.

Returns

  • If key exists in self._info, returns the value of the key;

  • else returns the sub-packet from the current packet of indexed protocol.

__index__()[source]

Index of the protocol.

Returns

If the object is initiated, i.e. self._fnum exists, returns the frame index number of itself; else raises UnsupportedCall.

Return type

int

Raises

UnsupportedCall – This protocol has no registry entry.

__length_hint__()[source]

Return an estimated length for the object.

Return type

Literal[16]

__post_init__(file=None, length=None, *, num, proto, nanosecond, **kwargs)[source]

Initialisation.

Parameters

  • file (Optional[io.BytesIO]) – Source packet stream.

  • length (Optional[int]) – Length of packet data.

Keyword Arguments

  • num (int) – Frame index number (self._fnum).

  • proto (pcapkit.const.reg.linktype.LinkType) – Next layer protocol index (self._prot).

  • nanosecond (bool) – Nanosecond-timestamp PCAP flag (self._nsec).

  • mpfdp (multiprocessing.Queue) – Multiprocessing file descriptor queue (self._mpfp).

  • mpkit (multiprocessing.Namespace) – Multiprocessing auxiliaries (self._mpkt).

  • **kwargs – Arbitrary keyword arguments.

For multiprocessing related parameters, please refer to pcapkit.foundation.extration.Extrator for more information.

See also

For construction argument, please refer to make().

_decode_next_layer(data, length=None)[source]

Decode next layer protocol.

Positional arguments:

data (dict): info buffer length (int): valid (non-padding) length

Returns

current protocol with packet extracted

Return type

dict

_import_next_layer(proto, length, error=False)[source]

Import next layer extractor.

This method currently supports following protocols as registered in LinkType:

proto

Protocol

1

Ethernet

228

IPv4

229

IPv6
Parameters
Keyword Arguments

error (bool) – if function called on error

Returns

instance of next layer

Return type

pcapkit.protocols.protocol.Protocol

_make_timestamp(**kwargs)[source]

Make timestamp.

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Returns

Second and microsecond/nanosecond value of timestamp.

Return type

Tuple[int, int]

index(name)[source]

Call ProtoChain.index.

Parameters

name (Union[str, Protocol, Type[Protocol]]) – name to be searched

Returns

first index of name

Return type

int

Raises

IndexNotFound – if name is not present

make(**kwargs)[source]

Make frame packet data.

Keyword Arguments

  • timestamp (float) – UNIX-Epoch timestamp

  • ts_sec (int) – timestamp seconds

  • ts_usec (int) – timestamp microseconds

  • incl_len (int) – number of octets of packet saved in file

  • orig_len (int) – actual length of packet

  • packet (bytes) – raw packet data (default: b'')

  • nanosecond (bool) – nanosecond-resolution file flag (default: False)

  • **kwargs – Arbitrary keyword arguments.

Returns

Constructed packet data.

Return type

bytes

read(length=None, **kwargs)[source]

Read each block after global header.

Parameters

length (Optional[int]) – Length of packet data.

Keyword Arguments

**kwargs – Arbitrary keyword arguments.

Returns

Parsed packet data.

Return type

DataType_Frame

Raises

EOFError – If self._file reaches EOF.

property length

Header length of corresponding protocol.

Return type

Literal[16]

property name

Name of corresponding protocol.

Return type

str

Data Structure

Important

Following classes are only for documentation purpose. They do NOT exist in the pcapkit module.

class pcapkit.protocols.pcap.frame.DataType_Frame
Bases

TypedDict

PCAP frame header.

frame_info: DataType_FrameInfo

PCAP frame information

time: datetime.datetime

timestamp

number: int

frame index number

time_epoch: float

EPOCH timestamp

len: int

captured packet length

cap_len: int

actual packet length

packet: bytes

packet raw data

protocols: pcapkit.corekit.protochain.ProtoChain

protocol chain

error: typing.Optional[str]

error message (optional)

class pcapkit.protocols.pcap.frame.DataType_FrameInfo
Bases

TypedDict

Frame information.

ts_sec: int

timestamp seconds

ts_usec: int

timestamp microseconds/nanoseconds

incl_len: int

number of octets of packet saved in file

orig_len: int

actual length of packet

*

https://wiki.wireshark.org/Development/LibpcapFileFormat#Record_.28Packet.29_Header