Registry Management¶

pcapkit.foundation.registry holds the registration functions for pcapkit’s engines, dumpers, callbacks and protocols.

A code the shipped enumerations do not define can still be registered: most constant enumerations return a member-like object for an in-range unknown value rather than rejecting it (see Unrecognised Values), so a newly assigned number needs no regeneration.

Foundation Registries¶

Changed in version 1.5.0: NULL, the default of every class_ argument here, is now the pcapkit.corekit.sentinels.NULL sentinel; in 1.4.x it was the string '(null)' (#833).

Engine Registries¶

pcapkit.foundation.registry.foundation.register_extractor_engine(name, module, class_=NULL)[source]¶

Overloads:

name (str), module (ModuleDescriptor[Engine] | Type[Engine]) → None
name (str), module (str), class_ (str) → None

Notes

The fully qualified class name of the new engine class should be {module}.{class_}.

The function will register the given engine class to the pcapkit.foundation.extraction.Extractor.__engine__ registry.

Parameters:

name (str) – engine name
module (ModuleDescriptor[Engine] | Type[Engine] | str) – module name or module descriptor or an Engine subclass (a class deriving only from EngineBase is refused: that is the base for pcapkit’s own engines, unless it is the engine name shipped with, which restores it)
class_ (str | NullType) – class name

Changed in version 1.3.0: The engine name, which was engine, is name, with no alias.

Dumper Registries¶

pcapkit.foundation.registry.foundation.register_dumper(format, module, class_=NULL, *, ext)[source]¶

Overloads:

format (str), module (ModuleDescriptor[dictdumper.dumper.Dumper] | Type[dictdumper.dumper.Dumper]), *, ext (str) → None
format (str), module (str), class_ (str), *, ext (str) → None

Notes

The fully qualified class name of the new dumper class should be {module}.{class_}.

The function will register the given dumper class to the pcapkit.foundation.traceflow.traceflow.TraceFlow.__output__ and pcapkit.foundation.extraction.Extractor.__output__ registries.

Parameters:

format (str) – format name
module (ModuleDescriptor[dictdumper.dumper.Dumper] | Type[dictdumper.dumper.Dumper] | str) – module name or module descriptor or a Dumper subclass
class_ (str | NullType) – class name
ext (str) – file extension

Callback Registries¶

pcapkit.foundation.registry.foundation.register_reassembly_ipv4_callback(callback)[source]¶

The function will register the given callback function to the IPv4.__callback_fn__ registry.

Parameters:: callback (Callable[[List[_DT]], None]) – callback function

pcapkit.foundation.registry.foundation.register_reassembly_ipv6_callback(callback)[source]¶

The function will register the given callback function to the IPv6.__callback_fn__ registry.

Parameters:: callback (Callable[[List[_DT]], None]) – callback function

pcapkit.foundation.registry.foundation.register_reassembly_tcp_callback(callback)[source]¶

The function will register the given callback function to the TCP.__callback_fn__ registry.

Parameters:: callback (Callable[[List[_DT]], None]) – callback function

pcapkit.foundation.registry.foundation.register_traceflow_tcp_callback(callback)[source]¶

The function will register the given callback function to the TCP.__callback_fn__ registry.

Parameters:: callback (Callable[[_IT], None]) – callback function

Extractor Registries¶

pcapkit.foundation.registry.foundation.register_extractor_reassembly(protocol, module, class_=NULL)[source]¶

Overloads:

protocol (str), module (ModuleDescriptor[Reassembly] | Type[Reassembly]) → None
protocol (str), module (str), class_ (str) → None

Notes

The fully qualified class name of the new reassembly class should be {module}.{class_}.

The function will register the given reassembly class to the pcapkit.foundation.extraction.Extractor.__reassembly__ registry.

Parameters:

protocol (str) – protocol name
module (str | ModuleDescriptor[Reassembly] | Type[Reassembly]) – module name or module descriptor or a Reassembly subclass (a class deriving only from ReassemblyBase is refused: that is the base for pcapkit’s own classes, unless it is the class protocol shipped with, which restores it)
class_ (str | NullType) – class name

pcapkit.foundation.registry.foundation.register_extractor_traceflow(protocol, module, class_=NULL)[source]¶

Overloads:

protocol (str), module (ModuleDescriptor[TraceFlow] | Type[TraceFlow]) → None
protocol (str), module (str), class_ (str) → None

Notes

The fully qualified class name of the new flow tracing class should be {module}.{class_}.

The function will register the given flow tracing class to the pcapkit.foundation.extraction.Extractor.__traceflow__ registry.

Parameters:

protocol (str) – protocol name
module (str | ModuleDescriptor[TraceFlow] | Type[TraceFlow]) – module name or module descriptor or a TraceFlow subclass (a class deriving only from TraceFlowBase is refused: that is the base for pcapkit’s own classes, unless it is the class protocol shipped with, which restores it)
class_ (str | NullType) – class name

Protocol Registries¶

pcapkit.foundation.registry.protocols is a package of one submodule per layer of pcapkit.protocols, beside protocol for the registries the others build on. Every function below is exported by the package, and by pcapkit.foundation.registry, as well as by its own submodule.

Changed in version 1.5.0: NULL, the default of every class_ argument here, is now the pcapkit.corekit.sentinels.NULL sentinel; in 1.4.x it was the string '(null)' (#833).

Changed in version 1.6.0: A package of per-layer submodules rather than a single module (#2578).

pcapkit.foundation.registry.protocols.protocol.register_protocol(protocol)[source]¶

The protocol class must be a subclass of ProtocolBase, and will be registered to the by-name registry ProtocolBase.__registry__ through ProtocolBase.register_protocol, replacing the entry its name holds.

The registry is keyed on protocol.__name__.upper(), which nothing makes unique: two protocol classes of the same name, such as a user’s class named after a shipped one, compete for one key. Defining the second as a Protocol subclass keeps the first, and registering it here replaces whichever was there, and the replacement is observable through every reader of the registry, e.g. Protocol.expand_comp, which resolves a bare protocol name through it. Per #675 the overwrite is reported, matching Protocol.register and the other overwrite-warning registries.

The guard reads “key present and incumbent is a different class” – presence alone is not enough. This registry’s key is derived from the class rather than supplied by a caller, and this function is the funnel every wrapper registrar calls – register_tcp(), register_udp(), register_apptype(), register_linktype() and the rest all end by calling it with their class, and registering their code back undoes that call’s write (#1505). So registering one class under two codes, a supported and documented thing to do, reaches this function twice with the same class and nothing at stake; a presence-only guard would warn about an overwrite that overwrote nothing. Warning on the harmless case is not free: it teaches a caller to filter RegistryWarning wholesale, and that filter would then hide the name collision this warning exists to surface. The sibling register methods across the package, each keyed on a caller-supplied code, apply the same identity criterion (#718). A built-in’s ModuleDescriptor entry is the class it names for that criterion.

Making the key itself unique would resolve the collision rather than merely reporting it, but it is a registry-format change that the bare-name readers outside this module cannot absorb on their own – the registry is a documented public attribute, and its readers look a bare name up and then degrade silently on a miss rather than raising, so a re-keying would not announce itself either. Protocol.expand_comp falls back to the name as a plain string, and the protocol properties on ReassemblyMeta and TraceFlowMeta fall back to Raw. The registry redesign of #514 keeps this key, and its thread records the shared namespace as a risk that design does not resolve, so the collision is reported here rather than fixed.

Parameters:: protocol (Type[ProtocolBase]) – Protocol class.
Raises:: pcapkit.utilities.exceptions.RegistryError – If protocol is not a ProtocolBase subclass.
Warns:: pcapkit.utilities.warnings.RegistryWarning – If the registry already holds a different class under this protocol’s name, i.e. the registration displaced another protocol class. Re-registering the same class under the same name is silent.

Changed in version 1.6.0: The HTTP member classes are named HTTPv1 and HTTPv2, so registering one keeps its own key and no longer displaces HTTP under 'HTTP' (#2529). The registry is ProtocolBase.__registry__, written by ProtocolBase.register_protocol, where it was pcapkit.protocols.__proto__ (#2763).

pcapkit.foundation.registry.protocols.protocol.register_protocol_code(protocol, code)[source]¶

This is what backs the code class keyword of ProtocolBase subclasses; it can also be called directly to register a class that declined at class-definition time.

code is normalised into a flat sequence of targets, where each item is either:

an enum member, whose type names the class(es) owning the matching __proto__ in its __proto_dest__ – EtherType to Link, TransType to Internet, PayloadProtocolIdentifier to SCTP, ARPHRD to LinuxSLL, and LinkType to both Frame and PCAPNG; or
a dict mapping an explicit destination class to a key – the only form accepted for a bare int, since e.g. a port number does not say by itself whether it means TCP or UDP;

or an iterable of either, to register protocol into several registries from one call – e.g. a L2TP subclass reachable both by its IP protocol number and by a UDP port:

register_protocol_code(L2TPv3, [TransType.L2TP, {UDP: 1701}])

The explicit mapping form is accepted for any key, even one whose type could be inferred – being more explicit than required is never an error.

Note

That example names L2TPv3, which this package does not implement, rather than L2TPv2. It is v3 that is genuinely reachable both ways: RFC 3931 §4.1.1 puts it directly over IP on protocol 115 and §4.1.2 puts it over UDP on port 1701. L2TPv2 answers on port 1701 only, and registering it at TransType.L2TP would point the RFC 2661 parser at a v3-over-IP header – see L2TP and GitHub issue #548 for what that produced when measured.

Parameters:

protocol (Type[ProtocolBase]) – Protocol class to register.
code (Any) – Registration key(s); see above.

Raises:

RegistryError – If a bare int (or any other non-enum, non-mapping value) is given without an explicit destination, or if an enum member’s type declares no __proto_dest__ – inference refuses rather than guesses; or if a key is not of the type its destination’s registry is keyed by, as its typed registrar would reject it, e.g. {Frame: TransType.ICMP}. What a registry is keyed by is read from the __proto_key__ declared by the class owning it, so a destination sharing another’s registry is checked as its owner is, and one whose owner declares no pairing is not checked. Every target is checked before any is registered, so a rejected code leaves every registry as it was (#2268).

Top-Level Registries¶

These are in misc with the PCAP-NG registries below, as Frame and PCAPNG are in pcapkit.protocols.misc.

pcapkit.foundation.registry.protocols.misc.register_linktype(code, module, class_=NULL)[source]¶

Overloads:

code (LinkType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (LinkType), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the following registries:

Parameters:

code (LinkType) – protocol code as in LinkType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Link Layer Registries¶

pcapkit.foundation.registry.protocols.link.register_ethertype(code, module, class_=NULL)[source]¶

Overloads:

code (EtherType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (EtherType), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.link.Link.__proto__ registry.

Parameters:

code (EtherType) – protocol code as in EtherType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Raises:

RegistryError – If code is not a EtherType member, e.g. a member of another enum, or module is not a ProtocolBase subclass.

pcapkit.foundation.registry.protocols.link.register_loopback(code, module, class_=NULL)[source]¶

Overloads:

code (int), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (int), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.loopback.protocol.Loopback.__proto__ registry.

Parameters:

code (int) – BSD address family
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Important

Unlike register_ethertype(), code is an address family, not an EtherType: Loopback keeps a registry of its own.

Raises:: RegistryError – If code is not an int (a bool is not accepted, even though it is one), or is a member of an enum, or module is not a ProtocolBase subclass.

Added in version 1.6.0.

pcapkit.foundation.registry.protocols.link.register_arphrd(code, module, class_=NULL)[source]¶

Overloads:

code (ARPHRD), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (ARPHRD), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.linux_sll.protocol.LinuxSLL.__proto__ registry, so that a Linux “cooked” capture on that arphrd_type dispatches to it instead of reading protocol_type as an EtherType.

Parameters:

code (ARPHRD) – ARP hardware type as in ARPHRD
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Raises:

RegistryError – If code is not a ARPHRD member, e.g. a member of another enum, or module is not a ProtocolBase subclass.

pcapkit.foundation.registry.protocols.link.register_frad(code, module, class_=NULL)[source]¶

Overloads:

code (int), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (int), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.frad.protocol.FRAD.__proto__ registry.

Parameters:

code (int) – NLPID, after resolving the 0x00 pad ahead of a SNAP header
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Raises:

RegistryError – If code is not an int (a bool is not accepted, even though it is one), or is a member of an enum.

pcapkit.foundation.registry.protocols.link.register_netlink(code, module, class_=NULL)[source]¶

Overloads:

code (int), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (int), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.netlink.protocol.Netlink.__proto__ registry.

Parameters:

code (int) – nlmsg_type of the dissected message
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Raises:

RegistryError – If code is not an int (a bool is not accepted, even though it is one), or is a member of an enum.

pcapkit.foundation.registry.protocols.link.register_radiotap(code, module, class_=NULL)[source]¶

Overloads:

code (LinkType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (LinkType), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.link.radiotap.protocol.Radiotap.__proto__ registry, keyed by the link type of the frame a radiotap header precedes. Any link type is accepted, but Radiotap.read consults LinkType.IEEE802_11 alone: registering that key replaces the 802.11 dissector, and an entry under any other key is stored and never reached.

Parameters:

code (LinkType) – link type as in LinkType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Raises:

RegistryError – If code is not a LinkType member, e.g. a member of another enum, or module is not a ProtocolBase subclass.

pcapkit.foundation.registry.protocols.link.register_radiotap_field(code, meth, *, schema=None)[source]¶

The function will register the given field parser to the pcapkit.protocols.link.radiotap.protocol.Radiotap.__field__ registry. A field type is decoded once both it and the schema registry hold an entry for it. A presence bit 28 to 30 follows rules of its own, as does a vendor namespace TLV item, so an entry for one is stored and not reached there; a type from 32 on is reached only as a TLV item.

Parameters:

code (FieldType) – Radiotap field type as in FieldType.
meth (str | tuple[Callable[[FieldType, RadiotapField], RadiotapField], Callable[[FieldType, RadiotapField | Mapping[str, Any]], RadiotapField]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the field. A name names the _read_field_* and _make_field_* methods, and has to name an existing _read_field_* one.
schema (Type[RadiotapField] | None) – Schema class for the field, whose fields are its subfields and whose __align__ is its alignment. It should be a subclass of pcapkit.protocols.link.radiotap.schema.RadiotapField.

Raises:

RegistryError – If code is not a FieldType member, e.g. a member of another enum, or meth is a name with no matching _read_field_* method.

Return type:

None

Added in version 1.6.0.

Internet Layer Registries¶

pcapkit.foundation.registry.protocols.internet.register_transtype(code, module, class_=NULL)[source]¶

Overloads:

code (TransType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (TransType), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.internet.internet.Internet.__proto__ registry.

Parameters:

code (TransType) – protocol code as in TransType
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Raises:

RegistryError – If code is not a TransType member, e.g. a member of another enum, or module is not a ProtocolBase subclass.

pcapkit.foundation.registry.protocols.internet.register_ipx(code, module, class_=NULL)[source]¶

Overloads:

code (int | Packet), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) → None
code (int | Packet), module (str), class_ (str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.internet.ipx.protocol.IPX.__proto__ registry.

Parameters:

code (int | Packet) – IPX Packet Type, as in Packet
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | NullType) – class name

Important

Unlike register_transtype(), code is an IPX Packet Type, not an IP protocol number: IPX keeps a registry of its own (#2169).

Raises:: RegistryError – If code is neither an int (a bool is not accepted, even though it is one) nor a Packet member, e.g. a TransType member, or module is not a ProtocolBase subclass.

Added in version 1.6.0.

pcapkit.foundation.registry.protocols.internet.register_ipv4_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.ipv4.protocol.IPv4.__option__ registry.

Parameters:

code (OptionNumber) – IPv4 option code as in OptionNumber.
meth (str | tuple[Callable[[Option, OrderedMultiDict[OptionNumber, Option]], Option], Callable[[OptionNumber, Option | None, Any], Option]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the option. A name names the _read_opt_* and _make_opt_* methods, and has to name an existing _read_opt_* one.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.internet.ipv4.schema.Option.

Raises:

RegistryError – If code is not a OptionNumber member, e.g. a member of another enum, or meth is a name with no matching _read_opt_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_icmp_type(code, meth)[source]¶

The function will register the given message body parser to the __type__ registry when code is an ICMPv4 type, or to __type__ when it is an ICMPv6 type. Each registry is written by that class’s own register_type() classmethod.

Parameters:

code (Type | Type) – ICMP type as in Type or Type.
meth (str | tuple[Callable[..., Any], Callable[..., Any]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the message body. A name names the _read_data_type_* and _make_data_type_* methods of the protocol, and has to name an existing _read_data_type_* one.

Raises:

RegistryError – If code is not a member of either ICMP type enum, or meth is a name with no matching _read_data_type_* method.

pcapkit.foundation.registry.protocols.internet.register_hip_parameter(code, meth, *, schema=None)[source]¶

The function will register the given parameter parser to the pcapkit.protocols.internet.hip.protocol.HIP.__parameter__ registry.

Parameters:

code (Parameter) – HIP parameter code as in Parameter.
meth (str | tuple[Callable[[Parameter, int, OrderedMultiDict[Parameter, Parameter]], Parameter], Callable[[Parameter, Parameter | None, int, Any], Parameter]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the parameter. A name names the _read_param_* and _make_param_* methods, and has to name an existing _read_param_* one.
schema (Type[Parameter] | None) – Schema class for the parameter. It should be a subclass of pcapkit.protocols.internet.hip.schema.Parameter.

Raises:

RegistryError – If code is not a Parameter member, e.g. a member of another enum, or meth is a name with no matching _read_param_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_hopopt_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.hopopt.protocol.HOPOPT.__option__ registry.

Parameters:

code (Option) – HOPOPT option code as in Option.
meth (str | tuple[Callable[[Option, OrderedMultiDict[Option, Option]], Option], Callable[[Option, Option | None, Any], Option]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the option. A name names the _read_opt_* and _make_opt_* methods, and has to name an existing _read_opt_* one.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.internet.hopopt.schema.Option.

Raises:

RegistryError – If code is not a Option member, e.g. a member of another enum, or meth is a name with no matching _read_opt_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_ipv6_opts_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.ipv6_opts.protocol.IPv6_Opts.__option__ registry.

Parameters:

code (Option) – IPv6-Opts option code as in Option.
meth (str | tuple[Callable[[Option, OrderedMultiDict[Option, Option]], Option], Callable[[Option, Option | None, Any], Option]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the option. A name names the _read_opt_* and _make_opt_* methods, and has to name an existing _read_opt_* one.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.internet.ipv6_opts.schema.Option.

Raises:

RegistryError – If code is not a Option member, e.g. a member of another enum, or meth is a name with no matching _read_opt_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_ipv6_route_routing(code, meth, *, schema=None)[source]¶

The function will register the given routing data parser to the pcapkit.protocols.internet.ipv6_route.protocol.IPv6_Route.__routing__ registry.

Parameters:

code (Routing) – IPv6-Route data type code as in Routing.
meth (str | tuple[Callable[[RoutingType, IPv6_Route], IPv6_Route], Callable[[Routing, IPv6_Route | None, IPv6Address | None, Any], RoutingType]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the data. A name names the _read_data_type_* and _make_data_type_* methods, and has to name an existing _read_data_type_* one.
schema (Type[RoutingType] | None) – Schema class for the routing data. It should be a subclass of pcapkit.protocols.internet.ipv6_route.schema.RoutingType.

Raises:

RegistryError – If code is not a Routing member, e.g. a member of another enum, or meth is a name with no matching _read_data_type_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_mh_message(code, meth, *, schema=None)[source]¶

The function will register the given message type parser to the pcapkit.protocols.internet.mh.protocol.MH.__message__ registry.

Parameters:

code (Packet) – MH message type code as in Packet.
meth (str | tuple[Callable[[Packet, MH], MH], Callable[[MH | None, Any], Packet]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the data. A name names the _read_msg_* and _make_msg_* methods, and has to name an existing _read_msg_* one.
schema (Type[Packet] | None) – Schema class for the message type. It should be a subclass of pcapkit.protocols.internet.mh.schema.Packet.

Raises:

RegistryError – If code is not a Packet member, e.g. a member of another enum, or meth is a name with no matching _read_msg_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_mh_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.internet.mh.protocol.MH.__option__ registry.

Parameters:

code (Option) – MH option code as in Option.
meth (str | tuple[Callable[[Option, OrderedMultiDict[Option, Option]], Option], Callable[[Option, Option | None, Any], Option]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the data. A name names the _read_opt_* and _make_opt_* methods, and has to name an existing _read_opt_* one.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.internet.mh.schema.Option.

Raises:

RegistryError – If code is not a Option member, e.g. a member of another enum, or meth is a name with no matching _read_opt_* method.

Return type:

None

pcapkit.foundation.registry.protocols.internet.register_mh_extension(code, meth, *, schema=None)[source]¶

The function will register the given CGA extension parser to the pcapkit.protocols.internet.mh.protocol.MH.__extension__ registry.

Parameters:

code (CGAExtension) – MH CGA extension code as in CGAExtension.
meth (str | tuple[Callable[[CGAExtension, OrderedMultiDict[CGAExtension, CGAExtension]], CGAExtension], Callable[[CGAExtension, CGAExtension | None, Any], CGAExtension]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the data. A name names the _read_ext_* and _make_ext_* methods, and has to name an existing _read_ext_* one.
schema (Type[CGAExtension] | None) – Schema class for the CGA extension. It should be a subclass of pcapkit.protocols.internet.mh.schema.CGAExtension.

Raises:

RegistryError – If code is not a CGAExtension member, e.g. a member of another enum, or meth is a name with no matching _read_ext_* method.

Return type:

None

Changed in version 1.5.0: schema is keyword-only, as in the other register_* functions that take one (#516).

Transport Layer Registries¶

pcapkit.foundation.registry.protocols.transport.register_apptype(code, module, class_=NULL, *transport)[source]¶

Overloads:

code (int), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]), *transport (TransportProtocol | str) → None
code (AppType), module (ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]), *transport (TransportProtocol | str) → None
code (int), module (str), class_ (str), *transport (TransportProtocol | str) → None
code (AppType), module (str), class_ (str), *transport (TransportProtocol | str) → None

Notes

The fully qualified class name of the new protocol class should be {module}.{class_}.

The function will register the given protocol class to the pcapkit.protocols.transport.tcp.protocol.TCP.__proto__ and/or pcapkit.protocols.transport.udp.protocol.UDP.__proto__ registry.

Parameters:

code (int | AppType) – port number
module (str | ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]) – module name or module descriptor or a ProtocolBase subclass
class_ (str | TransportProtocol | NullType) – class name, meaningful only when module is a str. Positional, at the same position as the sibling register_* functions – but unlike them, a third positional argument here is not always class_: which parameter it binds to is decided by type(module) alone, never by what the value looks like. When module is not a str, whatever is given here is treated as the first *transport element instead – prepended, so argument order is preserved – and class_ itself stays unset; register_apptype(80, Unit, TransportProtocol.udp) therefore reaches transport rather than being silently swallowed. This is not a heuristic on the value: with a str module, a str third argument is always a class name – register_apptype(80, 'a.b', 'tcp') registers a class literally named 'tcp' – and naming a transport alongside a str module takes the fourth position onward instead.
*transport (TransportProtocol | str) – transport protocols to register code under, named one at a time, each as a TransportProtocol member or as that member’s name (case-insensitively, e.g. 'tcp', 'TCP' or 'Tcp' alike); the two forms are coerced to the same member and behave identically, including which error they raise. Where none is given and code is an AppType member, the member’s own proto is used, which names exactly the registry the member lives in. A bare int carries no such default and so requires at least one.

Raises:

pcapkit.utilities.exceptions.RegistryError – If code is neither an int (a bool is not accepted, even though it is one) nor an AppType member, e.g. a member of another enum; if no transport protocol is given for a bare int; if one of those given (member or name) names no port-keyed registry; or if a str matches no TransportProtocol member’s name. A composite such as tcp | udp, or its string form 'tcp|udp', names two and is refused for the same reason: one call registers under one transport protocol.
pcapkit.utilities.exceptions.ProtocolError – Raised from ModuleDescriptor.klass, which the port-keyed registry resolves before storing the entry, when module is a str and either class_ names no attribute of it, or class_ was never given at all – the latter distinguished from the former rather than reported as a missing attribute named '(null)'. See GitHub issues #832 and #833.

Important

SCTP is deliberately not one of the registries this writes to, so naming sctp here is an error rather than a no-op. Its __proto__ registry is keyed by the DATA chunk’s payload protocol identifier rather than by port number, so writing a port number into it would dispatch on a number from the wrong registry. Use pcapkit.foundation.registry.protocols.transport.register_sctp() instead.

Application Layer Registries¶

pcapkit.foundation.registry.protocols.application.register_http_frame(code, meth, *, schema=None)[source]¶

The function will register the given frame parser to the pcapkit.protocols.application.httpv2.protocol.HTTPv2.__frame__ registry.

Parameters:

code (Frame) – HTTP/2 frame type code as in Frame.
meth (str | tuple[Callable[[FrameType, HTTPv2], HTTPv2], Callable[[HTTPv2 | None, Any], Tuple[FrameType, Flags]]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the frame. A name names the _read_http_* and _make_http_* methods, and has to name an existing _read_http_* one.
schema (Type[FrameType] | None) – Schema class for the frame. It should be a subclass of pcapkit.protocols.application.httpv2.schema.FrameType.

Raises:

RegistryError – If code is not a Frame member, e.g. a member of another enum, or meth is a name with no matching _read_http_* method.

Return type:

None

pcapkit.foundation.registry.protocols.application.register_tls_extension(code, meth)[source]¶

The function will register the given extension parser to the pcapkit.protocols.application.ssl.protocol.SSL.__extension__ registry, which TLS and DTLS share.

Parameters:

code (ExtensionType) – TLS/DTLS extension type as in ExtensionType.
meth (str | tuple[Callable[[ExtensionType, bytes, HandshakeType], ExtensionData | bytes], Callable[[ExtensionType, ExtensionData | None, HandshakeType, Any], bytes]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the extension_data. A name names the _read_ext_* and _make_ext_* methods, and has to name an existing _read_ext_* one.

Raises:

RegistryError – If code is not an ExtensionType member, e.g. a member of another enum, or meth is a name with no matching _read_ext_* method.

Added in version 1.6.0.

Miscellaneous Protocol Registries¶

pcapkit.foundation.registry.protocols.misc.register_pcapng_block(code, meth, *, schema=None)[source]¶

The function will register the given block parser to the pcapkit.protocols.misc.pcapng.protocol.PCAPNG.__block__ registry.

Parameters:

code (BlockType) – PCAPNG block type code as in BlockType.
meth (str | tuple[Callable[[BlockType, PCAPNG], PCAPNG], Callable[[PCAPNG | None, Any], BlockType]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the block. A name names the _read_block_* and _make_block_* methods, and has to name an existing _read_block_* one.
schema (Type[BlockType] | None) – Schema class for the block. It should be a subclass of pcapkit.protocols.misc.pcapng.schema.BlockType.

Raises:

RegistryError – If code is not a BlockType member, e.g. a member of another enum, or meth is a name with no matching _read_block_* method.

Return type:

None

pcapkit.foundation.registry.protocols.misc.register_pcapng_option(code, meth, *, schema=None)[source]¶

The function will register the given option parser to the pcapkit.protocols.misc.pcapng.protocol.PCAPNG.__option__ registry.

Parameters:

code (OptionType) – PCAPNG option type code as in OptionType.
meth (str | tuple[Callable[[Option, OrderedMultiDict[OptionType, Option]], Option], Callable[[OptionType, Option | None, Any], Option]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the option. A name names the _read_option_* and _make_option_* methods, and has to name an existing _read_option_* one.
schema (Type[Option] | None) – Schema class for the option. It should be a subclass of pcapkit.protocols.misc.pcapng.schema.Option.

Raises:

RegistryError – If code is not a OptionType member, e.g. a member of another enum, or meth is a name with no matching _read_option_* method.

Return type:

None

pcapkit.foundation.registry.protocols.misc.register_pcapng_record(code, meth, *, schema=None)[source]¶

The function will register the given name resolution record parser to the pcapkit.protocols.misc.pcapng.protocol.PCAPNG.__record__ registry.

Parameters:

code (RecordType) – PCAPNG name resolution record type code as in RecordType.
meth (str | tuple[Callable[[NameResolutionRecord, OrderedMultiDict[RecordType, NameResolutionRecord]], NameResolutionRecord], Callable[[RecordType, NameResolutionRecord | None, Any], NameResolutionRecord]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the name resolution record. A name names the _read_record_* and _make_record_* methods, and has to name an existing _read_record_* one.
schema (Type[NameResolutionRecord] | None) – Schema class for the name resolution record. It should be a subclass of pcapkit.protocols.misc.pcapng.schema.NameResolutionRecord.

Raises:

RegistryError – If code is not a RecordType member, e.g. a member of another enum, or meth is a name with no matching _read_record_* method.

Return type:

None

pcapkit.foundation.registry.protocols.misc.register_pcapng_secrets(code, meth, *, schema=None)[source]¶

The function will register the given decryption secrets parser to the pcapkit.protocols.misc.pcapng.protocol.PCAPNG.__secrets__ registry.

Parameters:

code (SecretsType) – PCAPNG decryption secrets type code as in SecretsType.
meth (str | tuple[Callable[[DSBSecrets, DecryptionSecretsBlock], DSBSecrets], Callable[[SecretsType, DSBSecrets | None, Any], DSBSecrets]]) – Method name, or a (parser, constructor) pair of callables, to parse and construct the decryption secrets. A name names the _read_secrets_* and _make_secrets_* methods, and has to name an existing _read_secrets_* one.
schema (Type[DSBSecrets] | None) – Schema class for the decryption secrets. It should be a subclass of pcapkit.protocols.misc.pcapng.schema.DSBSecrets.

Raises:

RegistryError – If code is not a SecretsType member, e.g. a member of another enum, or meth is a name with no matching _read_secrets_* method.

Return type:

None