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 valueNone
will be omitted in encoding TLV. There is no required field in aTlvModel
, i.e. any Field can beNone
.- 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()
ifinstance
is notNone
.- 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 variableswire (
Union
[bytearray
,memoryview
]) – buffer to encodeoffset (
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 withf'{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 inwire
.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 isNone
, which is equivalent toFalse
.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, 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
ifis_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
ofelement_type
is used.Type:
list
- 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.
- __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 newbytearray
will be created if it’sNone
.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.