TLV
The alc.tlv module contains some functions and classes that help in handling TLV-encoded data.
Decoding a list of TLVs
- alc.tlv.decode(data, tlen=1, llen=1, inclusive=False)
Retrieves an iterator to iterate over the decoded TLV entries.
- Parameters
data (bytes) – TLV encoded string to search in
tlen (int) – length, in bytes, of the type-field
llen (int) – length, in bytes, of the length-field
inclusive (bool) – whether the length includes the lengths of both type- and length-fields
- Returns
iterator that iterates the entries, returning a tuple of (type, value)
Encoding a list of TLVs
- alc.tlv.encode(items, tlen=1, llen=1, inclusive=False)
Encodes a list of items into a bytes representation.
- Parameters
items – An iterable of tv-pairs, of types (int, bytes).
tlen (int) – length, in bytes, of the type-field
llen (int) – length, in bytes, of the length-field
inclusive (bool) – whether the length includes the lengths of both type- and length-fields
- Returns
bytes object encoding the list of tlv-pairs
Finding a specific TLV
- alc.tlv.find(data, type, tlen=1, llen=1, inclusive=False)
Finds the value for a specific type in a TLV encoded string.
- Parameters
data (bytes) – TLV encoded string to search in
type (int) – value of the type to search for
tlen (int) – length, in bytes, of the type-field
llen (int) – length, in bytes, of the length-field
inclusive (bool) – whether the length includes the lengths of both type- and length-fields
- Returns
the value corresponding with the type, or None if not present
The alc.tlv.TLV object
- class alc.tlv.TLV(tlen=1, llen=1, inclusive=False)
Creates a TLV object that works with a specific type of TLV encoded data.
- Parameters
tlen (int) – length, in bytes, of the type-field
llen (int) – length, in bytes, of the length-field
inclusive (bool) – whether the length includes the lengths of both type- and length-fields
- find(self, data, type)
Finds the value for a specific type in a TLV encoded string.
- Parameters
data (bytes) – TLV encoded string to search in
type – value of the type to search for
- Returns
the value corresponding with the type, or None if not present
- decode(self, data):
Retrieves an iterator to iterate over the decoded TLV entries.
- Parameters
data (bytes) – TLV encoded string to search in
- Returns
iterator that iterates the entries, returning a tuple of (type, value)
- encode(self, items):
Encodes a list of items into a bytes representation.
- Parameters
items – An iterable of tlv-pairs, of types (int, bytes).
- Returns
bytes object encoding the list of tlv-pairs
Example
Creates a bytes object which contains some TLV-encoded data. Both type and length fields are one byte and the length field is inclusive:
from ubinascii import unhexlify
data = unhexlify(b"0105666f6f1905626172")
Use the alc.tlv module to list the items or search for a specific item. The defaults for tlen and llen are correct, but a value must be specified for inclusive:
from alc import tlv
list(tlv.decode(data, inclusive=True)) #[(1, b'foo'), (25, b'bar')]
tlv.find(data, 25, inclusive=True) #b'bar'
If the type of TLV encoding is different from the default values, an object can be created which encapsulates the type of encoding. This object can be used to work with this kind of tlv-strings without the need of passing the same parameters again and again:
tlv11i = tlv.TLV(tlen=1, llen=1, inclusive=True)
list(tlv11i.decode(data)) # [(1, b'foo'), (25, b'bar')]
tlv11i.find(data, 1) # b'foo'
When the format of the data is not as expected and decoding fails, a ValueError is raised:
tlv24 = tlv.TLV(tlen=2, llen=4)
list(tlv24.decode(data))
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: invalid tlv encoded data
Encoding a list of type-value pairs into a bytes object:
tlv11i.encode([(1, b'foo'), (25, b'bar')]) # b'0105666f6f1905626172'
Breaking changes
Warning
The functions provided in this module were previously added onto the str class in the Python 2 API. With the Python 3 API, these functions have been removed from the str-class and this module should be used instead.