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, val_base_type=<class 'int'>)

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.
val_base_type – the base type of the value of the field. Can be int (default), an Enum or a Flag type.

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, type_number=7)

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

Type: NonStrictName

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

Field for *OCTET.

Type: BinaryStr

Variables:: is_string – If the value is a UTF-8 string. False by default.

Note

Do not assign it with a str if is_string is False.

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]) – 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.