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.