Struct TLVElement

Source

pub struct TLVElement<'a>(/* private fields */);

Expand description

A newtype for reading TLV-encoded data from Rust &[u8] slices.

Semantically, a TLVElement is just a byte slice of TLV-encoded data/stream, and the methods provided by this therefore allow to parse - on the fly - the byte slice as TLV.

Note also, that - as per the Matter Core Spec:

A valid TLV stream always represents a SINGLE TLV element (hence why this type is named TLVElement and why we claim that it represents also a whole TLV stream)
If there is a need to encode more than one TLV element, they should be encoded in a TLV container (array, list or struct), hence we end up again with a single TLV element, which represents the whole container.

Parsing/reading/validating the TLV of the slice represented by a TLVElement is done on-demand. What this means is that:

TLVElement::new(slice) always succeeds, even when the passed slice contains invalid TLV data
As the various methods of TLVElement type are called, the data in the slice is parsed and validated on the fly. Hence why all methods on TLVElement except is_empty are fallible.

A TLV element can currently be constructed from an empty &[] slice, but the empty slice does not actually represent a TLV element, so all methods except TLVElement::is_empty would fail on a TLVElement constructed from an empty slice. The only reason why empty slices are currently allowed is to simplify the FromTLV trait a bit by representing data which was not found (i.e. optional data in TLV structures) as a TLVElement with an empty slice.

The design approach from above (on-demand parsing/validation) trades memory efficiency for extra computations, in that by simply decorating a Rust &[u8] slice anbd post-poning everything else post-construction it ensures the size of a TLVElement is equal to the size of the wrapped &[u8] slice - i.e., a regular Rust fat pointer (8 bytes on 32 bit archs and 16 bytes on 64 bit archs).

Furthermore, all accompanying types of TLVElement, like TLVSequence, TLVContainerIter and TLVArray are also just newtypes over byte slices and therefore just as small.

(Keeping interim data is still optionally possible, by using the TLV::tag and TLV::value methods to read the tag and value of a TLV as enums.)

As for representing the encoded TLV stream itself as a raw &[u8] slice - this trivializes the traversal of the stream as the stream traversal is represented as returning sub-slices of the original slice. It also allows FromTLV implementations where the data is borrowed directly from the &[u8] slice representing the encoded TLV stream without any data moves. Types that implement such borrowing are e.g.:

&str (used to represent borrowed TLV UTF-8 strings)
Bytes<'a> (a newtype over &'a [u8] - used to represent TLV octet strings)
TLVArray
TLVSequence - discussed below

Also, this representation naturally allows random-access to the TLV stream, which is necessary for a number of reasons:

Deserialization of TLV structs into Rust structs (with the FromTLV derive macro) where the order of the TLV elements of the struct is not known in advance
Delayed in-place initialization of large Rust types with FromTLV::init_from_tlv which requires random access for reasons beyond the possible unordering of the TLV struct elements.

In practice, random access - and in general - representation of the TLV stream as a &[u8] slice should be natural and convenient, as the TLV stream usually comes from the network UDP/TCP memory buffers of the Matter transport protocol, and these can and are borrowed as &[u8] slices in the upper-layer code for direct reads.

Struct TLVElement Copy item path

Implementations§

impl<'a> TLVElement<'a>

pub fn read<T>(&self, ctx: u8) -> Result<T, Error>where T: FromTLV<'a>,

pub fn read_opt<T>(&self, ctx: u8) -> Result<Option<T>, Error>where T: FromTLV<'a>,

pub const fn new(data: &'a [u8]) -> TLVElement<'a>

pub fn is_empty(&self) -> bool

pub fn non_empty(&self) -> Option<&TLVElement<'a>>

pub const fn raw_data(&self) -> &'a [u8] ⓘ

pub fn control(&self) -> Result<TLVControl, Error>

pub fn raw_value(&self) -> Result<&'a [u8], Error>

pub fn tlv(&self) -> Result<TLV<'a>, Error>

pub fn tag(&self) -> Result<TLVTag, Error>

pub fn value(&self) -> Result<TLVValue<'a>, Error>

pub fn i8(&self) -> Result<i8, Error>

pub fn u8(&self) -> Result<u8, Error>

pub fn i16(&self) -> Result<i16, Error>

pub fn u16(&self) -> Result<u16, Error>

pub fn i32(&self) -> Result<i32, Error>

pub fn u32(&self) -> Result<u32, Error>

pub fn i64(&self) -> Result<i64, Error>

pub fn u64(&self) -> Result<u64, Error>

pub fn f32(&self) -> Result<f32, Error>

pub fn f64(&self) -> Result<f64, Error>

pub fn str(&self) -> Result<&'a [u8], Error>

pub fn utf8(&self) -> Result<&'a str, Error>

pub fn octets(&self) -> Result<&'a [u8], Error>

pub fn bool(&self) -> Result<bool, Error>

pub fn is_container(&self) -> Result<bool, Error>

pub fn null(&self) -> Result<(), Error>

pub fn structure(&self) -> Result<TLVSequence<'a>, Error>

pub fn struct(&self) -> Result<TLVSequence<'a>, Error>

pub fn array(&self) -> Result<TLVSequence<'a>, Error>

pub fn list(&self) -> Result<TLVSequence<'a>, Error>

pub fn container(&self) -> Result<TLVSequence<'a>, Error>

pub fn confirm_anon(&self) -> Result<(), Error>

pub fn ctx(&self) -> Result<u8, Error>

pub fn try_ctx(&self) -> Result<Option<u8>, Error>

Trait Implementations§

impl<'a> Clone for TLVElement<'a>

fn clone(&self) -> TLVElement<'a>

fn clone_from(&mut self, source: &Self)

impl Debug for TLVElement<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl Display for TLVElement<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<'a> Eq for TLVElement<'a>

impl<'a> FromTLV<'a> for TLVElement<'a>

fn from_tlv(element: &TLVElement<'a>) -> Result<TLVElement<'a>, Error>

fn init_from_tlv(element: TLVElement<'a>) -> impl Init<Self, Error>

fn nullable_from_tlv(element: &TLVElement<'a>) -> Result<Self, Error>

fn init_nullable_from_tlv(element: TLVElement<'a>) -> impl Init<Self, Error>

impl<'a> Hash for TLVElement<'a>

fn hash<__H>(&self, state: &mut __H)where __H: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

impl<'a> PartialEq for TLVElement<'a>

fn eq(&self, other: &TLVElement<'a>) -> bool

fn ne(&self, other: &Rhs) -> bool

impl<'a> StructuralPartialEq for TLVElement<'a>

impl ToTLV for TLVElement<'_>

fn to_tlv<W>(&self, tag: &TLVTag, tw: W) -> Result<(), Error>where W: TLVWrite,

fn tlv_iter(&self, tag: TLVTag) -> impl Iterator<Item = Result<TLV<'_>, Error>>

fn nullable_to_tlv<W>(&self, tag: &TLVTag, tw: W) -> Result<(), Error>where W: TLVWrite,

fn nullable_tlv_iter( &self, tag: TLVTag, ) -> impl Iterator<Item = Result<TLV<'_>, Error>>

impl TryFrom<&TLVElement<'_>> for AreaTypeTag

type Error = Error

fn try_from( element: &TLVElement<'_>, ) -> Result<AreaTypeTag, <AreaTypeTag as TryFrom<&TLVElement<'_>>>::Error>

impl TryFrom<&TLVElement<'_>> for AtomicRequestTypeEnum

type Error = Error

fn try_from( element: &TLVElement<'_>, ) -> Result<AtomicRequestTypeEnum, <AtomicRequestTypeEnum as TryFrom<&TLVElement<'_>>>::Error>

impl TryFrom<&TLVElement<'_>> for LandmarkTag

type Error = Error

fn try_from( element: &TLVElement<'_>, ) -> Result<LandmarkTag, <LandmarkTag as TryFrom<&TLVElement<'_>>>::Error>

impl TryFrom<&TLVElement<'_>> for LocationTag

type Error = Error

fn try_from( element: &TLVElement<'_>, ) -> Result<LocationTag, <LocationTag as TryFrom<&TLVElement<'_>>>::Error>

impl TryFrom<&TLVElement<'_>> for MeasurementTypeEnum

type Error = Error

fn try_from( element: &TLVElement<'_>, ) -> Result<MeasurementTypeEnum, <MeasurementTypeEnum as TryFrom<&TLVElement<'_>>>::Error>

impl TryFrom<&TLVElement<'_>> for PositionTag

Struct TLVElement

pub fn read<T>(&self, ctx: u8) -> Result<T, Error>
where T: FromTLV<'a>,

pub fn read_opt<T>(&self, ctx: u8) -> Result<Option<T>, Error>
where T: FromTLV<'a>,

fn hash<H>(&self, state: &mut H)
where __H: Hasher,

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

fn to_tlv<W>(&self, tag: &TLVTag, tw: W) -> Result<(), Error>
where W: TLVWrite,

fn nullable_to_tlv<W>(&self, tag: &TLVTag, tw: W) -> Result<(), Error>
where W: TLVWrite,