Skip to main content

spodes_rs/spodus/
table_manager.rs

1//! Table-manager interface class (СТО 34.01-5.1-013-2023, §7.2, class 8200).
2//!
3//! A СПОДУС-specific class that operates on an `array` attribute as a table of
4//! fixed-column rows, one column being a unique key. It provides group
5//! operations — add/update, remove, count and selective retrieve — so the
6//! head-end can manage a working table (e.g. the meter list `0.0.94.7.128.255`)
7//! in a single request. Class 8200, version 0.
8
9use std::any::Any;
10
11use crate::interface::InterfaceClass;
12use crate::obis::ObisCode;
13use crate::types::{BerError, CosemDataType};
14
15/// The unique-key value of a row structure at `key_index`, if present.
16fn key_of(row: &CosemDataType, key_index: usize) -> Option<CosemDataType> {
17    match row {
18        CosemDataType::Structure(fields) => fields.get(key_index).cloned(),
19        _ => None,
20    }
21}
22
23/// Table-manager object (class 8200, `0.0.94.7.200.255`), managing a working
24/// array whose rows are structures with a unique-key column.
25#[derive(Clone, Debug)]
26pub struct TableManager {
27    logical_name: ObisCode,
28    /// Index of the unique-key field within each row structure.
29    key_index: usize,
30    /// The managed working array (rows are structures).
31    rows: Vec<CosemDataType>,
32}
33
34impl TableManager {
35    /// Creates a manager at `logical_name` for a table keyed on field `key_index`.
36    pub fn new(logical_name: ObisCode, key_index: usize) -> Self {
37        TableManager { logical_name, key_index, rows: Vec::new() }
38    }
39
40    /// The managed rows.
41    pub fn rows(&self) -> &[CosemDataType] {
42        &self.rows
43    }
44
45    /// Replaces the managed rows.
46    pub fn set_rows(&mut self, rows: Vec<CosemDataType>) {
47        self.rows = rows;
48    }
49
50    /// Method 1: `add_update_entries` — merge full rows by unique key.
51    fn add_update_entries(&mut self, entries: Vec<CosemDataType>) -> Result<CosemDataType, String> {
52        let key_index = self.key_index;
53        for entry in entries {
54            let key = key_of(&entry, key_index).ok_or("entry is not a keyed structure")?;
55            match self.rows.iter_mut().find(|r| key_of(r, key_index).as_ref() == Some(&key)) {
56                Some(existing) => *existing = entry,
57                None => self.rows.push(entry),
58            }
59        }
60        Ok(CosemDataType::Null)
61    }
62
63    /// Method 2: `remove_entries` — remove rows by key; empty list clears all.
64    fn remove_entries(&mut self, keys: &[CosemDataType]) -> CosemDataType {
65        let key_index = self.key_index;
66        if keys.is_empty() {
67            self.rows.clear();
68        } else {
69            self.rows.retain(|row| !keys.iter().any(|k| key_of(row, key_index).as_ref() == Some(k)));
70        }
71        CosemDataType::Null
72    }
73
74    /// Method 4: `retrieve_entries` — rows matching the keys; empty list = all.
75    fn retrieve_entries(&self, keys: &[CosemDataType]) -> CosemDataType {
76        let key_index = self.key_index;
77        let selected = if keys.is_empty() {
78            self.rows.clone()
79        } else {
80            self.rows
81                .iter()
82                .filter(|row| keys.iter().any(|k| key_of(row, key_index).as_ref() == Some(k)))
83                .cloned()
84                .collect()
85        };
86        CosemDataType::Array(selected)
87    }
88
89    /// Extracts the `entries_list` from a method's `{object_obis, entries_list}`
90    /// data structure.
91    fn entries_list(params: Option<CosemDataType>) -> Result<Vec<CosemDataType>, String> {
92        match params {
93            Some(CosemDataType::Structure(fields)) => match fields.into_iter().nth(1) {
94                Some(CosemDataType::Array(entries)) => Ok(entries),
95                _ => Err("entries_list must be an array".to_string()),
96            },
97            _ => Err("expected a {object_obis, entries_list} structure".to_string()),
98        }
99    }
100}
101
102impl InterfaceClass for TableManager {
103    fn class_id(&self) -> u16 {
104        8200
105    }
106
107    fn version(&self) -> u8 {
108        0
109    }
110
111    fn logical_name(&self) -> &ObisCode {
112        &self.logical_name
113    }
114
115    fn attributes(&self) -> Vec<(u8, CosemDataType)> {
116        vec![(1, CosemDataType::OctetString(self.logical_name.to_bytes()))]
117    }
118
119    fn methods(&self) -> Vec<(u8, String)> {
120        vec![
121            (1, "add_update_entries".to_string()),
122            (2, "remove_entries".to_string()),
123            (3, "retrieve_number_of_entries".to_string()),
124            (4, "retrieve_entries".to_string()),
125        ]
126    }
127
128    fn serialize_ber(&self, buf: &mut Vec<u8>) -> Result<(), BerError> {
129        buf.push(0x02); // structure
130        buf.push(0x02); // two elements
131        CosemDataType::LongUnsigned(self.class_id()).serialize_ber(buf)?;
132        CosemDataType::OctetString(self.logical_name.to_bytes()).serialize_ber(buf)
133    }
134
135    fn deserialize_ber(&mut self, _data: &[u8]) -> Result<(), BerError> {
136        Ok(())
137    }
138
139    fn invoke_method(&mut self, method_id: u8, params: Option<CosemDataType>) -> Result<CosemDataType, String> {
140        match method_id {
141            1 => {
142                let entries = Self::entries_list(params)?;
143                self.add_update_entries(entries)
144            }
145            2 => {
146                let keys = Self::entries_list(params)?;
147                Ok(self.remove_entries(&keys))
148            }
149            3 => {
150                // Already clamped to u8::MAX above, so the cast can't truncate.
151                #[allow(clippy::cast_possible_truncation)]
152                let count = self.rows.len().min(u8::MAX as usize) as u8;
153                Ok(CosemDataType::Unsigned(count))
154            }
155            4 => {
156                let keys = Self::entries_list(params)?;
157                Ok(self.retrieve_entries(&keys))
158            }
159            other => Err(format!("method {other} not supported for the Table manager class")),
160        }
161    }
162
163    fn as_any(&self) -> &dyn Any {
164        self
165    }
166}
167
168#[cfg(test)]
169mod tests {
170    use super::*;
171
172    fn key(id: &[u8]) -> CosemDataType {
173        CosemDataType::OctetString(id.to_vec())
174    }
175
176    fn row(id: &[u8], value: u16) -> CosemDataType {
177        CosemDataType::Structure(vec![key(id), CosemDataType::LongUnsigned(value)])
178    }
179
180    fn wrap(entries: Vec<CosemDataType>) -> CosemDataType {
181        CosemDataType::Structure(vec![CosemDataType::OctetString(vec![]), CosemDataType::Array(entries)])
182    }
183
184    #[test]
185    fn table_manager_group_operations() {
186        let mut mgr = TableManager::new(ObisCode::new(0, 0, 94, 7, 200, 255), 0);
187        assert_eq!(mgr.class_id(), 8200);
188
189        // add two rows.
190        mgr.invoke_method(1, Some(wrap(vec![row(b"A", 1), row(b"B", 2)]))).unwrap();
191        assert_eq!(mgr.invoke_method(3, None).unwrap(), CosemDataType::Unsigned(2));
192
193        // update A by its unique key.
194        mgr.invoke_method(1, Some(wrap(vec![row(b"A", 100)]))).unwrap();
195        assert_eq!(mgr.invoke_method(3, None).unwrap(), CosemDataType::Unsigned(2));
196        let CosemDataType::Array(got) = mgr.invoke_method(4, Some(wrap(vec![key(b"A")]))).unwrap() else {
197            panic!("array");
198        };
199        assert_eq!(got, vec![row(b"A", 100)]);
200
201        // remove B; one row left.
202        mgr.invoke_method(2, Some(wrap(vec![key(b"B")]))).unwrap();
203        assert_eq!(mgr.invoke_method(3, None).unwrap(), CosemDataType::Unsigned(1));
204
205        // remove-all with an empty list.
206        mgr.invoke_method(2, Some(wrap(vec![]))).unwrap();
207        assert_eq!(mgr.invoke_method(3, None).unwrap(), CosemDataType::Unsigned(0));
208    }
209}