Skip to main content

spodes_rs/spodus/
profile_filter.rs

1//! Profile-data-filter interface class (СТО 34.01-5.1-013-2023, §7.3, class 8201).
2//!
3//! A СПОДУС-specific class that extends `Profile generic` (IC 7) with filtered
4//! reads: it selects rows of a working profile by range or value-match
5//! conditions and projects them to the requested columns, so the head-end can
6//! read exactly the rows and columns it needs in one request. Class 8201, v0.
7//!
8//! The filter data is
9//! `{ object_obis, selected_values: array capture_object_definition,
10//!    filter_list: array filter_object_definition }`, where each filter is
11//! `{ filtering_object, from_value, to_value, entry_values }`. A row passes when
12//! it satisfies every filter (range `from..to` inclusive, or membership in
13//! `entry_values`).
14
15use std::any::Any;
16use std::cmp::Ordering;
17
18use crate::interface::InterfaceClass;
19use crate::obis::ObisCode;
20use crate::types::{BerError, CosemDataType};
21
22/// Profile-data-filter object (class 8201, `0.0.94.7.201.255`) over a working
23/// profile's rows.
24#[derive(Clone, Debug)]
25pub struct ProfileDataFilter {
26    logical_name: ObisCode,
27    /// Column OBIS codes of the working profile, in order.
28    columns: Vec<ObisCode>,
29    /// The working profile rows (structures).
30    rows: Vec<CosemDataType>,
31}
32
33impl ProfileDataFilter {
34    /// Creates a filter at `logical_name` over a profile with the given column
35    /// OBIS codes.
36    pub fn new(logical_name: ObisCode, columns: Vec<ObisCode>) -> Self {
37        ProfileDataFilter { logical_name, columns, rows: Vec::new() }
38    }
39
40    /// Replaces the working profile rows.
41    pub fn set_rows(&mut self, rows: Vec<CosemDataType>) {
42        self.rows = rows;
43    }
44
45    /// The working rows.
46    pub fn rows(&self) -> &[CosemDataType] {
47        &self.rows
48    }
49
50    /// Resolves a `capture_object_definition` (field 1 = logical_name) to a
51    /// column index.
52    fn column_index(&self, capture_object: &CosemDataType) -> Option<usize> {
53        let name = match capture_object {
54            CosemDataType::Structure(fields) => fields.get(1),
55            _ => None,
56        }?;
57        let CosemDataType::OctetString(bytes) = name else { return None };
58        self.columns.iter().position(|c| &c.to_bytes() == bytes)
59    }
60
61    /// Whether a row passes all filters.
62    fn passes(&self, row: &[CosemDataType], filters: &[CosemDataType]) -> bool {
63        filters.iter().all(|filter| self.passes_one(row, filter))
64    }
65
66    fn passes_one(&self, row: &[CosemDataType], filter: &CosemDataType) -> bool {
67        let CosemDataType::Structure(f) = filter else { return true };
68        let Some(index) = f.first().and_then(|o| self.column_index(o)) else { return true };
69        let Some(value) = row.get(index) else { return false };
70        let from = f.get(1);
71        let to = f.get(2);
72        let entries = f.get(3);
73
74        // Value-match filter.
75        if let Some(CosemDataType::Array(list)) = entries {
76            if !list.is_empty() {
77                return list.contains(value);
78            }
79        }
80        // Range filter (inclusive; a Null bound is open).
81        let lower_ok = matches!(from, None | Some(CosemDataType::Null))
82            || matches!(compare(from.unwrap(), value), Some(Ordering::Less | Ordering::Equal));
83        let upper_ok = matches!(to, None | Some(CosemDataType::Null))
84            || matches!(compare(value, to.unwrap()), Some(Ordering::Less | Ordering::Equal));
85        lower_ok && upper_ok
86    }
87
88    /// Projects a row to the columns named by `selected_values` (all columns if
89    /// the selection is empty).
90    fn project(&self, row: &[CosemDataType], selected: &[CosemDataType]) -> CosemDataType {
91        if selected.is_empty() {
92            return CosemDataType::Structure(row.to_vec());
93        }
94        let fields = selected.iter().filter_map(|s| self.column_index(s).and_then(|i| row.get(i)).cloned()).collect();
95        CosemDataType::Structure(fields)
96    }
97
98    /// Applies a filter request, returning the projected matching rows.
99    fn filtered(&self, selected: &[CosemDataType], filters: &[CosemDataType]) -> Vec<CosemDataType> {
100        self.rows
101            .iter()
102            .filter_map(|row| match row {
103                CosemDataType::Structure(fields) if self.passes(fields, filters) => {
104                    Some(self.project(fields, selected))
105                }
106                _ => None,
107            })
108            .collect()
109    }
110
111    /// Parses `{object_obis, selected_values, filter_list}` into its two arrays.
112    fn parse(params: Option<CosemDataType>) -> (Vec<CosemDataType>, Vec<CosemDataType>) {
113        let mut selected = Vec::new();
114        let mut filters = Vec::new();
115        if let Some(CosemDataType::Structure(fields)) = params {
116            if let Some(CosemDataType::Array(s)) = fields.get(1) {
117                selected.clone_from(s);
118            }
119            if let Some(CosemDataType::Array(f)) = fields.get(2) {
120                filters.clone_from(f);
121            }
122        }
123        (selected, filters)
124    }
125}
126
127/// Compares two COSEM values, if comparable (numeric or byte-lexicographic).
128fn compare(a: &CosemDataType, b: &CosemDataType) -> Option<Ordering> {
129    if let (Some(x), Some(y)) = (as_int(a), as_int(b)) {
130        return Some(x.cmp(&y));
131    }
132    match (a, b) {
133        (CosemDataType::OctetString(x), CosemDataType::OctetString(y))
134        | (CosemDataType::DateTime(x), CosemDataType::DateTime(y))
135        | (CosemDataType::DateTime(x), CosemDataType::OctetString(y))
136        | (CosemDataType::OctetString(x), CosemDataType::DateTime(y)) => Some(x.cmp(y)),
137        _ => None,
138    }
139}
140
141/// The integer value of a numeric COSEM type, if it is one.
142fn as_int(v: &CosemDataType) -> Option<i128> {
143    Some(match v {
144        CosemDataType::Integer(i) => i128::from(*i),
145        CosemDataType::Long(i) => i128::from(*i),
146        CosemDataType::DoubleLong(i) => i128::from(*i),
147        CosemDataType::Unsigned(u) | CosemDataType::Enum(u) => i128::from(*u),
148        CosemDataType::LongUnsigned(u) => i128::from(*u),
149        CosemDataType::DoubleLongUnsigned(u) => i128::from(*u),
150        _ => return None,
151    })
152}
153
154impl InterfaceClass for ProfileDataFilter {
155    fn class_id(&self) -> u16 {
156        8201
157    }
158
159    fn version(&self) -> u8 {
160        0
161    }
162
163    fn logical_name(&self) -> &ObisCode {
164        &self.logical_name
165    }
166
167    fn attributes(&self) -> Vec<(u8, CosemDataType)> {
168        vec![(1, CosemDataType::OctetString(self.logical_name.to_bytes()))]
169    }
170
171    fn methods(&self) -> Vec<(u8, String)> {
172        vec![
173            (1, "retrieve_number_of_entries".to_string()),
174            (2, "retrieve_entries".to_string()),
175            (3, "retrieve_entries_by_row".to_string()),
176            (4, "remove_entries".to_string()),
177        ]
178    }
179
180    fn serialize_ber(&self, buf: &mut Vec<u8>) -> Result<(), BerError> {
181        buf.push(0x02);
182        buf.push(0x02);
183        CosemDataType::LongUnsigned(self.class_id()).serialize_ber(buf)?;
184        CosemDataType::OctetString(self.logical_name.to_bytes()).serialize_ber(buf)
185    }
186
187    fn deserialize_ber(&mut self, _data: &[u8]) -> Result<(), BerError> {
188        Ok(())
189    }
190
191    fn invoke_method(&mut self, method_id: u8, params: Option<CosemDataType>) -> Result<CosemDataType, String> {
192        match method_id {
193            1 => {
194                let (_, filters) = Self::parse(params);
195                let count = self
196                    .rows
197                    .iter()
198                    .filter(|r| matches!(r, CosemDataType::Structure(f) if self.passes(f, &filters)))
199                    .count();
200                // Already clamped to u8::MAX above, so the cast can't truncate.
201                #[allow(clippy::cast_possible_truncation)]
202                let count = count.min(u8::MAX as usize) as u8;
203                Ok(CosemDataType::Unsigned(count))
204            }
205            // retrieve_entries and retrieve_entries_by_row share the filter+project logic.
206            2 | 3 => {
207                let (selected, filters) = Self::parse(params);
208                Ok(CosemDataType::Array(self.filtered(&selected, &filters)))
209            }
210            4 => {
211                let (_, filters) = Self::parse(params);
212                let kept = self
213                    .rows
214                    .iter()
215                    .filter(|row| match row {
216                        CosemDataType::Structure(f) => !self.passes(f, &filters),
217                        _ => true,
218                    })
219                    .cloned()
220                    .collect();
221                self.rows = kept;
222                Ok(CosemDataType::Null)
223            }
224            other => Err(format!("method {other} not supported for the Profile data filter class")),
225        }
226    }
227
228    fn as_any(&self) -> &dyn Any {
229        self
230    }
231}
232
233#[cfg(test)]
234mod tests {
235    use super::*;
236
237    fn columns() -> Vec<ObisCode> {
238        vec![ObisCode::new(0, 0, 94, 7, 128, 10), ObisCode::new(1, 0, 1, 8, 0, 255)]
239    }
240
241    fn col_def(code: &ObisCode) -> CosemDataType {
242        CosemDataType::Structure(vec![
243            CosemDataType::LongUnsigned(1),
244            CosemDataType::OctetString(code.to_bytes()),
245            CosemDataType::Integer(2),
246            CosemDataType::LongUnsigned(0),
247        ])
248    }
249
250    fn row(id: &[u8], value: u16) -> CosemDataType {
251        CosemDataType::Structure(vec![CosemDataType::OctetString(id.to_vec()), CosemDataType::LongUnsigned(value)])
252    }
253
254    fn build() -> ProfileDataFilter {
255        let mut f = ProfileDataFilter::new(ObisCode::new(0, 0, 94, 7, 201, 255), columns());
256        f.set_rows(vec![row(b"A", 100), row(b"B", 200), row(b"C", 300)]);
257        f
258    }
259
260    #[test]
261    fn value_match_filter_and_projection() {
262        let mut filter = build();
263        // Select the value column for rows whose meter id is A or C.
264        let selected = vec![col_def(&ObisCode::new(1, 0, 1, 8, 0, 255))];
265        let filters = vec![CosemDataType::Structure(vec![
266            col_def(&ObisCode::new(0, 0, 94, 7, 128, 10)),
267            CosemDataType::Null,
268            CosemDataType::Null,
269            CosemDataType::Array(vec![
270                CosemDataType::OctetString(b"A".to_vec()),
271                CosemDataType::OctetString(b"C".to_vec()),
272            ]),
273        ])];
274        let data = Some(CosemDataType::Structure(vec![
275            CosemDataType::OctetString(vec![]),
276            CosemDataType::Array(selected),
277            CosemDataType::Array(filters),
278        ]));
279        let CosemDataType::Array(rows) = filter.invoke_method(2, data).unwrap() else { panic!("array") };
280        assert_eq!(rows.len(), 2);
281        // Projected to the single value column.
282        assert_eq!(rows[0], CosemDataType::Structure(vec![CosemDataType::LongUnsigned(100)]));
283    }
284
285    #[test]
286    fn range_filter_and_count() {
287        let mut filter = build();
288        // Rows whose value column is in [150, 250] → only B (200).
289        let filters = vec![CosemDataType::Structure(vec![
290            col_def(&ObisCode::new(1, 0, 1, 8, 0, 255)),
291            CosemDataType::LongUnsigned(150),
292            CosemDataType::LongUnsigned(250),
293            CosemDataType::Null,
294        ])];
295        let data = Some(CosemDataType::Structure(vec![
296            CosemDataType::OctetString(vec![]),
297            CosemDataType::Array(vec![]),
298            CosemDataType::Array(filters),
299        ]));
300        assert_eq!(filter.invoke_method(1, data.clone()).unwrap(), CosemDataType::Unsigned(1));
301        let CosemDataType::Array(rows) = filter.invoke_method(2, data).unwrap() else { panic!("array") };
302        assert_eq!(rows.len(), 1);
303        assert_eq!(rows[0], row(b"B", 200));
304    }
305}