matter-kit 0.3.0

Matter (CSA smart-home standard) protocol implementation in Rust: no_std, no-alloc, executor-agnostic
Documentation
// Generated by `cargo xtask` from the CSA data model 1.6. Do not edit.
//
// Diagnostic Logs โ€” cluster 0x0032.
//
// Regenerate with `cargo xtask clusters --dm <checkout>/data_model/1.6`; `cargo xtask check`
// is the CI gate that keeps this file honest. The XML itself is not vendored here โ€” it
// carries the CSA's own copyright notice and is not redistributable.

//! Diagnostic Logs (cluster `0x0032`, revision 1).
//!
//! 2 identifiers, 0 feature bits, and the specification's own conformance for
//! every element. `CLUSTER` is the whole table.

#![allow(unused_imports)]

use crate::dm::conformance::{Clause, Condition, Conform, Conformance};
use crate::dm::meta::{EventPriority, Reporting};
use crate::dm::spec::{Attribute, Cluster, Command, Event, Feature};
use crate::dm::{Access, AccessQualities, AttributeQualities, Privilege};
use crate::error::Result;
use crate::im::{AttributeId, ClusterId, CommandId, EventId};
use crate::tlv::{
    ContainerKind, Element, FromTlv, Nullable, Tag, TlvList, TlvReader, TlvWriter, ToTlv, Value,
};

/// The cluster id.
pub const ID: ClusterId = 0x0032;

/// The highest revision the specification's history defines โ€” what `ClusterRevision`
/// must report (Core ยง7.13.1).
pub const REVISION: u16 = 1;

/// The PICS code, which a certification declaration names the cluster by.
pub const PICS: &str = "DLOG";

/// This cluster defines no features, so its `FeatureMap` is always zero.
pub const FEATURES: &[Feature] = &[];

/// The command ids.
pub mod command {
    use crate::im::CommandId;

    /// `RetrieveLogsRequest`.
    pub const RETRIEVE_LOGS_REQUEST: CommandId = 0x00;
    /// `RetrieveLogsResponse`.
    pub const RETRIEVE_LOGS_RESPONSE: CommandId = 0x01;
}

/// `IntentEnum`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(u8)]
pub enum IntentEnum {
    /// Logs to be used for end-user support
    EndUserSupport = 0,
    /// Logs to be used for network diagnostics
    NetworkDiag = 1,
    /// Obtain crash logs from the Node
    CrashLogs = 2,
}

impl IntentEnum {
    /// Reads a wire value, or `None` for one this revision does not define.
    #[must_use]
    pub const fn from_value(value: u8) -> Option<Self> {
        match value {
            0 => Some(Self::EndUserSupport),
            1 => Some(Self::NetworkDiag),
            2 => Some(Self::CrashLogs),
            _ => None,
        }
    }

    /// Its wire value.
    #[must_use]
    pub const fn value(self) -> u8 {
        self as u8
    }
}

impl ToTlv for IntentEnum {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        self.value().to_tlv(w, tag)
    }
}

impl<'a> FromTlv<'a> for IntentEnum {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        let value = <u8 as FromTlv<'a>>::from_tlv(reader, element)?;
        Self::from_value(value).ok_or(crate::Error::new(crate::ErrorCode::TlvOutOfRange))
    }
}

/// `StatusEnum`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(u8)]
pub enum StatusEnum {
    /// Successful transfer of logs
    Success = 0,
    /// All logs have been transferred
    Exhausted = 1,
    /// No logs of the requested type available
    NoLogs = 2,
    /// Unable to handle request, retry later
    Busy = 3,
    /// The request is denied, no logs being transferred
    Denied = 4,
}

impl StatusEnum {
    /// Reads a wire value, or `None` for one this revision does not define.
    #[must_use]
    pub const fn from_value(value: u8) -> Option<Self> {
        match value {
            0 => Some(Self::Success),
            1 => Some(Self::Exhausted),
            2 => Some(Self::NoLogs),
            3 => Some(Self::Busy),
            4 => Some(Self::Denied),
            _ => None,
        }
    }

    /// Its wire value.
    #[must_use]
    pub const fn value(self) -> u8 {
        self as u8
    }
}

impl ToTlv for StatusEnum {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        self.value().to_tlv(w, tag)
    }
}

impl<'a> FromTlv<'a> for StatusEnum {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        let value = <u8 as FromTlv<'a>>::from_tlv(reader, element)?;
        Self::from_value(value).ok_or(crate::Error::new(crate::ErrorCode::TlvOutOfRange))
    }
}

/// `TransferProtocolEnum`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(u8)]
pub enum TransferProtocolEnum {
    /// Logs to be returned as a response
    ResponsePayload = 0,
    /// Logs to be returned using BDX
    BDX = 1,
}

impl TransferProtocolEnum {
    /// Reads a wire value, or `None` for one this revision does not define.
    #[must_use]
    pub const fn from_value(value: u8) -> Option<Self> {
        match value {
            0 => Some(Self::ResponsePayload),
            1 => Some(Self::BDX),
            _ => None,
        }
    }

    /// Its wire value.
    #[must_use]
    pub const fn value(self) -> u8 {
        self as u8
    }
}

impl ToTlv for TransferProtocolEnum {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        self.value().to_tlv(w, tag)
    }
}

impl<'a> FromTlv<'a> for TransferProtocolEnum {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        let value = <u8 as FromTlv<'a>>::from_tlv(reader, element)?;
        Self::from_value(value).ok_or(crate::Error::new(crate::ErrorCode::TlvOutOfRange))
    }
}

/// The fields of `RetrieveLogsRequest` (command `0x00`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RetrieveLogsRequestFields<'a> {
    /// `Intent`, field 0.
    pub intent: IntentEnum,
    /// `RequestedProtocol`, field 1.
    pub requested_protocol: TransferProtocolEnum,
    /// `TransferFileDesignator`, field 2.
    pub transfer_file_designator: Option<&'a str>,
}

impl<'a> ToTlv for RetrieveLogsRequestFields<'a> {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        w.start_structure(tag)?;
        self.intent.to_tlv(w, Tag::Context(0))?;
        self.requested_protocol.to_tlv(w, Tag::Context(1))?;
        if let Some(value) = &self.transfer_file_designator {
            value.to_tlv(w, Tag::Context(2))?;
        }
        w.end_container()
    }
}

impl<'a> FromTlv<'a> for RetrieveLogsRequestFields<'a> {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        if element.value.container() != Some(ContainerKind::Structure) {
            return Err(crate::Error::new(crate::ErrorCode::TlvWrongType));
        }
        let mut intent = None;
        let mut requested_protocol = None;
        let mut transfer_file_designator = None;
        loop {
            let Some(field) = reader.next_element()? else {
                return Err(crate::Error::new(crate::ErrorCode::TlvTruncated));
            };
            if field.value == Value::EndOfContainer {
                break;
            }
            match field.tag.context() {
                Some(0) => intent = Some(<IntentEnum>::from_tlv(reader, &field)?),
                Some(1) => {
                    requested_protocol = Some(<TransferProtocolEnum>::from_tlv(reader, &field)?)
                }
                Some(2) => transfer_file_designator = Some(<&'a str>::from_tlv(reader, &field)?),
                // A field this revision does not define. ยง7.19.2: a receiver
                // ignores what it does not know rather than refusing the whole
                // structure, which is what lets a newer peer talk to an older one.
                _ => reader.skip_value(&field)?,
            }
        }
        Ok(Self {
            intent: intent.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            requested_protocol: requested_protocol
                .ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            transfer_file_designator,
        })
    }
}

/// The fields of `RetrieveLogsResponse` (command `0x01`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RetrieveLogsResponseFields<'a> {
    /// `Status`, field 0.
    pub status: StatusEnum,
    /// `LogContent`, field 1.
    pub log_content: &'a [u8],
    /// `UTCTimeStamp`, field 2.
    pub utc_time_stamp: Option<u64>,
    /// `TimeSinceBoot`, field 3.
    pub time_since_boot: Option<u64>,
}

impl<'a> ToTlv for RetrieveLogsResponseFields<'a> {
    fn to_tlv(&self, w: &mut TlvWriter<'_>, tag: Tag) -> Result<()> {
        w.start_structure(tag)?;
        self.status.to_tlv(w, Tag::Context(0))?;
        self.log_content.to_tlv(w, Tag::Context(1))?;
        if let Some(value) = &self.utc_time_stamp {
            value.to_tlv(w, Tag::Context(2))?;
        }
        if let Some(value) = &self.time_since_boot {
            value.to_tlv(w, Tag::Context(3))?;
        }
        w.end_container()
    }
}

impl<'a> FromTlv<'a> for RetrieveLogsResponseFields<'a> {
    fn from_tlv(reader: &mut TlvReader<'a>, element: &Element<'a>) -> Result<Self> {
        if element.value.container() != Some(ContainerKind::Structure) {
            return Err(crate::Error::new(crate::ErrorCode::TlvWrongType));
        }
        let mut status = None;
        let mut log_content = None;
        let mut utc_time_stamp = None;
        let mut time_since_boot = None;
        loop {
            let Some(field) = reader.next_element()? else {
                return Err(crate::Error::new(crate::ErrorCode::TlvTruncated));
            };
            if field.value == Value::EndOfContainer {
                break;
            }
            match field.tag.context() {
                Some(0) => status = Some(<StatusEnum>::from_tlv(reader, &field)?),
                Some(1) => log_content = Some(<&'a [u8]>::from_tlv(reader, &field)?),
                Some(2) => utc_time_stamp = Some(<u64>::from_tlv(reader, &field)?),
                Some(3) => time_since_boot = Some(<u64>::from_tlv(reader, &field)?),
                // A field this revision does not define. ยง7.19.2: a receiver
                // ignores what it does not know rather than refusing the whole
                // structure, which is what lets a newer peer talk to an older one.
                _ => reader.skip_value(&field)?,
            }
        }
        Ok(Self {
            status: status.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            log_content: log_content.ok_or(crate::Error::new(crate::ErrorCode::TlvNotFound))?,
            utc_time_stamp,
            time_since_boot,
        })
    }
}

/// Every attribute the specification defines, with its conformance.
pub const ATTRIBUTES: &[Attribute] = &[];

/// Every command, with its conformance.
pub const COMMANDS: &[Command] = &[
    Command {
        id: 0x00,
        name: "RetrieveLogsRequest",
        to_server: true,
        response: Some(0x01),
        access: Access::invoke(Privilege::Operate),
        conform: Conform::MANDATORY,
    },
    Command {
        id: 0x01,
        name: "RetrieveLogsResponse",
        to_server: false,
        response: None,
        access: Access::invoke(Privilege::Operate),
        conform: Conform::MANDATORY,
    },
];

/// Every event, with its conformance.
pub const EVENTS: &[Event] = &[];

/// The whole cluster, as the specification defines it.
pub const CLUSTER: Cluster = Cluster {
    id: ID,
    name: "Diagnostic Logs",
    revision: REVISION,
    pics: "DLOG",
    derived_from: None,
    features: FEATURES,
    attributes: ATTRIBUTES,
    commands: COMMANDS,
    events: EVENTS,
};