Protocol Family#
pcapkit.protocols is collection of all protocol families,
with detailed implementation and methods.
- Root Protocol
- Link Layer
- Internet Layer
- Base Protocol
- IP - Internet Protocol
- IPv4 - Internet Protocol version 4
- IPv6 - Internet Protocol version 6
- IPv6-Frag - Fragment Header for IPv6
- IPv6-Opts - Destination Options for IPv6
- IPv6-Route - Routing Header for IPv6
- HOPOPT - IPv6 Hop-by-Hop Options
- IPsec - Internet Protocol Security
- AH - Authentication Header
- HIP - Host Identity Protocol
- MH - Mobility Header
- IPX - Internetwork Packet Exchange
- Protocol Registry
- Transport Layer
- Application Layer
- Auxiliary Protocols
All protocol classes are implemented as Protocol
subclasses, which are responsible for processing extracted binary packet data
and/or construct protocol packet from given information. Below is a brief
diagram of the class hierarchy of pcapkit.protocols:
Protocol Registry#
- pcapkit.protocols.__proto__: dict[str, Type[ProtocolBase]]#
Protocol registry.
See also
Please refer to
pcapkit.foundation.registry.protocols.register_protocol()for more information.
Header Schema#
- class pcapkit.protocols.schema.schema.Schema(dict_=None, **kwargs)[source]#
Bases:
Mapping[str,_VT],Generic[_VT]Schema for protocol headers.
- static __new__(cls, *args, **kwargs)[source]#
Create a new instance.
The class will try to automatically generate
__init__method with the same signature as specified in class variables’ type annotations, which is inspired by PEP 557 (dataclasses).
- pack(packet=None)[source]#
-
- Parameters:
- Return type:
- Returns:
Notes
Since we do not know the length of the packet, we use a reasonable default value
-1for the__length__field, as theFieldclass will consider negative value as a placeholder.If you want to pack the packet with the correct length, please provide the
__length__value before packing.
- pre_pack(packet)[source]#
Prepare
packetdata for packing process.Note
This method is expected to directly modify any data stored in the
packetand thus no return is required.
- classmethod unpack(cls, data, length=None, packet=None)[source]#
-
- Parameters:
- Return type:
Self- Returns:
Unpacked data as
Schema.
Notes
We used a
__length__key inpacketto record the length of the remaining data, which is used to determine the length of the payload field.And a
__padding_length__key in thepacketto record the length of the padding field after anOptionField, which is used to potentially determine the length of the remaining padding field data.
- classmethod pre_unpack(packet)[source]#
Prepare
packetdata for unpacking process.Note
This method is expected to directly modify any data stored in the
packetand thus no return is required.
- classmethod from_dict(dict_=None, **kwargs)[source]#
Create a new instance.
If
dict_is present and has a.keys()method, then does:for k in dict_: self[k] = dict_[k].If
dict_is present and has no.keys()method, then does:for k, v in dict_: self[k] = v.If
dict_is not present, then does:for k, v in kwargs.items(): self[k] = v.
-
__fields__:
OrderedDict[str,FieldBase]# Mapping of fields.
- class pcapkit.protocols.schema.schema.EnumSchema(dict_=None, **kwargs)[source]#
-
Schemawith enumeration mapping support.Examples
To create an enumeration mapping supported schema, simply
class MySchema(EnumSchema[MyEnum]): # optional, set the default schema for enumeration mapping # if the enumeration number is not found in the mapping __default__ = lambda: UnknownSchema # by default, None
then, you can use inheritance to create a list of schemas for this given enumeration mapping:
class OneSchema(MySchema, code=MyEnum.ONE): ... class MultipleSchema(MySchema, code=[MyEnum.TWO, MyEnum.THREE]): ...
or optionally, using the
register()method to register a schema to the enumeration mapping:MySchema.register(MyEnum.ZERO, ZeroSchema)
And now you can access the enumeration mapping via the
registryproperty (more specifically, class attribute):>>> MySchema.registry[MyEnum.ONE] # OneSchema
-
__default__:
Callable[[],Type[Self]]# Callback to return the default schema for enumeration mapping, by default is a
lambda: Nonestatement.
-
__enum__:
DefaultDict[TypeVar(_ET, bound= Enum),Type[Self]]# Mapping of enumeration numbers to schemas.
- property registry: DefaultDict[_ET, Type[Self]]#
Mapping of enumeration numbers to schemas.
Note
This property is also available as a class attribute.
- classmethod __init_subclass__(code=None, *args, **kwargs)[source]#
Register enumeration to
registrymapping.- Parameters:
- Return type:
If
codeis provided, the subclass will be registered to theregistrymapping with the givencode. Ifcodeis not given, the subclass will not be registered.Notes
If
__enum__is not yet defined at function call, it will automatically be defined as acollections.defaultdictobject, with the default value set to__default__.If intended to customise the
__enum__mapping, it is possible to override the__init_subclass__()method and define__enum__manually.
-
__default__:
- @pcapkit.protocols.schema.schema.schema_final(cls, *, _finalised=True)[source]#
Finalise schema class.
This decorator function is used to generate necessary attributes and methods for the decorated
Schemaclass. It can be useful to reduce runtime generation time as well as caching already generated attributes.Notes
The decorator should only be used on the final class, otherwise, any subclasses derived from a finalised schema class will not be re-finalised.
Internal Definitions#
- class pcapkit.protocols.schema.schema.SchemaMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any], **kwargs: Any)[source]#
Bases:
ABCMetaMeta class to add dynamic support to
Schema.This meta class is used to generate necessary attributes for the
Schemaclass. It can be useful to reduce runtime generation cost as well as caching already generated attributes.Schema.__fields__is a dictionary of field names and their correspondingFieldobjects, which are used to define and parse the protocol headers. The field dictionary will automatically be populated from the class attributes of theSchemaclass, and the field names will be the same as the attribute names.See also
This is implemented thru setting up the initial field dictionary in the
__prepare__()method, and then inherit the field dictionaries from the base classes.Later, during the class creation, the
Field.__set_name__method will be called to set the field name for each field object, as well as to add the field object to the field dictionary.Schema.__additional__andSchema.__excluded__are lists of additional and excluded field names, which are used to determine certain names to be included or excluded from the field dictionary. They will be automatically populated from the class attributes of theSchemaclass and its base classes.Note
This is implemented thru the
__new__()method, which will inherit the additional and excluded field names from the base classes, as well as populating the additional and excluded field from the subclass attributes.class A(Schema): __additional__ = ['a', 'b'] class B(A): __additional__ = ['c', 'd'] class C(B): __additional__ = ['e', 'f'] print(A.__additional__) # ['a', 'b'] print(B.__additional__) # ['a', 'b', 'c', 'd'] print(C.__additional__) # ['a', 'b', 'c', 'd', 'e', 'f']
- class pcapkit.protocols.schema.schema.EnumMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any], **kwargs: Any)[source]#
Bases:
SchemaMeta,Generic[_ET]Meta class to add dynamic support for
EnumSchema.This meta class is used to generate necessary attributes for the
SchemaMetaclass. It can be useful to reduce runtime generation cost as well as caching already generated attributes.registryis added to subclasses as an immutable proxy (similar toproperty, but on class variables) to theEnumSchema.__enum__mapping.
Type Variables#
- pcapkit.protocols.schema.schema._ST: Type[pcapkit.protocols.schema.schema.Schema]#