dvb_ci_runtime/
event.rs

1//! The sans-IO event/action model.
2//!
3//! The protocol core is pure: it consumes [`Event`]s and produces [`Action`]s,
4//! with no device, threads, or clock of its own. The driver loop executes the
5//! actions against a [`CaDevice`](crate::CaDevice) and feeds events back. This
6//! keeps every state machine deterministic and testable without
7//! hardware — a test (or a differential comparison against an external
8//! reference) drives a sequence of events and asserts the emitted action
9//! sequence.
10
11use std::time::Duration;
12
13use dvb_ci::resource::ResourceId;
14
15/// An input to the protocol core.
16#[derive(Debug, Clone, PartialEq, Eq)]
17#[non_exhaustive]
18pub enum Event<'a> {
19    /// One link-layer frame was read from the device.
20    Readable(&'a [u8]),
21    /// Logical time advanced by `elapsed` since the last tick (drives poll
22    /// cadence and resource timers without a real clock in the core).
23    Tick {
24        /// Time since the previous tick.
25        elapsed: Duration,
26    },
27    /// A request from the host application.
28    Host(HostRequest<'a>),
29}
30
31/// A request the host application makes of the stack.
32#[derive(Debug, Clone, PartialEq, Eq)]
33#[non_exhaustive]
34pub enum HostRequest<'a> {
35    /// Bring the interface up: reset the slot and open the transport connection.
36    Init,
37    /// Send a serialized `ca_pmt` APDU body to the CAM's conditional-access
38    /// resource (descrambling request).
39    SendCaPmt(&'a [u8]),
40    /// Answer an MMI `menu`/`list` by 1-based `choice_ref` (0 = "back"/cancel),
41    /// sent as `menu_answ` to the module.
42    MmiMenuAnswer(u8),
43    /// Answer an MMI `enquiry` with the user's input text (EN 300 468 Annex A
44    /// bytes), sent as `answ` (`answ_id = answer`).
45    MmiEnquiryAnswer(&'a [u8]),
46    /// Abort the current MMI enquiry (`answ` with `answ_id = cancel`).
47    MmiCancel,
48    /// Ask the module to open its MMI menu (`enter_menu` on the
49    /// application_information session) — e.g. to read card / entitlement info.
50    EnterMenu,
51    /// Descramble the services in a PMT section (raw `dvb-si` PMT bytes). The
52    /// stack filters the PMT's `CA_descriptor`s to the CAM's advertised CAIDs
53    /// (from its `ca_info`) and sends a `ca_pmt` with `list_management = only`,
54    /// `cmd_id = ok_descrambling`. The reply outcome surfaces as
55    /// [`Notification::CaPmtReply`].
56    Descramble(&'a [u8]),
57    /// Descramble a **set** of programmes in one CA-PMT list (`first`/`more`/
58    /// `last`, all `ok_descrambling`), replacing any prior set. Each element is a
59    /// raw PMT section.
60    DescramblePrograms(&'a [&'a [u8]]),
61    /// Add one programme to the descrambled set (`list_management = add`).
62    AddProgram(&'a [u8]),
63    /// Remove one programme from the descrambled set (`list_management = update`,
64    /// `cmd_id = not_selected`).
65    RemoveProgram(&'a [u8]),
66    /// Tear the interface down (close sessions + transport connection).
67    Shutdown,
68}
69
70/// An output the driver loop must perform.
71#[derive(Debug, Clone, PartialEq, Eq)]
72#[non_exhaustive]
73pub enum Action {
74    /// Write one link-layer frame to the device.
75    Write(Vec<u8>),
76    /// Issue the `CA_RESET` ioctl.
77    Reset,
78    /// Issue the `CA_GET_SLOT_INFO` ioctl.
79    QuerySlot,
80    /// Arm the poll/timer to fire after `after` (coalesced: the latest wins).
81    SetTimer {
82        /// Delay before the next [`Event::Tick`] should be delivered.
83        after: Duration,
84    },
85    /// Surface a host-facing [`Notification`].
86    Notify(Notification),
87}
88
89/// A host-facing event surfaced by the stack (the useful outputs of a CI
90/// session — what an application reacts to).
91#[derive(Debug, Clone, PartialEq, Eq)]
92#[non_exhaustive]
93pub enum Notification {
94    /// The module is present and the resource-manager handshake completed.
95    CamReady,
96    /// `application_information` was received.
97    ApplicationInfo {
98        /// `application_type` (0x01 = CA).
99        application_type: u8,
100        /// `application_manufacturer`.
101        manufacturer: u16,
102        /// `manufacturer_code`.
103        code: u16,
104        /// The decoded menu string.
105        menu: String,
106    },
107    /// `ca_info` was received — the CA system ids the module supports.
108    CaInfo {
109        /// `CA_system_id` values the CAM can descramble.
110        ca_system_ids: Vec<u16>,
111    },
112    /// A `ca_pmt_reply` was received for a prior CA_PMT.
113    CaPmtReply {
114        /// `program_number` the reply pertains to.
115        program_number: u16,
116        /// Raw `CA_enable`/descrambling-possibility bytes (per-program/ES).
117        descrambling_ok: bool,
118    },
119    /// An MMI menu/enquiry the host should display.
120    Mmi(MmiEvent),
121    /// A session for `resource` was opened.
122    SessionOpened {
123        /// The resource the session serves.
124        resource: ResourceId,
125    },
126    /// A session closed.
127    SessionClosed {
128        /// The `session_nb` that closed.
129        session_nb: u16,
130    },
131    /// A protocol error surfaced by the stack (non-fatal; informational).
132    Error {
133        /// Human-readable detail.
134        detail: String,
135    },
136}
137
138/// A decoded high-level MMI `menu()` / `list()` ready for display (§8.6.5,
139/// Tables 49/51). The three header lines and the choice list are kept separate
140/// so a UI can render them directly — a title bar, two sub-lines, and a list of
141/// selectable rows — without re-parsing.
142#[derive(Debug, Clone, PartialEq, Eq, Default)]
143pub struct MmiMenu {
144    /// Title line.
145    pub title: String,
146    /// Sub-title line (often a section heading).
147    pub subtitle: String,
148    /// Bottom line (often a hint such as "Select item and press OK").
149    pub bottom: String,
150    /// The selectable choices, in wire order. Answer the Nth (1-based) with
151    /// [`Driver::mmi_menu_answer`](crate::Driver::mmi_menu_answer)`(N)`; `0`
152    /// cancels / goes back.
153    pub choices: Vec<String>,
154}
155
156/// MMI (man-machine interface) host events.
157#[derive(Debug, Clone, PartialEq, Eq)]
158#[non_exhaustive]
159pub enum MmiEvent {
160    /// A `menu()` to display — the user picks one choice. Answer via
161    /// [`Driver::mmi_menu_answer`](crate::Driver::mmi_menu_answer).
162    Menu(MmiMenu),
163    /// A `list()` to display — informational (e.g. an entitlement listing); the
164    /// host typically dismisses it with
165    /// [`Driver::mmi_menu_answer`](crate::Driver::mmi_menu_answer)`(0)`.
166    List(MmiMenu),
167    /// An `enquiry` (text prompt) expecting an answer. Reply via
168    /// [`Driver::mmi_enquiry_answer`](crate::Driver::mmi_enquiry_answer) or
169    /// [`Driver::mmi_cancel`](crate::Driver::mmi_cancel).
170    Enquiry {
171        /// Prompt text.
172        prompt: String,
173        /// Whether the answer should be hidden (e.g. PIN).
174        blind: bool,
175        /// Expected answer length.
176        answer_len: u8,
177    },
178    /// The module closed the MMI dialog.
179    Close,
180}
dvb_ci_runtime/event.rs

dvb_ci_runtime/
event.rs
