Base Protocol

pcapkit.protocols.transport.transport contains Transport, which is a base class for transport layer protocols, eg. TCP, UDP and SCTP.

class pcapkit.protocols.transport.transport.Transport(file=None, length=None, **kwargs)

Bases: ProtocolBase[_PT, _ST], Generic[_PT, _ST]

Abstract base class for transport layer protocol family.

property layer: Literal['Transport']

Protocol layer.

classmethod register(code, protocol)

Register a new protocol class.

Notes

The full qualified class name of the new protocol class should be as {protocol.module}.{protocol.name}.

Parameters:

• code (int) – port number

• protocol (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module descriptor or a Protocol subclass

Important

This method must be called from a non-abstract class, as the protocol map should be associated directly with specific transport layer protocol type.

Raises:

• pcapkit.utilities.exceptions.UnsupportedCall – If called on Transport itself.

• pcapkit.utilities.exceptions.RegistryError – If protocol is not a class, or not a Protocol subclass.

Warns:

pcapkit.utilities.warnings.RegistryWarning – If this port is already registered and the incumbent differs from the replacement; the message names both. An unresolved ModuleDescriptor counts as different from the class it names. See ProtocolBase.register for the guard this shares with register_protocol, and for the shipped descriptor a restore puts back (#1504).

Note

TCP and UDP each define their own __proto__ rather than sharing one on Transport. register_apptype reaches this method once per protocol and inspects two different registries, so it cannot warn spuriously.

Changed in version 1.3.0: Takes the protocol as one protocol argument, a ModuleDescriptor or a Protocol subclass, in place of the module and class_ names.

classmethod analyze(ports, payload, **kwargs)

Analyse packet payload.

Parameters:

• ports (tuple[int, int]) – Source & destination port numbers.

• payload (bytes) – Packet payload.

• **kwargs (Any) – Arbitrary keyword arguments.

Return type:

ProtocolBase

Returns:

Parsed payload as a Protocol instance.

classmethod from_data(data, **kwargs)

Create protocol instance from data.

Parameters:

• data (TypeVar(_PT, bound= Data) | dict[str, Any]) – Protocol data.

• **kwargs (Any) – Construction keywords, as for ProtocolBase.from_data.

Return type:

Self

Returns:

Protocol instance, cut back to what was captured when the header it was parsed from was cut short (#1458).

__post_init__(file=None, length=None, **kwargs)

Post initialisation hook.

Parameters:

• file (IO[bytes] | bytes | None) – Source packet stream.

• length (int | None) – Length of packet data.

• **kwargs (Any) – Arbitrary keyword arguments.

Notes

A header the data ends inside keeps that in its info, so that from_data() rebuilds only what was captured (#1458).

static _make_port(port, proto)

Resolve a port number to its application type.

Parameters:

• port (AppType | int) – port number, or the application type itself

• proto (TransportProtocol) – transport protocol the port belongs to, which is what distinguishes e.g. TCP/80 from UDP/80

Return type:

AppType

Returns:

The AppType for port.

Important

self.make accepts a bare int for a port, but the schema field converts it only on the way out (in PortEnumField.pre_process), so the schema attribute keeps whatever it was handed. Normalising here makes a constructed packet carry the same AppType as a parsed one, so reading .port off it works on both paths.

_decode_next_layer(dict_, ports, length=None, *, packet=None)

Decode next layer protocol.

The next layer is looked up by port number. The lower of the two ports is the primary key; the higher one is used only when it alone is registered.

Parameters:

• dict_ (TypeVar(_PT, bound= Data)) – info buffer

• ports (tuple[int, int]) – source & destination port numbers

• length (int | None) – valid (non-padding) length

• packet (dict[str, Any] | None) – packet info (passed from self.unpack)

Return type:

TypeVar(_PT, bound= Data)

Returns:

Current protocol with next layer extracted.

Important

The port is forwarded whether or not it is registered: ProtocolBase._import_next_layer passes it on as alias and Raw records it as Data_Raw.protocol. Dropping it would make a payload on a port we do not decode indistinguishable from one on port 22. The lower port is the one carried, for the same reason it is the primary lookup key. SCTP._decode_next_layer and Internet._import_next_layer behave the same way for an unregistered PPID and transport type.

__layer__: Literal['Transport']

Layer of protocol.

__proto__: DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]

Protocol index mapping for decoding next layer, c.f. self._decode_next_layer & self._import_next_layer.

Important

The attribute must be defined and maintained in subclass.