matter-clusters 0.3.0

//! TimeSynchronization cluster (0x0038).
//! @generated by `cargo xtask codegen` — do not edit.

#![allow(
    clippy::all,
    clippy::pedantic,
    dead_code,
    unreachable_pub,
    unused_imports
)]

use crate::datatypes::SemanticTagStruct;
use crate::error::ClusterError;
use crate::types::Nullable;
use matter_codec::{ContainerKind, Element, Tag, TlvReader, TlvWriter, Value};

/// Cluster ID.
pub const CLUSTER_ID: u32 = 0x0038;
/// Cluster revision.
pub const CLUSTER_REVISION: u16 = 2;

/// Command IDs (requests and responses).
pub mod command_id {
    /// `SetUtcTime` (request).
    pub const SET_UTC_TIME: u32 = 0x00;
    /// `SetTrustedTimeSource` (request).
    pub const SET_TRUSTED_TIME_SOURCE: u32 = 0x01;
    /// `SetTimeZone` (request).
    pub const SET_TIME_ZONE: u32 = 0x02;
    /// `SetTimeZoneResponse` (response).
    pub const SET_TIME_ZONE_RESPONSE: u32 = 0x03;
    /// `SetDstOffset` (request).
    pub const SET_DST_OFFSET: u32 = 0x04;
    /// `SetDefaultNtp` (request).
    pub const SET_DEFAULT_NTP: u32 = 0x05;
}

/// Attribute IDs (cluster-specific).
pub mod attribute_id {
    /// `UtcTime`.
    pub const UTC_TIME: u32 = 0x0000;
    /// `Granularity`.
    pub const GRANULARITY: u32 = 0x0001;
    /// `TimeSource`.
    pub const TIME_SOURCE: u32 = 0x0002;
    /// `TrustedTimeSource`.
    pub const TRUSTED_TIME_SOURCE: u32 = 0x0003;
    /// `DefaultNtp`.
    pub const DEFAULT_NTP: u32 = 0x0004;
    /// `TimeZone`.
    pub const TIME_ZONE: u32 = 0x0005;
    /// `DstOffset`.
    pub const DST_OFFSET: u32 = 0x0006;
    /// `LocalTime`.
    pub const LOCAL_TIME: u32 = 0x0007;
    /// `TimeZoneDatabase`.
    pub const TIME_ZONE_DATABASE: u32 = 0x0008;
    /// `NtpServerAvailable`.
    pub const NTP_SERVER_AVAILABLE: u32 = 0x0009;
    /// `TimeZoneListMaxSize`.
    pub const TIME_ZONE_LIST_MAX_SIZE: u32 = 0x000A;
    /// `DstOffsetListMaxSize`.
    pub const DST_OFFSET_LIST_MAX_SIZE: u32 = 0x000B;
    /// `SupportsDnsResolve`.
    pub const SUPPORTS_DNS_RESOLVE: u32 = 0x000C;
}

bitflags::bitflags! {
    /// `TimeSynchronization` feature bits (FeatureMap).
    #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
    pub struct Feature: u32 {
        /// TimeZone (TZ).
        const TZ = 1 << 0;
        /// NtpClient (NTPC).
        const NTPC = 1 << 1;
        /// NtpServer (NTPS).
        const NTPS = 1 << 2;
        /// TimeSyncClient (TSC).
        const TSC = 1 << 3;
    }
}

/// `DSTOffsetStruct` struct.
#[derive(Clone, Debug, PartialEq)]
pub struct DSTOffsetStruct {
    /// Field Offset (tag 0).
    pub offset: i32,
    /// Field ValidStarting (tag 1).
    pub valid_starting: u64,
    /// Field ValidUntil (tag 2).
    pub valid_until: Nullable<u64>,
}

/// `FabricScopedTrustedTimeSourceStruct` struct.
#[derive(Clone, Debug, PartialEq)]
pub struct FabricScopedTrustedTimeSourceStruct {
    /// Field NodeId (tag 0).
    pub node_id: u64,
    /// Field Endpoint (tag 1).
    pub endpoint: u16,
}

/// `GranularityEnum` (enum8).
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum GranularityEnum {
    /// NoTimeGranularity = 0.
    NoTimeGranularity,
    /// MinutesGranularity = 1.
    MinutesGranularity,
    /// SecondsGranularity = 2.
    SecondsGranularity,
    /// MillisecondsGranularity = 3.
    MillisecondsGranularity,
    /// MicrosecondsGranularity = 4.
    MicrosecondsGranularity,
    /// A value not known to this codegen revision.
    Unknown(u8),
}

impl GranularityEnum {
    /// Decode from its raw discriminant (unknown → `Unknown`).
    #[must_use]
    pub fn from_raw(v: u8) -> Self {
        match v {
            0 => Self::NoTimeGranularity,
            1 => Self::MinutesGranularity,
            2 => Self::SecondsGranularity,
            3 => Self::MillisecondsGranularity,
            4 => Self::MicrosecondsGranularity,
            other => Self::Unknown(other),
        }
    }
    /// The raw discriminant.
    #[must_use]
    pub fn to_raw(self) -> u8 {
        match self {
            Self::NoTimeGranularity => 0,
            Self::MinutesGranularity => 1,
            Self::SecondsGranularity => 2,
            Self::MillisecondsGranularity => 3,
            Self::MicrosecondsGranularity => 4,
            Self::Unknown(v) => v,
        }
    }
}

/// `StatusCodeEnum` (enum8).
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum StatusCodeEnum {
    /// TimeNotAccepted = 2.
    TimeNotAccepted,
    /// A value not known to this codegen revision.
    Unknown(u8),
}

impl StatusCodeEnum {
    /// Decode from its raw discriminant (unknown → `Unknown`).
    #[must_use]
    pub fn from_raw(v: u8) -> Self {
        match v {
            2 => Self::TimeNotAccepted,
            other => Self::Unknown(other),
        }
    }
    /// The raw discriminant.
    #[must_use]
    pub fn to_raw(self) -> u8 {
        match self {
            Self::TimeNotAccepted => 2,
            Self::Unknown(v) => v,
        }
    }
}

/// `TimeSourceEnum` (enum8).
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum TimeSourceEnum {
    /// None = 0.
    None,
    /// Unknown = 1.
    Unknown,
    /// Admin = 2.
    Admin,
    /// NodeTimeCluster = 3.
    NodeTimeCluster,
    /// NonMatterSntp = 4.
    NonMatterSntp,
    /// NonMatterNtp = 5.
    NonMatterNtp,
    /// MatterSntp = 6.
    MatterSntp,
    /// MatterNtp = 7.
    MatterNtp,
    /// MixedNtp = 8.
    MixedNtp,
    /// NonMatterSntpnts = 9.
    NonMatterSntpnts,
    /// NonMatterNtpnts = 10.
    NonMatterNtpnts,
    /// MatterSntpnts = 11.
    MatterSntpnts,
    /// MatterNtpnts = 12.
    MatterNtpnts,
    /// MixedNtpnts = 13.
    MixedNtpnts,
    /// CloudSource = 14.
    CloudSource,
    /// Ptp = 15.
    Ptp,
    /// Gnss = 16.
    Gnss,
    /// A value not known to this codegen revision.
    Unrecognized(u8),
}

impl TimeSourceEnum {
    /// Decode from its raw discriminant (unknown → `Unrecognized`).
    #[must_use]
    pub fn from_raw(v: u8) -> Self {
        match v {
            0 => Self::None,
            1 => Self::Unknown,
            2 => Self::Admin,
            3 => Self::NodeTimeCluster,
            4 => Self::NonMatterSntp,
            5 => Self::NonMatterNtp,
            6 => Self::MatterSntp,
            7 => Self::MatterNtp,
            8 => Self::MixedNtp,
            9 => Self::NonMatterSntpnts,
            10 => Self::NonMatterNtpnts,
            11 => Self::MatterSntpnts,
            12 => Self::MatterNtpnts,
            13 => Self::MixedNtpnts,
            14 => Self::CloudSource,
            15 => Self::Ptp,
            16 => Self::Gnss,
            other => Self::Unrecognized(other),
        }
    }
    /// The raw discriminant.
    #[must_use]
    pub fn to_raw(self) -> u8 {
        match self {
            Self::None => 0,
            Self::Unknown => 1,
            Self::Admin => 2,
            Self::NodeTimeCluster => 3,
            Self::NonMatterSntp => 4,
            Self::NonMatterNtp => 5,
            Self::MatterSntp => 6,
            Self::MatterNtp => 7,
            Self::MixedNtp => 8,
            Self::NonMatterSntpnts => 9,
            Self::NonMatterNtpnts => 10,
            Self::MatterSntpnts => 11,
            Self::MatterNtpnts => 12,
            Self::MixedNtpnts => 13,
            Self::CloudSource => 14,
            Self::Ptp => 15,
            Self::Gnss => 16,
            Self::Unrecognized(v) => v,
        }
    }
}

/// `TimeZoneDatabaseEnum` (enum8).
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum TimeZoneDatabaseEnum {
    /// Full = 0.
    Full,
    /// Partial = 1.
    Partial,
    /// None = 2.
    None,
    /// A value not known to this codegen revision.
    Unknown(u8),
}

impl TimeZoneDatabaseEnum {
    /// Decode from its raw discriminant (unknown → `Unknown`).
    #[must_use]
    pub fn from_raw(v: u8) -> Self {
        match v {
            0 => Self::Full,
            1 => Self::Partial,
            2 => Self::None,
            other => Self::Unknown(other),
        }
    }
    /// The raw discriminant.
    #[must_use]
    pub fn to_raw(self) -> u8 {
        match self {
            Self::Full => 0,
            Self::Partial => 1,
            Self::None => 2,
            Self::Unknown(v) => v,
        }
    }
}

/// `TimeZoneStruct` struct.
#[derive(Clone, Debug, PartialEq)]
pub struct TimeZoneStruct {
    /// Field Offset (tag 0).
    pub offset: i32,
    /// Field ValidAt (tag 1).
    pub valid_at: u64,
    /// Field Name (tag 2).
    pub name: Option<String>,
}

/// `TrustedTimeSourceStruct` struct.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct TrustedTimeSourceStruct {
    /// Field FabricIndex (tag 0).
    pub fabric_index: u8,
    /// Field NodeId (tag 1).
    pub node_id: u64,
    /// Field Endpoint (tag 2).
    pub endpoint: u16,
}

impl DSTOffsetStruct {
    /// Decode the fields of an already-opened anonymous structure
    /// (reader positioned after the struct start; consumes to its end).
    ///
    /// # Errors
    /// Returns [`ClusterError`] on a malformed structure or missing required field.
    pub fn decode_from(r: &mut TlvReader<'_>) -> Result<Self, ClusterError> {
        let mut f_offset: Option<i32> = None;
        let mut f_valid_starting: Option<u64> = None;
        let mut f_valid_until: Option<Nullable<u64>> = None;
        loop {
            match r.next()? {
                Some(Element::ContainerEnd) => break,
                Some(Element::Scalar {
                    tag: Tag::Context(0),
                    value: Value::Int(v),
                }) => {
                    f_offset =
                        Some(i32::try_from(v).map_err(|_| ClusterError::InvalidLength("Offset"))?)
                }
                Some(Element::Scalar {
                    tag: Tag::Context(1),
                    value: Value::Uint(v),
                }) => {
                    f_valid_starting = Some(
                        u64::try_from(v)
                            .map_err(|_| ClusterError::InvalidLength("ValidStarting"))?,
                    )
                }
                Some(Element::Scalar {
                    tag: Tag::Context(2),
                    value: Value::Null,
                }) => f_valid_until = Some(Nullable::Null),
                Some(Element::Scalar {
                    tag: Tag::Context(2),
                    value: Value::Uint(v),
                }) => {
                    f_valid_until = Some(Nullable::Value(
                        u64::try_from(v).map_err(|_| ClusterError::InvalidLength("ValidUntil"))?,
                    ))
                }
                None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
                Some(Element::ContainerStart { .. }) => r.skip_container()?,
                Some(_) => {} // unknown/future scalar — skip
            }
        }
        Ok(Self {
            offset: f_offset.ok_or(ClusterError::MissingField("Offset"))?,
            valid_starting: f_valid_starting.ok_or(ClusterError::MissingField("ValidStarting"))?,
            valid_until: f_valid_until.ok_or(ClusterError::MissingField("ValidUntil"))?,
        })
    }
    /// Decode from a standalone anonymous TLV structure.
    ///
    /// # Errors
    /// Returns [`ClusterError`] if the bytes are not an anonymous structure or a field is malformed.
    pub fn decode(tlv: &[u8]) -> Result<Self, ClusterError> {
        let mut r = TlvReader::new(tlv);
        match r.next()? {
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {}
            _ => {
                return Err(ClusterError::UnexpectedType {
                    context: "DSTOffsetStruct",
                })
            }
        }
        Self::decode_from(&mut r)
    }
    /// Write this struct's fields into an already-open container.
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn write_fields(&self, w: &mut TlvWriter<'_>) {
        w.put_int(Tag::Context(0), i64::from(self.offset))
            .expect("infallible: vec writer");
        w.put_uint(Tag::Context(1), u64::from(self.valid_starting))
            .expect("infallible: vec writer");
        match &self.valid_until {
            Nullable::Null => w.put_null(Tag::Context(2)).expect("infallible: vec writer"),
            Nullable::Value(valid_until) => {
                w.put_uint(Tag::Context(2), u64::from(*valid_until))
                    .expect("infallible: vec writer");
            }
        }
    }
    /// Encode as a standalone anonymous TLV structure.
    #[must_use]
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::new();
        let mut w = TlvWriter::new(&mut buf);
        w.start_structure(Tag::Anonymous)
            .expect("infallible: vec writer");
        self.write_fields(&mut w);
        w.end_container().expect("infallible: vec writer");
        buf
    }
}

impl FabricScopedTrustedTimeSourceStruct {
    /// Decode the fields of an already-opened anonymous structure
    /// (reader positioned after the struct start; consumes to its end).
    ///
    /// # Errors
    /// Returns [`ClusterError`] on a malformed structure or missing required field.
    pub fn decode_from(r: &mut TlvReader<'_>) -> Result<Self, ClusterError> {
        let mut f_node_id: Option<u64> = None;
        let mut f_endpoint: Option<u16> = None;
        loop {
            match r.next()? {
                Some(Element::ContainerEnd) => break,
                Some(Element::Scalar {
                    tag: Tag::Context(0),
                    value: Value::Uint(v),
                }) => {
                    f_node_id =
                        Some(u64::try_from(v).map_err(|_| ClusterError::InvalidLength("NodeId"))?)
                }
                Some(Element::Scalar {
                    tag: Tag::Context(1),
                    value: Value::Uint(v),
                }) => {
                    f_endpoint = Some(
                        u16::try_from(v).map_err(|_| ClusterError::InvalidLength("Endpoint"))?,
                    )
                }
                None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
                Some(Element::ContainerStart { .. }) => r.skip_container()?,
                Some(_) => {} // unknown/future scalar — skip
            }
        }
        Ok(Self {
            node_id: f_node_id.ok_or(ClusterError::MissingField("NodeId"))?,
            endpoint: f_endpoint.ok_or(ClusterError::MissingField("Endpoint"))?,
        })
    }
    /// Decode from a standalone anonymous TLV structure.
    ///
    /// # Errors
    /// Returns [`ClusterError`] if the bytes are not an anonymous structure or a field is malformed.
    pub fn decode(tlv: &[u8]) -> Result<Self, ClusterError> {
        let mut r = TlvReader::new(tlv);
        match r.next()? {
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {}
            _ => {
                return Err(ClusterError::UnexpectedType {
                    context: "FabricScopedTrustedTimeSourceStruct",
                })
            }
        }
        Self::decode_from(&mut r)
    }
    /// Write this struct's fields into an already-open container.
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn write_fields(&self, w: &mut TlvWriter<'_>) {
        w.put_uint(Tag::Context(0), u64::from(self.node_id))
            .expect("infallible: vec writer");
        w.put_uint(Tag::Context(1), u64::from(self.endpoint))
            .expect("infallible: vec writer");
    }
    /// Encode as a standalone anonymous TLV structure.
    #[must_use]
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::new();
        let mut w = TlvWriter::new(&mut buf);
        w.start_structure(Tag::Anonymous)
            .expect("infallible: vec writer");
        self.write_fields(&mut w);
        w.end_container().expect("infallible: vec writer");
        buf
    }
}

impl TimeZoneStruct {
    /// Decode the fields of an already-opened anonymous structure
    /// (reader positioned after the struct start; consumes to its end).
    ///
    /// # Errors
    /// Returns [`ClusterError`] on a malformed structure or missing required field.
    pub fn decode_from(r: &mut TlvReader<'_>) -> Result<Self, ClusterError> {
        let mut f_offset: Option<i32> = None;
        let mut f_valid_at: Option<u64> = None;
        let mut f_name: Option<String> = None;
        loop {
            match r.next()? {
                Some(Element::ContainerEnd) => break,
                Some(Element::Scalar {
                    tag: Tag::Context(0),
                    value: Value::Int(v),
                }) => {
                    f_offset =
                        Some(i32::try_from(v).map_err(|_| ClusterError::InvalidLength("Offset"))?)
                }
                Some(Element::Scalar {
                    tag: Tag::Context(1),
                    value: Value::Uint(v),
                }) => {
                    f_valid_at =
                        Some(u64::try_from(v).map_err(|_| ClusterError::InvalidLength("ValidAt"))?)
                }
                Some(Element::Scalar {
                    tag: Tag::Context(2),
                    value: Value::Utf8(v),
                }) => f_name = Some(v),
                None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
                Some(Element::ContainerStart { .. }) => r.skip_container()?,
                Some(_) => {} // unknown/future scalar — skip
            }
        }
        Ok(Self {
            offset: f_offset.ok_or(ClusterError::MissingField("Offset"))?,
            valid_at: f_valid_at.ok_or(ClusterError::MissingField("ValidAt"))?,
            name: f_name,
        })
    }
    /// Decode from a standalone anonymous TLV structure.
    ///
    /// # Errors
    /// Returns [`ClusterError`] if the bytes are not an anonymous structure or a field is malformed.
    pub fn decode(tlv: &[u8]) -> Result<Self, ClusterError> {
        let mut r = TlvReader::new(tlv);
        match r.next()? {
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {}
            _ => {
                return Err(ClusterError::UnexpectedType {
                    context: "TimeZoneStruct",
                })
            }
        }
        Self::decode_from(&mut r)
    }
    /// Write this struct's fields into an already-open container.
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn write_fields(&self, w: &mut TlvWriter<'_>) {
        w.put_int(Tag::Context(0), i64::from(self.offset))
            .expect("infallible: vec writer");
        w.put_uint(Tag::Context(1), u64::from(self.valid_at))
            .expect("infallible: vec writer");
        if let Some(name) = &self.name {
            w.put_utf8(Tag::Context(2), &*name)
                .expect("infallible: vec writer");
        }
    }
    /// Encode as a standalone anonymous TLV structure.
    #[must_use]
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::new();
        let mut w = TlvWriter::new(&mut buf);
        w.start_structure(Tag::Anonymous)
            .expect("infallible: vec writer");
        self.write_fields(&mut w);
        w.end_container().expect("infallible: vec writer");
        buf
    }
}

impl TrustedTimeSourceStruct {
    /// Decode the fields of an already-opened anonymous structure
    /// (reader positioned after the struct start; consumes to its end).
    ///
    /// # Errors
    /// Returns [`ClusterError`] on a malformed structure or missing required field.
    pub fn decode_from(r: &mut TlvReader<'_>) -> Result<Self, ClusterError> {
        let mut f_fabric_index: Option<u8> = None;
        let mut f_node_id: Option<u64> = None;
        let mut f_endpoint: Option<u16> = None;
        loop {
            match r.next()? {
                Some(Element::ContainerEnd) => break,
                Some(Element::Scalar {
                    tag: Tag::Context(0),
                    value: Value::Uint(v),
                }) => {
                    f_fabric_index = Some(
                        u8::try_from(v).map_err(|_| ClusterError::InvalidLength("FabricIndex"))?,
                    )
                }
                Some(Element::Scalar {
                    tag: Tag::Context(1),
                    value: Value::Uint(v),
                }) => {
                    f_node_id =
                        Some(u64::try_from(v).map_err(|_| ClusterError::InvalidLength("NodeId"))?)
                }
                Some(Element::Scalar {
                    tag: Tag::Context(2),
                    value: Value::Uint(v),
                }) => {
                    f_endpoint = Some(
                        u16::try_from(v).map_err(|_| ClusterError::InvalidLength("Endpoint"))?,
                    )
                }
                None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
                Some(Element::ContainerStart { .. }) => r.skip_container()?,
                Some(_) => {} // unknown/future scalar — skip
            }
        }
        Ok(Self {
            fabric_index: f_fabric_index.ok_or(ClusterError::MissingField("FabricIndex"))?,
            node_id: f_node_id.ok_or(ClusterError::MissingField("NodeId"))?,
            endpoint: f_endpoint.ok_or(ClusterError::MissingField("Endpoint"))?,
        })
    }
    /// Decode from a standalone anonymous TLV structure.
    ///
    /// # Errors
    /// Returns [`ClusterError`] if the bytes are not an anonymous structure or a field is malformed.
    pub fn decode(tlv: &[u8]) -> Result<Self, ClusterError> {
        let mut r = TlvReader::new(tlv);
        match r.next()? {
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {}
            _ => {
                return Err(ClusterError::UnexpectedType {
                    context: "TrustedTimeSourceStruct",
                })
            }
        }
        Self::decode_from(&mut r)
    }
    /// Write this struct's fields into an already-open container.
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn write_fields(&self, w: &mut TlvWriter<'_>) {
        w.put_uint(Tag::Context(0), u64::from(self.fabric_index))
            .expect("infallible: vec writer");
        w.put_uint(Tag::Context(1), u64::from(self.node_id))
            .expect("infallible: vec writer");
        w.put_uint(Tag::Context(2), u64::from(self.endpoint))
            .expect("infallible: vec writer");
    }
    /// Encode as a standalone anonymous TLV structure.
    #[must_use]
    #[allow(clippy::expect_used)] // Vec-backed TlvWriter is infallible.
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::new();
        let mut w = TlvWriter::new(&mut buf);
        w.start_structure(Tag::Anonymous)
            .expect("infallible: vec writer");
        self.write_fields(&mut w);
        w.end_container().expect("infallible: vec writer");
        buf
    }
}

/// Decode the `UtcTime` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_utc_time(tlv: &[u8]) -> Result<Nullable<u64>, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Null, ..
        }) => Ok(Nullable::Null),
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(Nullable::Value(
            u64::try_from(v).map_err(|_| ClusterError::InvalidLength("UtcTime"))?,
        )),
        _ => Err(ClusterError::UnexpectedType { context: "UtcTime" }),
    }
}

/// Decode the `Granularity` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_granularity(tlv: &[u8]) -> Result<GranularityEnum, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(GranularityEnum::from_raw(
            u8::try_from(v).map_err(|_| ClusterError::InvalidLength("Granularity"))?,
        )),
        _ => Err(ClusterError::UnexpectedType {
            context: "Granularity",
        }),
    }
}

/// Decode the `TimeSource` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_time_source(tlv: &[u8]) -> Result<TimeSourceEnum, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(TimeSourceEnum::from_raw(
            u8::try_from(v).map_err(|_| ClusterError::InvalidLength("TimeSource"))?,
        )),
        _ => Err(ClusterError::UnexpectedType {
            context: "TimeSource",
        }),
    }
}

/// Decode the `TrustedTimeSource` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_trusted_time_source(
    tlv: &[u8],
) -> Result<Nullable<TrustedTimeSourceStruct>, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Null, ..
        }) => Ok(Nullable::Null),
        Some(Element::ContainerStart {
            kind: ContainerKind::Structure,
            ..
        }) => Ok(Nullable::Value(TrustedTimeSourceStruct::decode_from(
            &mut r,
        )?)),
        _ => Err(ClusterError::UnexpectedType {
            context: "TrustedTimeSource",
        }),
    }
}

/// Decode the `DefaultNtp` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_default_ntp(tlv: &[u8]) -> Result<Nullable<String>, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Null, ..
        }) => Ok(Nullable::Null),
        Some(Element::Scalar {
            value: Value::Utf8(v),
            ..
        }) => Ok(Nullable::Value(v)),
        _ => Err(ClusterError::UnexpectedType {
            context: "DefaultNtp",
        }),
    }
}

/// Decode the `TimeZone` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_time_zone(tlv: &[u8]) -> Result<Vec<TimeZoneStruct>, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::ContainerStart {
            kind: ContainerKind::Array,
            ..
        }) => {}
        _ => {
            return Err(ClusterError::UnexpectedType {
                context: "TimeZone",
            })
        }
    }
    let r = &mut r;
    let mut out = Vec::new();
    loop {
        match r.next()? {
            Some(Element::ContainerEnd) => break,
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {
                out.push(TimeZoneStruct::decode_from(r)?);
            }
            None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
            Some(Element::ContainerStart { .. }) => r.skip_container()?,
            Some(_) => {} // skip unknown scalar
        }
    }
    Ok(out)
}

/// Decode the `DstOffset` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_dst_offset(tlv: &[u8]) -> Result<Vec<DSTOffsetStruct>, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::ContainerStart {
            kind: ContainerKind::Array,
            ..
        }) => {}
        _ => {
            return Err(ClusterError::UnexpectedType {
                context: "DstOffset",
            })
        }
    }
    let r = &mut r;
    let mut out = Vec::new();
    loop {
        match r.next()? {
            Some(Element::ContainerEnd) => break,
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {
                out.push(DSTOffsetStruct::decode_from(r)?);
            }
            None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
            Some(Element::ContainerStart { .. }) => r.skip_container()?,
            Some(_) => {} // skip unknown scalar
        }
    }
    Ok(out)
}

/// Decode the `LocalTime` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_local_time(tlv: &[u8]) -> Result<Nullable<u64>, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Null, ..
        }) => Ok(Nullable::Null),
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(Nullable::Value(
            u64::try_from(v).map_err(|_| ClusterError::InvalidLength("LocalTime"))?,
        )),
        _ => Err(ClusterError::UnexpectedType {
            context: "LocalTime",
        }),
    }
}

/// Decode the `TimeZoneDatabase` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_time_zone_database(tlv: &[u8]) -> Result<TimeZoneDatabaseEnum, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(TimeZoneDatabaseEnum::from_raw(
            u8::try_from(v).map_err(|_| ClusterError::InvalidLength("TimeZoneDatabase"))?,
        )),
        _ => Err(ClusterError::UnexpectedType {
            context: "TimeZoneDatabase",
        }),
    }
}

/// Decode the `NtpServerAvailable` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_ntp_server_available(tlv: &[u8]) -> Result<bool, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Bool(v),
            ..
        }) => Ok(v),
        _ => Err(ClusterError::UnexpectedType {
            context: "NtpServerAvailable",
        }),
    }
}

/// Decode the `TimeZoneListMaxSize` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_time_zone_list_max_size(tlv: &[u8]) -> Result<u8, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(u8::try_from(v).map_err(|_| ClusterError::InvalidLength("TimeZoneListMaxSize"))?),
        _ => Err(ClusterError::UnexpectedType {
            context: "TimeZoneListMaxSize",
        }),
    }
}

/// Decode the `DstOffsetListMaxSize` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_dst_offset_list_max_size(tlv: &[u8]) -> Result<u8, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Uint(v),
            ..
        }) => Ok(u8::try_from(v).map_err(|_| ClusterError::InvalidLength("DstOffsetListMaxSize"))?),
        _ => Err(ClusterError::UnexpectedType {
            context: "DstOffsetListMaxSize",
        }),
    }
}

/// Decode the `SupportsDnsResolve` attribute value.
///
/// # Errors
/// Returns [`ClusterError`] on a type mismatch or out-of-range value.
pub fn decode_supports_dns_resolve(tlv: &[u8]) -> Result<bool, ClusterError> {
    let mut r = TlvReader::new(tlv);
    match r.next()? {
        Some(Element::Scalar {
            value: Value::Bool(v),
            ..
        }) => Ok(v),
        _ => Err(ClusterError::UnexpectedType {
            context: "SupportsDnsResolve",
        }),
    }
}

/// Encode the `SetUtcTime` command request payload.
#[must_use]
#[allow(clippy::expect_used, clippy::missing_panics_doc)] // Vec-backed TlvWriter is infallible.
pub fn encode_set_utc_time(
    utc_time: u64,
    granularity: GranularityEnum,
    time_source: Option<TimeSourceEnum>,
) -> Vec<u8> {
    let mut buf = Vec::new();
    let mut w = TlvWriter::new(&mut buf);
    w.start_structure(Tag::Anonymous)
        .expect("infallible: vec writer");
    w.put_uint(Tag::Context(0), u64::from(utc_time))
        .expect("infallible: vec writer");
    w.put_uint(Tag::Context(1), u64::from(granularity.to_raw()))
        .expect("infallible: vec writer");
    if let Some(time_source) = time_source {
        w.put_uint(Tag::Context(2), u64::from(time_source.to_raw()))
            .expect("infallible: vec writer");
    }
    w.end_container().expect("infallible: vec writer");
    buf
}

/// Encode the `SetTrustedTimeSource` command request payload.
#[must_use]
#[allow(clippy::expect_used, clippy::missing_panics_doc)] // Vec-backed TlvWriter is infallible.
pub fn encode_set_trusted_time_source(
    trusted_time_source: Nullable<FabricScopedTrustedTimeSourceStruct>,
) -> Vec<u8> {
    let mut buf = Vec::new();
    let mut w = TlvWriter::new(&mut buf);
    w.start_structure(Tag::Anonymous)
        .expect("infallible: vec writer");
    match &trusted_time_source {
        Nullable::Null => w.put_null(Tag::Context(0)).expect("infallible: vec writer"),
        Nullable::Value(trusted_time_source) => {
            w.start_structure(Tag::Context(0))
                .expect("infallible: vec writer");
            trusted_time_source.write_fields(&mut w);
            w.end_container().expect("infallible: vec writer");
        }
    }
    w.end_container().expect("infallible: vec writer");
    buf
}

/// Encode the `SetTimeZone` command request payload.
#[must_use]
#[allow(clippy::expect_used, clippy::missing_panics_doc)] // Vec-backed TlvWriter is infallible.
pub fn encode_set_time_zone(time_zone: &Vec<TimeZoneStruct>) -> Vec<u8> {
    let mut buf = Vec::new();
    let mut w = TlvWriter::new(&mut buf);
    w.start_structure(Tag::Anonymous)
        .expect("infallible: vec writer");
    w.start_array(Tag::Context(0))
        .expect("infallible: vec writer");
    for el in time_zone.iter() {
        w.start_structure(Tag::Anonymous)
            .expect("infallible: vec writer");
        el.write_fields(&mut w);
        w.end_container().expect("infallible: vec writer");
    }
    w.end_container().expect("infallible: vec writer");
    w.end_container().expect("infallible: vec writer");
    buf
}

/// Decoded `SetTimeZoneResponse` payload.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct SetTimeZoneResponse {
    /// Field DstOffsetRequired (tag 0).
    pub dst_offset_required: bool,
}

impl SetTimeZoneResponse {
    /// Decode the fields of an already-opened anonymous structure
    /// (reader positioned after the struct start; consumes to its end).
    ///
    /// # Errors
    /// Returns [`ClusterError`] on a malformed structure or missing required field.
    pub fn decode_from(r: &mut TlvReader<'_>) -> Result<Self, ClusterError> {
        let mut f_dst_offset_required: Option<bool> = None;
        loop {
            match r.next()? {
                Some(Element::ContainerEnd) => break,
                Some(Element::Scalar {
                    tag: Tag::Context(0),
                    value: Value::Bool(v),
                }) => f_dst_offset_required = Some(v),
                None => return Err(ClusterError::Tlv(matter_codec::Error::UnclosedContainer)),
                Some(Element::ContainerStart { .. }) => r.skip_container()?,
                Some(_) => {} // unknown/future scalar — skip
            }
        }
        Ok(Self {
            dst_offset_required: f_dst_offset_required
                .ok_or(ClusterError::MissingField("DstOffsetRequired"))?,
        })
    }
    /// Decode from a standalone anonymous TLV structure.
    ///
    /// # Errors
    /// Returns [`ClusterError`] if the bytes are not an anonymous structure or a field is malformed.
    pub fn decode(tlv: &[u8]) -> Result<Self, ClusterError> {
        let mut r = TlvReader::new(tlv);
        match r.next()? {
            Some(Element::ContainerStart {
                kind: ContainerKind::Structure,
                ..
            }) => {}
            _ => {
                return Err(ClusterError::UnexpectedType {
                    context: "SetTimeZoneResponse",
                })
            }
        }
        Self::decode_from(&mut r)
    }
}

/// Encode the `SetDstOffset` command request payload.
#[must_use]
#[allow(clippy::expect_used, clippy::missing_panics_doc)] // Vec-backed TlvWriter is infallible.
pub fn encode_set_dst_offset(dst_offset: &Vec<DSTOffsetStruct>) -> Vec<u8> {
    let mut buf = Vec::new();
    let mut w = TlvWriter::new(&mut buf);
    w.start_structure(Tag::Anonymous)
        .expect("infallible: vec writer");
    w.start_array(Tag::Context(0))
        .expect("infallible: vec writer");
    for el in dst_offset.iter() {
        w.start_structure(Tag::Anonymous)
            .expect("infallible: vec writer");
        el.write_fields(&mut w);
        w.end_container().expect("infallible: vec writer");
    }
    w.end_container().expect("infallible: vec writer");
    w.end_container().expect("infallible: vec writer");
    buf
}

/// Encode the `SetDefaultNtp` command request payload.
#[must_use]
#[allow(clippy::expect_used, clippy::missing_panics_doc)] // Vec-backed TlvWriter is infallible.
pub fn encode_set_default_ntp(default_ntp: Nullable<String>) -> Vec<u8> {
    let mut buf = Vec::new();
    let mut w = TlvWriter::new(&mut buf);
    w.start_structure(Tag::Anonymous)
        .expect("infallible: vec writer");
    match default_ntp {
        Nullable::Null => w.put_null(Tag::Context(0)).expect("infallible: vec writer"),
        Nullable::Value(default_ntp) => {
            w.put_utf8(Tag::Context(0), &default_ntp)
                .expect("infallible: vec writer");
        }
    }
    w.end_container().expect("infallible: vec writer");
    buf
}