osmocom.construct

Helpers for the consturct declarative parser/encoder

Utility code related to the integration of the ‘construct’ declarative parser.

class osmocom.construct.BcdAdapter(subcon)

convert a bytes() type to a string of BCD nibbles.

osmocom.construct.BitsRFU(n=1)

Field that packs Reserved for Future Use (RFU) bit(s) as defined in TS 31.101 Sec. “3.4 Coding Conventions”

Use this for (currently) unused/reserved bits whose contents should be initialized automatically but should not be cleared in the future or when restoring read data (unlike padding).

Parameters:

n (Integer) – Number of bits (default: 1)

osmocom.construct.BytesRFU(n=1)

Field that packs Reserved for Future Use (RFU) byte(s) as defined in TS 31.101 Sec. “3.4 Coding Conventions”

Use this for (currently) unused/reserved bytes whose contents should be initialized automatically but should not be cleared in the future or when restoring read data (unlike padding).

Parameters:

n (Integer) – Number of bytes (default: 1)

class osmocom.construct.DnsAdapter(subcon)

Convert between DNS label format (length-prefixed labels) and string format.

class osmocom.construct.GreedyInteger(signed=False, swapped=False, minlen=0)

A variable-length integer implementation, think of combining GrredyBytes with BytesInteger.

class osmocom.construct.GsmOrUcs2Adapter(subcon)

Try to encode into a GSM 03.38 string; if that fails, fall back to UCS-2 as described in TS 102 221 Annex A.

osmocom.construct.GsmOrUcs2String(n)

GSM 03.38 or UCS-2 (TS 102 221 Annex A) encoded byte string of fixed length n. Encoder appends padding bytes (b’xff’) to maintain length. Decoder removes those trailing bytes.

Exceptions are raised for invalid characters and length excess.

Parameters:

n (Integer) – Fixed length of the encoded byte string

osmocom.construct.GsmString(n)

GSM 03.38 encoded byte string of fixed length n. Encoder appends padding bytes (b’xff’) to maintain length. Decoder removes those trailing bytes.

Exceptions are raised for invalid characters and length excess.

Parameters:

n (Integer) – Fixed length of the encoded byte string

class osmocom.construct.GsmStringAdapter(subcon, codec='gsm03.38', err='strict')

Convert GSM 03.38 encoded bytes to a string.

class osmocom.construct.HexAdapter(subcon)

convert a bytes() type to a string of hex nibbles.

class osmocom.construct.InvertAdapter(subcon)

inverse logic (false->true, true->false).

class osmocom.construct.Ipv4Adapter(subcon)

Encoder converts from 4 bytes to string representation (A.B.C.D). Decoder converts from string representation (A.B.C.D) to four bytes.

class osmocom.construct.Ipv6Adapter(subcon)

Encoder converts from 16 bytes to string representation. Decoder converts from string representation to 16 bytes.

class osmocom.construct.MultiplyAdapter(subcon, multiplicator)

Decoder multiplies by multiplicator Encoder divides by multiplicator

Parameters:

  • subcon – Subconstruct as defined by construct library

  • multiplier – Multiplier to apply to raw encoded value

class osmocom.construct.PaddedBcdAdapter(subcon)

Representatin of a BCD string of potentially odd number of BCD digits, which then need to be padded at the end with an ‘f’ nibble.

class osmocom.construct.PlmnAdapter(subcon)

convert a bytes(3) type to BCD string like 262-02 or 262-002.

class osmocom.construct.Rpad(subcon, pattern=b'\xff', num_per_byte=1)

Encoder appends padding bytes (b’xff’) or characters up to target size. Decoder removes trailing padding bytes/characters.

Parameters:

  • subcon – Subconstruct as defined by construct library

  • pattern – set padding pattern (default: b’xff’)

  • num_per_byte – number of ‘elements’ per byte. E.g. for hex nibbles: 2

class osmocom.construct.StripTrailerAdapter(subcon, total_length: int, default_value=b'\x00', min_len=1)

Encoder removes all trailing bytes matching the default_value Decoder pads input data up to total_length with default_value

This is used in constellations like “FlagsEnum(StripTrailerAdapter(GreedyBytes, 3), …” where you have a bit-mask that may have 1, 2 or 3 bytes, depending on whether or not any of the LSBs are actually set.

class osmocom.construct.Ucs2Adapter(subcon)

convert a bytes() type that contains UCS2 encoded characters encoded as defined in TS 102 221 Annex A to normal python string representation (and back).

class osmocom.construct.Utf8Adapter(subcon)

convert a bytes() type that contains utf8 encoded text to human readable text.

osmocom.construct.build_construct(c, decoded_data, context: dict = {})

Helper function to handle total_len.

osmocom.construct.filter_dict(d, exclude_prefix='_')

filter the input dict to ensure no keys starting with ‘exclude_prefix’ remain.

osmocom.construct.normalize_construct(c, exclude_prefix: str = '_')

Convert a construct specific type to a related base type, mostly useful so we can serialize it.

osmocom.construct.parse_construct(c, raw_bin_data: bytes, length: int | None = None, exclude_prefix: str = '_', context: dict = {})

Helper function to wrap around normalize_construct() and filter_dict().