TLV Model

exception ndn.encoding.tlv_model.DecodeError

Raised when there is a critical field (Type is odd) that is unrecognized, redundant or out-of-order.

exception ndn.encoding.tlv_model.IncludeBaseError

Raised when IncludeBase is used to include a non-base class.

class ndn.encoding.tlv_model.IncludeBase(base)

Include all fields from a base class.

class ndn.encoding.tlv_model.Field(type_num, default=None)

Field of TlvModel. A field with value None will be omitted in encoding TLV. There is no required field in a TlvModel, i.e. any Field can be None.

Variables
  • name (str) – The name of the field

  • type_num (int) – The Type number used in TLV encoding

  • default

    The default value used for parsing and encoding.

    • If this field is absent during parsing, default is used to fill in this field.

    • If this field is not explicitly assigned to None before encoding, default is used.

__get__(instance, owner)

Get the value of this field in a specific instance. Simply call get_value() if instance is not None.

Parameters
  • instance – the instance that this field is being accessed through.

  • owner – the owner class of this field.

Returns

the value of this field.

__set__(instance, value)

Set the value of this field.

Parameters
  • instance – the instance whose field is being set.

  • value – the new value.

abstract encode_into(val, markers, wire, offset)

Encode this field into wire. Must be called after encoded_length().

Parameters
  • val – value of this field

  • markers (dict) – encoding marker variables

  • wire (Union[bytearray, memoryview]) – buffer to encode

  • offset (int) – offset of this field in wire

Return type

int

Returns

encoded length with TL. It is expected to be the same as encoded_length() returns.

abstract encoded_length(val, markers)

Preprocess value and get encoded length of this field. The function may use markers[f'{self.name}##encoded_length'] to store the length with TL. Other marker variables starting with f'{self.name}##' may also be used. Generally, marker variables are only used to store temporary values and avoid duplicated calculation. One field should not access to another field’s marker by its name.

This function may also use other marker variables. However, in that case, this field must be unique in a TlvModel. Usage of marker variables should follow the name convention defined by specific TlvModel.

Parameters
  • val – value of this field

  • markers (dict) – encoding marker variables

Return type

int

Returns

encoded length with TL. It is expected as the exact length when encoding this field. The only exception is SignatureValueField (invisible to application developer).

get_value(instance)

Get the value of this field in a specific instance. Most fields use instance.__dict__ to access the value.

Parameters

instance – the instance that this field is being accessed through.

Returns

the value of this field.

abstract parse_from(instance, markers, wire, offset, length, offset_btl)

Parse the value of this field from an encoded wire.

Parameters
  • instance – the instance to parse into.

  • markers (dict) – encoding marker variables. Only used in special cases.

  • wire (Union[bytes, bytearray, memoryview]) – the TLV encoded wire.

  • offset (int) – the offset of this field’s Value in wire.

  • length (int) – the Length of this field’s Value.

  • offset_btl (int) –

    the offset of this field’s TLV.

    assert offset == (offset_btl
                    + get_tl_num_size(self.type_num)
                    + get_tl_num_size(length))
    

Returns

the value.

skipping_process(markers, wire, offset)

Called when this field does not occur in wire and thus be skipped.

Parameters
  • markers (dict) – encoding marker variables.

  • wire (Union[bytes, bytearray, memoryview]) – the TLV encoded wire.

  • offset (int) – the offset where this field should have been if it occurred.

class ndn.encoding.tlv_model.ProcedureArgument(default=None)

A marker variable used during encoding or parsing. It does not have a value. Instead, it provides a way to access a specific variable in markers.

__get__(instance, owner)
Returns

itself.

__set__(instance, value)

This is not allowed and will raise a TypeError if called.

get_arg(markers)

Get its value from markers

Parameters

markers (dict) – the markers dict.

Returns

its value.

set_arg(markers, val)

Set its value in markers.

Parameters
  • markers (dict) – the markers dict.

  • val – the new value.

class ndn.encoding.tlv_model.OffsetMarker(default=None)

A marker variable that records its position in TLV wire in terms of offset.

class ndn.encoding.tlv_model.UintField(type_num, default=None, fixed_len=None)

NonNegativeInteger field.

Type: int

Its Length is 1, 2, 4 or 8 when present.

Variables

fixed_len (int) – the fixed value for Length if it’s not None. Only 1, 2, 4 and 8 are acceptable.

class ndn.encoding.tlv_model.BoolField(type_num, default=None)

Boolean field.

Type: bool

Its Length is always 0. When present, its Value is True. When absent, its Value is None, which is equivalent to False.

Note

The default value is always None.

class ndn.encoding.tlv_model.NameField(default=None)

NDN Name field. Its Type is always Name.TYPE_NAME.

Type: NonStrictName

class ndn.encoding.tlv_model.BytesField(type_num, default=None)

Field for *OCTET.

Type: BinaryStr

Note

Do not assign it with a str.

class ndn.encoding.tlv_model.ModelField(type_num, model_type, copy_in_fields=None, copy_out_fields=None, ignore_critical=False)

Field for nested TlvModel.

Type: TlvModel

Variables
  • model_type (TlvModelMeta) – the type of its value.

  • ignore_critical (bool) – whether to ignore critical fields (whose Types are odd).

class ndn.encoding.tlv_model.RepeatedField(element_type)

Field for an array of a specific type. All elements will be directly encoded into TLV wire in order, sharing the same Type. The type_num of element_type is used.

Type: list

Variables

element_type (Field) –

the type of elements in the list.

Warning

Please always create a new Field instance. Don’t use an existing one.

class ndn.encoding.tlv_model.TlvModelMeta(name, bases, attrs)

Metaclass for TlvModel, used to collect fields.

class ndn.encoding.tlv_model.TlvModel

Used to describe a TLV format.

Variables

_encoded_fields (List[Field]) – a list of Field in order.

__eq__(other)

Compare two TlvModels

Parameters

other – the other TlvModel to compare with.

Returns

whether all Fields are equal.

asdict(dict_factory=<class 'dict'>)

Return a dict to represent this TlvModel.

Parameters

dict_factory – class of dict.

Returns

the dict.

encode(wire=None, offset=0, markers=None)

Encode the TlvModel.

Parameters
  • wire (Union[bytearray, memoryview, None]) – the buffer to contain the encoded wire. A new bytearray will be created if it’s None.

  • offset (int) – the starting offset.

  • markers (Optional[dict]) – encoding marker variables.

Return type

Union[bytearray, memoryview]

Returns

wire.

Raises
  • ValueError – some field is assigned with improper value.

  • TypeError – some field is assigned with value of wrong type.

  • IndexError – wire does not have enough length.

  • struct.error – a negative number is assigned to any non-negative integer field.

encoded_length(markers=None)

Get the encoded Length of this TlvModel.

Parameters

markers (Optional[dict]) – encoding marker variables.

Return type

int

Returns

the encoded Length.

classmethod parse(wire, markers=None, ignore_critical=False)

Parse a TlvModel from TLV encoded wire.

Parameters
  • wire (Union[bytes, bytearray, memoryview]) – the TLV encoded wire.

  • markers (Optional[dict]) – encoding marker variables.

  • ignore_critical (bool) – whether to ignore unknown critical fields.

Returns

parsed TlvModel.

Raises
  • DecodeError – a critical field is unrecognized, redundant or out-of-order.

  • IndexError – the Length of a field exceeds the size of wire.