Skip to main content

TlvReader

Struct TlvReader 

Source
pub struct TlvReader<'a> { /* private fields */ }
Expand description

A cursor over a TLV encoding.

Implementations§

Source§

impl<'a> TlvReader<'a>

Source

pub const fn new(buf: &'a [u8]) -> Self

Starts reading at the beginning of buf.

Source

pub const fn new_in(buf: &'a [u8], container: ContainerKind) -> Self

Starts reading as though the cursor were already inside container.

Which tag forms are legal depends on where an element sits (§A.2.2, §A.5.1, §A.5.2), so a fragment that will be spliced into a structure has to be checked against a structure’s rules, not against the top level’s. A context-specific tag is invalid at the top level and required inside a structure — validating such a fragment with TlvReader::new would reject exactly the bytes that are correct.

This is what TlvWriter::raw_element uses.

Source

pub const fn new_members(buf: &'a [u8], container: ContainerKind) -> Self

A cursor over the members of a container — many elements, not one.

TlvReader::new_in reads a fragment that will be spliced in as a single element, and holds it to §A.1’s “single top-level element”. This reads the inside of a container whose opening and closing octets live somewhere else, so the rule does not apply: TlvList keeps a list’s members that way, and a reader that refused the second one would be applying a rule about encodings to something that is not one.

The members must not include the end-of-container: that octet closes a container this cursor was never told it is inside, and meeting it is ErrorCode::TlvContainerMismatch.

Source

pub const fn position(&self) -> usize

How many octets have been consumed.

Source

pub const fn depth(&self) -> usize

How many containers are currently open.

Source

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

The octets not yet consumed.

Source

pub const fn is_empty(&self) -> bool

Whether the cursor is at the end of the buffer.

Source

pub fn next_element(&mut self) -> Result<Option<Element<'a>>>

Reads the next element.

Returns Ok(None) at the end of the buffer. An unterminated container is not an error here — it is one in TlvReader::finish, which is what a caller that has read a whole encoding should call.

Source

pub fn skip_container(&mut self) -> Result<()>

Skips the container the cursor has just entered, leaving it positioned after that container’s end-of-container element.

Call this immediately after a Value::Container element. It is iterative, so nesting costs no stack.

Source

pub fn slice_from(&self, start: usize) -> Result<&'a [u8]>

The octets between start and the cursor — one element with its tag, when start was taken immediately before reading it.

This is how a payload whose schema belongs to somebody else is carried: an attribute’s value has a cluster’s type, not the interaction model’s, so the interaction model keeps the encoded element and hands it on with TlvWriter::raw_element rather than interpreting it.

Returns ErrorCode::TlvTruncated if start is past the cursor, which can only happen if a caller passed a position from a different reader.

Source

pub fn skip_value(&mut self, element: &Element<'a>) -> Result<()>

Skips whatever the given element is: a no-op for a primitive, a whole subtree for a container.

Source

pub fn finish(&self) -> Result<()>

Checks that the encoding is complete and well-formed: every container closed, and exactly one top-level element present.

Source

pub fn validate(buf: &'a [u8]) -> Result<usize>

Reads the whole encoding, checking it is well-formed, and returns how many elements it contained.

This is what a fuzz target and a “is this valid TLV?” caller want.

Source

pub fn first_empty_optional(buf: &'a [u8]) -> Result<Option<Tag>>

The first container with no members under a context-specific tag, if there is one.

What you write, somebody stricter will read. An optional structure encoded with nothing in it is legal Appendix A, accepted by this crate’s decoder, and refused by every released CHIP SDK — so the rule kept here is stricter than the specification’s: an optional structure that would be empty is not written at all.

It cannot live in TlvWriter, because §4.14.1.2 gives empty a meaning: an empty PBKDFParamResponse.pbkdf_parameters [4] encodes “the initiator already has them”, which is a claim rather than an absence. So the rule is checked over the writer, on encoded output, and the caller knows its own exceptions.

Two narrowings, and both matter. Only structures — an empty array or list is a value, and a node that wrote nothing has to be able to say so. Only context-specific tags — an anonymous empty structure is an element of the list containing it, not an absent field.

use matter_kit::tlv::{ContainerKind, Tag, TlvReader, TlvWriter};

let mut buf = [0u8; 32];
let mut w = TlvWriter::new(&mut buf);
w.start(Tag::Anonymous, ContainerKind::Structure).unwrap();
w.start(Tag::Context(4), ContainerKind::Structure).unwrap();   // optional, and empty
w.end_container().unwrap();
w.end_container().unwrap();
let encoded = w.finish().unwrap();

assert_eq!(TlvReader::first_empty_optional(encoded).unwrap(), Some(Tag::Context(4)));

Errors only when buf is not well-formed TLV; TlvReader::validate is the check that makes that complaint.

Trait Implementations§

Source§

impl<'a> Clone for TlvReader<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<'a> Debug for TlvReader<'a>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a> Forget for TlvReader<'a>

§

impl<'a> Freeze for TlvReader<'a>

§

impl<'a> Move for TlvReader<'a>

§

impl<'a> RefUnwindSafe for TlvReader<'a>

§

impl<'a> Send for TlvReader<'a>

§

impl<'a> Sync for TlvReader<'a>

§

impl<'a> Unpin for TlvReader<'a>

§

impl<'a> UnsafeUnpin for TlvReader<'a>

§

impl<'a> UnwindSafe for TlvReader<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.