pub struct TlvReader<'a> { /* private fields */ }Expand description
A cursor over a TLV encoding.
Implementations§
Source§impl<'a> TlvReader<'a>
impl<'a> TlvReader<'a>
Sourcepub const fn new_in(buf: &'a [u8], container: ContainerKind) -> Self
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.
Sourcepub const fn new_members(buf: &'a [u8], container: ContainerKind) -> Self
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.
Sourcepub fn next_element(&mut self) -> Result<Option<Element<'a>>>
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.
Sourcepub fn skip_container(&mut self) -> Result<()>
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.
Sourcepub fn slice_from(&self, start: usize) -> Result<&'a [u8]>
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.
Sourcepub fn skip_value(&mut self, element: &Element<'a>) -> Result<()>
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.
Sourcepub fn finish(&self) -> Result<()>
pub fn finish(&self) -> Result<()>
Checks that the encoding is complete and well-formed: every container closed, and exactly one top-level element present.
Sourcepub fn validate(buf: &'a [u8]) -> Result<usize>
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.
Sourcepub fn first_empty_optional(buf: &'a [u8]) -> Result<Option<Tag>>
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.