dvb-ci 0.11.0

//! Conditional Access Support — CI Plus multi-stream `ca_pmt` / `ca_pmt_reply` —
//! ETSI TS 103 205 V1.4.1 §6.4.4, Tables 14/16 (PDF pp. 38-40). See
//! `private/specs-verified/dvb/dvb-ci/ts_103_205/ca-support.md`.
//!
//! For multi-stream functionality the CA Support resource gets a new
//! `resource_type` (= 2, version = 1) in which `ca_pmt()` and `ca_pmt_reply()`
//! are extended with a leading `LTS_id`; `ca_pmt()` additionally carries a
//! `PMT_PID`. The apdu_tags are unchanged (`ca_pmt` `0x9F8032`, `ca_pmt_reply`
//! `0x9F8033`).
//!
//! ## Deferred resource_id
//!
//! TS 103 205 §6.4.4.1 (render-verified) does **not** print a full 32-bit
//! `resource_identifier` for this resource_type — only the prose
//! "resource_type = 2, version = 1". The authoritative value is in CI Plus V1.3
//! \[3\]. So these objects are provided as standalone, directly-constructible /
//! parseable typed structs (full `Parse`/`Serialize`) and are **not** wired into
//! [`crate::ci_plus::CiPlusApdu`]'s resource dispatch — there is no invented
//! resource_id constant. A small [`CaSupportApdu::parse`] helper dispatches on
//! the apdu_tag for callers that already know they are in a multi-stream CA
//! Support session.
//!
//! These extended bodies reuse the EN 50221 value enums (`ca_pmt_list_management`,
//! `ca_pmt_cmd_id`, `CA_enable`); Table 15 narrows `ca_pmt_list_management` to the
//! `{Only=0x03, Update=0x05}` subset in multi-stream mode (a usage constraint —
//! any value still round-trips via the full enum).

use crate::error::{Error, Result};
use crate::objects;
use crate::objects::ca_pmt::{
    CaPmtCmdId, CaPmtListManagement, CaPmtStream, checked_streams_len, info_block_len,
    parse_cmd_and_descriptors, parse_streams, streams_len, write_info_block, write_streams,
};
use crate::objects::ca_pmt_reply::{
    CaEnable, CaPmtReplyStream, decode_enable_byte, encode_enable_byte, parse_reply_streams,
    reply_streams_len, write_reply_streams,
};
use crate::reserved::ReservedOnes;
use crate::tag::{CA_PMT, CA_PMT_REPLY};
use alloc::vec::Vec;
use broadcast_common::len::need_in;
use broadcast_common::{Parse, Serialize};
use mpeg_ts::pid::Pid;

// Re-export the shared value enums so callers needn't reach into `objects`.
pub use crate::objects::ca_pmt::{
    CaPmtCmdId as MsCaPmtCmdId, CaPmtListManagement as MsCaPmtListManagement,
};
pub use crate::objects::ca_pmt_reply::CaEnable as MsCaEnable;

// ---------------------------------------------------------------------------
// ca_pmt (Table 14)
// ---------------------------------------------------------------------------

/// CI Plus multi-stream `ca_pmt()` (Table 14): Host → CICAM. Differs from the
/// EN 50221 `ca_pmt` by the leading `LTS_id` and the added `PMT_PID`.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct MsCaPmt<'a> {
    /// How the `length_field` was coded on the wire: a non-minimal long form
    /// (e.g. `82 00 09`) is preserved so the object re-serializes
    /// byte-for-byte; [`LengthForm::Minimal`](crate::length::LengthForm::Minimal) for a hand-built value.
    #[cfg_attr(feature = "serde", serde(skip))]
    pub length_form: crate::length::LengthForm,

    /// `LTS_id` (8) — Local TS identifier.
    pub lts_id: u8,
    /// `ca_pmt_list_management` (Table 15 narrows to `{Only, Update}`).
    pub list_management: CaPmtListManagement,
    /// `program_number` (16).
    pub program_number: u16,
    /// `PMT_PID` (13) — PID of the selected service's PMT.
    pub pmt_pid: Pid,
    /// 5-bit `version_number`.
    pub version_number: u8,
    /// `current_next_indicator`.
    pub current_next_indicator: bool,
    /// Programme-level `ca_pmt_cmd_id` — present only when `program_info_length != 0`.
    pub cmd_id: Option<CaPmtCmdId>,
    /// Programme-level `CA_descriptor()` loop, verbatim wire bytes (no `cmd_id`).
    #[cfg_attr(feature = "serde", serde(borrow, with = "crate::objects::bytes_serde"))]
    pub program_ca_descriptors: &'a [u8],
    /// Elementary streams in wire order.
    #[cfg_attr(feature = "serde", serde(borrow))]
    pub streams: Vec<CaPmtStream<'a>>,
    /// The 3-bit `reserved` field as received, preserved so the object
    /// re-serializes byte-for-byte; all ones when hand-built. (before `PMT_PID`)
    #[cfg_attr(feature = "serde", serde(skip))]
    pub reserved_pmt_pid: ReservedOnes<3>,
    /// The 2-bit `reserved` field as received, preserved so the object
    /// re-serializes byte-for-byte; all ones when hand-built. (before `version_number`)
    #[cfg_attr(feature = "serde", serde(skip))]
    pub reserved_version: ReservedOnes<2>,
    /// The 4-bit `reserved` field as received, preserved so the object
    /// re-serializes byte-for-byte; all ones when hand-built. (before `program_info_length`)
    #[cfg_attr(feature = "serde", serde(skip))]
    pub reserved_program_info: ReservedOnes<4>,
}

// LTS_id(1) + list_management(1) + program_number(2) + reserved/PMT_PID(2) +
// reserved/version/cni(1) + reserved/program_info_length(2).
const MS_CA_PMT_PREFIX: usize = 1 + 1 + 2 + 2 + 1 + 2;

impl<'a> Parse<'a> for MsCaPmt<'a> {
    type Error = Error;
    fn parse(bytes: &'a [u8]) -> Result<Self> {
        let (length_form, body) = crate::objects::parse_apdu_header(bytes, CA_PMT, "ms ca_pmt")?;
        need_in(body, MS_CA_PMT_PREFIX, "ms ca_pmt prefix")?;
        let lts_id = body[0];
        let list_management = CaPmtListManagement::from_u8(body[1]);
        let program_number = u16::from_be_bytes([body[2], body[3]]);
        // reserved(3) + PMT_PID(13).
        let pmt_pid = Pid::new((((body[4] & 0x1F) as u16) << 8) | body[5] as u16);
        let reserved_pmt_pid = ReservedOnes::from_bits(body[4] >> 5);
        let reserved_version = ReservedOnes::from_bits(body[6] >> 6);
        let reserved_program_info = ReservedOnes::from_bits(body[7] >> 4);
        // reserved(2) + version(5) + cni(1).
        let version_number = (body[6] >> 1) & 0x1F;
        let current_next_indicator = (body[6] & 0x01) != 0;
        // reserved(4) + program_info_length(12).
        let program_info_length = (((body[7] & 0x0F) as usize) << 8) | body[8] as usize;

        let mut pos = MS_CA_PMT_PREFIX;
        let (cmd_id, program_ca_descriptors) = parse_cmd_and_descriptors(
            body,
            &mut pos,
            program_info_length,
            "ms ca_pmt program_info",
        )?;

        let streams = parse_streams(body, pos, "ms ca_pmt ES prefix", "ms ca_pmt ES_info")?;

        Ok(Self {
            length_form,
            lts_id,
            list_management,
            program_number,
            pmt_pid,
            version_number,
            current_next_indicator,
            cmd_id,
            program_ca_descriptors,
            streams,
            reserved_pmt_pid,
            reserved_version,
            reserved_program_info,
        })
    }
}

impl Serialize for MsCaPmt<'_> {
    type Error = Error;
    fn serialized_len(&self) -> usize {
        let body = MS_CA_PMT_PREFIX
            + info_block_len(self.cmd_id, self.program_ca_descriptors)
            + streams_len(&self.streams);
        crate::objects::apdu_len(body, self.length_form)
    }
    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
        objects::fit_bits(
            u64::from(self.version_number),
            5,
            "ms ca_pmt version_number",
        )?;
        let program_info_length = info_block_len(self.cmd_id, self.program_ca_descriptors);
        objects::fit_bits(
            program_info_length as u64,
            12,
            "ms ca_pmt program_info_length",
        )?;
        let body = MS_CA_PMT_PREFIX
            + program_info_length
            + checked_streams_len(&self.streams, "ms ca_pmt ES_info_length")?;
        let mut pos = crate::objects::write_apdu_header(CA_PMT, body, self.length_form, buf)?;
        buf[pos] = self.lts_id;
        buf[pos + 1] = self.list_management.to_u8();
        buf[pos + 2..pos + 4].copy_from_slice(&self.program_number.to_be_bytes());
        // reserved(3), PMT_PID(13). Range-checked above.
        buf[pos + 4] = (self.reserved_pmt_pid.get() << 5) | (self.pmt_pid.value() >> 8) as u8;
        buf[pos + 5] = self.pmt_pid.value() as u8;
        // reserved(2), version(5), current_next(1). Range-checked above.
        buf[pos + 6] = (self.reserved_version.get() << 6)
            | (self.version_number << 1)
            | u8::from(self.current_next_indicator);
        // reserved(4), program_info_length(12). Range-checked above.
        buf[pos + 7] = (self.reserved_program_info.get() << 4) | (program_info_length >> 8) as u8;
        buf[pos + 8] = program_info_length as u8;
        pos += MS_CA_PMT_PREFIX;
        pos += write_info_block(self.cmd_id, self.program_ca_descriptors, &mut buf[pos..])?;

        write_streams(buf, pos, &self.streams)
    }
}

// ---------------------------------------------------------------------------
// ca_pmt_reply (Table 16)
// ---------------------------------------------------------------------------

/// CI Plus multi-stream `ca_pmt_reply()` (Table 16): CICAM → Host. Differs from
/// the EN 50221 `ca_pmt_reply` by the leading `LTS_id`.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct MsCaPmtReply {
    /// How the `length_field` was coded on the wire: a non-minimal long form
    /// (e.g. `82 00 09`) is preserved so the object re-serializes
    /// byte-for-byte; [`LengthForm::Minimal`](crate::length::LengthForm::Minimal) for a hand-built value.
    #[cfg_attr(feature = "serde", serde(skip))]
    pub length_form: crate::length::LengthForm,

    /// `LTS_id` (8) — Local TS identifier.
    pub lts_id: u8,
    /// `program_number` (16).
    pub program_number: u16,
    /// 5-bit `version_number`.
    pub version_number: u8,
    /// `current_next_indicator`.
    pub current_next_indicator: bool,
    /// Programme-level `CA_enable` — `Some` iff the programme `CA_enable_flag` bit
    /// was set.
    pub ca_enable: Option<CaEnable>,
    /// Per-ES entries in wire order.
    pub streams: Vec<CaPmtReplyStream>,
    /// The 2-bit `reserved` field as received, preserved so the object
    /// re-serializes byte-for-byte; all ones when hand-built. (before `version_number`)
    #[cfg_attr(feature = "serde", serde(skip))]
    pub reserved_version: ReservedOnes<2>,
    /// The 7-bit field after `CA_enable_flag` when the flag is clear (`reserved`),
    /// as received so the object re-serializes byte-for-byte; ignored on
    /// serialize when `ca_enable` is `Some`. `0b111_1111` when hand-built.
    #[cfg_attr(feature = "serde", serde(skip))]
    pub reserved_ca_enable: ReservedOnes<7>,
}

// LTS_id(1) + program_number(2) + reserved/version/cni(1) + flag/enable(1).
const MS_REPLY_PREFIX: usize = 1 + 2 + 1 + 1;

impl<'a> Parse<'a> for MsCaPmtReply {
    type Error = Error;
    fn parse(bytes: &'a [u8]) -> Result<Self> {
        let (length_form, body) =
            crate::objects::parse_apdu_header(bytes, CA_PMT_REPLY, "ms ca_pmt_reply")?;
        need_in(body, MS_REPLY_PREFIX, "ms ca_pmt_reply prefix")?;
        let lts_id = body[0];
        let program_number = u16::from_be_bytes([body[1], body[2]]);
        let version_number = (body[3] >> 1) & 0x1F;
        let current_next_indicator = (body[3] & 0x01) != 0;
        let (ca_enable, reserved_ca_enable) = decode_enable_byte(body[4]);

        let streams = parse_reply_streams(body, MS_REPLY_PREFIX, "ms ca_pmt_reply ES")?;

        Ok(Self {
            length_form,
            lts_id,
            program_number,
            version_number,
            current_next_indicator,
            ca_enable,
            streams,
            reserved_version: ReservedOnes::from_bits(body[3] >> 6),
            reserved_ca_enable,
        })
    }
}

impl Serialize for MsCaPmtReply {
    type Error = Error;
    fn serialized_len(&self) -> usize {
        crate::objects::apdu_len(
            MS_REPLY_PREFIX + reply_streams_len(&self.streams),
            self.length_form,
        )
    }
    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
        objects::fit_bits(
            u64::from(self.version_number),
            5,
            "ms ca_pmt_reply version_number",
        )?;
        let body = MS_REPLY_PREFIX + reply_streams_len(&self.streams);
        let mut pos = crate::objects::write_apdu_header(CA_PMT_REPLY, body, self.length_form, buf)?;
        buf[pos] = self.lts_id;
        buf[pos + 1..pos + 3].copy_from_slice(&self.program_number.to_be_bytes());
        // reserved(2), version(5), current_next(1). Range-checked above.
        buf[pos + 3] = (self.reserved_version.get() << 6)
            | (self.version_number << 1)
            | u8::from(self.current_next_indicator);
        buf[pos + 4] = encode_enable_byte(self.ca_enable, self.reserved_ca_enable);
        pos += MS_REPLY_PREFIX;
        Ok(write_reply_streams(buf, pos, &self.streams))
    }
}

// ---------------------------------------------------------------------------
// apdu-tag dispatch helper (no resource_id — see module doc)
// ---------------------------------------------------------------------------

crate::dispatch::declare_resource_apdus! {
    /// A parsed CI Plus multi-stream CA-support object.
    ///
    /// There is intentionally **no** `resource_id`-keyed entry point for these
    /// objects: TS 103 205 does not print the resource_id (see the module doc), so
    /// dispatch is on the apdu_tag alone, for callers already in a multi-stream CA
    /// Support session.
    #[derive(Debug, Clone, PartialEq, Eq)]
    #[cfg_attr(feature = "serde", derive(serde::Serialize))]
    #[non_exhaustive]
    pub enum CaSupportApdu<'a> ("ca_support") {
        /// `ca_pmt` (`9F 80 32`), CI Plus multi-stream variant.
        CaPmt(MsCaPmt<'a>) = CA_PMT,
        /// `ca_pmt_reply` (`9F 80 33`), CI Plus multi-stream variant.
        CaPmtReply(MsCaPmtReply) = CA_PMT_REPLY,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::objects::ca_pmt::CA_DESCRIPTOR_TAG;

    fn sample_ca_descriptor(ca_system_id: u16, pid: u16) -> [u8; 6] {
        [
            CA_DESCRIPTOR_TAG,
            0x04,
            (ca_system_id >> 8) as u8,
            ca_system_id as u8,
            0xE0 | ((pid >> 8) as u8 & 0x1F),
            pid as u8,
        ]
    }

    #[test]
    fn ms_ca_pmt_round_trips_and_bites() {
        let prog = sample_ca_descriptor(0x1234, 0x0100);
        let es_desc = sample_ca_descriptor(0x1234, 0x0101);
        let pmt = MsCaPmt {
            reserved_program_info: Default::default(),
            reserved_version: Default::default(),
            reserved_pmt_pid: Default::default(),
            length_form: crate::length::LengthForm::Minimal,
            lts_id: 0x02,
            list_management: CaPmtListManagement::Only,
            program_number: 0x0001,
            pmt_pid: Pid::new(0x0064),
            version_number: 1,
            current_next_indicator: true,
            cmd_id: Some(CaPmtCmdId::OkDescrambling),
            program_ca_descriptors: &prog,
            streams: alloc::vec![CaPmtStream {
                reserved_es_info: Default::default(),
                reserved_pid: Default::default(),
                stream_type: 0x02,
                elementary_pid: Pid::new(0x0200),
                cmd_id: Some(CaPmtCmdId::OkDescrambling),
                ca_descriptors: &es_desc,
            }],
        };
        let bytes = pmt.try_to_bytes().unwrap();
        // Hand-computed body:
        //   LTS_id 02 | list_mgmt 03 | prog_num 00 01 | reserved+PMT_PID E0 64
        //   reserved+ver1+cni1 = 0xC0|0x02|0x01 = 0xC3
        //   reserved+prog_info_len(7) = F0 07 ; cmd_id 01 + 6 desc bytes
        //   ES: stream_type 02 | E0 00 (pid 0x200 -> hi 0x02) wait pid 0x0200
        let pid = 0x0200u16;
        let es_hi = 0xE0 | ((pid >> 8) as u8 & 0x1F);
        let expected = {
            let mut v = alloc::vec![
                0x9F, 0x80, 0x32, // tag
                0x1C, // length (28 body bytes)
                0x02, // LTS_id
                0x03, // list_management Only
                0x00, 0x01, // program_number
                0xE0, 0x64, // reserved + PMT_PID 0x0064
                0xC3, // reserved + version 1 + cni 1
                0xF0, 0x07, // reserved + program_info_length 7
                0x01, // program ca_pmt_cmd_id ok_descrambling
            ];
            v.extend_from_slice(&prog); // 6 bytes
            v.extend_from_slice(&[0x02, es_hi, 0x00, 0xF0, 0x07, 0x01]); // ES prefix + es_info_len + cmd
            v.extend_from_slice(&es_desc); // 6 bytes
            v
        };
        assert_eq!(bytes, expected);
        assert_eq!(MsCaPmt::parse(&bytes).unwrap(), pmt);
        // Field-mutation: change PMT_PID.
        let mut other = pmt.clone();
        other.pmt_pid = Pid::new(0x0065);
        assert_ne!(bytes, other.try_to_bytes().unwrap());
    }

    #[test]
    fn ms_ca_pmt_no_descriptors() {
        let pmt = MsCaPmt {
            reserved_program_info: Default::default(),
            reserved_version: Default::default(),
            reserved_pmt_pid: Default::default(),
            length_form: crate::length::LengthForm::Minimal,
            lts_id: 0x00,
            list_management: CaPmtListManagement::Update,
            program_number: 0x0009,
            pmt_pid: Pid::new(0x1FFF),
            version_number: 0,
            current_next_indicator: true,
            cmd_id: None,
            program_ca_descriptors: &[],
            streams: Vec::new(),
        };
        let bytes = pmt.try_to_bytes().unwrap();
        // PMT_PID 0x1FFF -> hi 0xE0|0x1F=0xFF, lo 0xFF; prog_info_len 0 -> F0 00.
        assert_eq!(
            bytes,
            [
                0x9F, 0x80, 0x32, 0x09, 0x00, 0x05, 0x00, 0x09, 0xFF, 0xFF, 0xC1, 0xF0, 0x00
            ]
        );
        assert_eq!(MsCaPmt::parse(&bytes).unwrap(), pmt);
    }

    #[test]
    fn ms_ca_pmt_reply_round_trips_and_bites() {
        let reply = MsCaPmtReply {
            reserved_ca_enable: Default::default(),
            reserved_version: Default::default(),
            length_form: crate::length::LengthForm::Minimal,
            lts_id: 0x03,
            program_number: 0x0001,
            version_number: 1,
            current_next_indicator: true,
            ca_enable: Some(CaEnable::Possible),
            streams: alloc::vec![
                CaPmtReplyStream {
                    reserved_ca_enable: Default::default(),
                    reserved_pid: Default::default(),
                    elementary_pid: Pid::new(0x0200),
                    ca_enable: Some(CaEnable::Possible),
                },
                CaPmtReplyStream {
                    reserved_ca_enable: Default::default(),
                    reserved_pid: Default::default(),
                    elementary_pid: Pid::new(0x0201),
                    ca_enable: None,
                },
            ],
        };
        let bytes = reply.try_to_bytes().unwrap();
        let expected = [
            0x9F, 0x80, 0x33, // tag
            0x0B, // length (11 body bytes)
            0x03, // LTS_id
            0x00, 0x01, // program_number
            0xC3, // reserved + version 1 + cni 1
            0x81, // flag=1 + CA_enable Possible(0x01)
            0xE2, 0x00, 0x81, // ES pid 0x200 + flag/enable Possible
            0xE2, 0x01, 0x7F, // ES pid 0x201 + no enable (0x7F)
        ];
        assert_eq!(bytes, expected);
        assert_eq!(MsCaPmtReply::parse(&bytes).unwrap(), reply);
        // Field-mutation: change LTS_id.
        let mut other = reply.clone();
        other.lts_id = 0x04;
        assert_ne!(bytes, other.try_to_bytes().unwrap());
        assert_eq!(other.try_to_bytes().unwrap()[4], 0x04);
    }

    #[test]
    fn dispatch_helper_routes_by_tag() {
        let pmt = MsCaPmt {
            reserved_program_info: Default::default(),
            reserved_version: Default::default(),
            reserved_pmt_pid: Default::default(),
            length_form: crate::length::LengthForm::Minimal,
            lts_id: 0,
            list_management: CaPmtListManagement::Only,
            program_number: 1,
            pmt_pid: Pid::new(0x64),
            version_number: 0,
            current_next_indicator: true,
            cmd_id: None,
            program_ca_descriptors: &[],
            streams: Vec::new(),
        };
        let bytes = pmt.try_to_bytes().unwrap();
        let parsed = CaSupportApdu::parse(&bytes).unwrap();
        assert!(matches!(parsed, CaSupportApdu::CaPmt(_)));
        assert_eq!(parsed.try_to_bytes().unwrap(), bytes);

        let reply = MsCaPmtReply {
            reserved_ca_enable: Default::default(),
            reserved_version: Default::default(),
            length_form: crate::length::LengthForm::Minimal,
            lts_id: 1,
            program_number: 1,
            version_number: 0,
            current_next_indicator: true,
            ca_enable: None,
            streams: Vec::new(),
        };
        let rb = reply.try_to_bytes().unwrap();
        assert!(matches!(
            CaSupportApdu::parse(&rb).unwrap(),
            CaSupportApdu::CaPmtReply(_)
        ));
    }

    #[test]
    fn max_pmt_pid_still_serializes_and_round_trips() {
        let pmt = MsCaPmt {
            reserved_program_info: Default::default(),
            reserved_version: Default::default(),
            reserved_pmt_pid: Default::default(),
            length_form: crate::length::LengthForm::Minimal,
            lts_id: 0,
            list_management: CaPmtListManagement::Only,
            program_number: 1,
            pmt_pid: Pid::new(0x1FFF),
            version_number: 0,
            current_next_indicator: true,
            cmd_id: None,
            program_ca_descriptors: &[],
            streams: Vec::new(),
        };
        let bytes = pmt.try_to_bytes().unwrap();
        assert_eq!(MsCaPmt::parse(&bytes).unwrap(), pmt);
    }

    #[test]
    fn oversized_pids_are_unrepresentable() {
        // The 13-bit PID fields are typed `Pid`: a value that previously had
        // to be rejected at serialize time cannot be constructed at all.
        assert_eq!(Pid::try_new(0x2064).unwrap_err().value, 0x2064);
        assert!(Pid::try_new(0x1FFF).is_ok());
    }
}