bacnet_objects/network_port/
pending.rs

1//! Writes that wait for activation: a BBMD port's
2//! BBMD_Broadcast_Distribution_Table and BBMD_Accept_FD_Registrations
3//! (Clause 12.56.34, 12.56.35, #1578) and, behind a NAT router,
4//! BACnet_IP_NAT_Traversal and BACnet_IP_Global_Address (Clause 12.56.32,
5//! 12.56.33, #940), and a foreign device's
6//! FD_BBMD_Address and FD_Subscription_Lifetime (Clause 12.56.37,
7//! 12.56.38, #1825).
8//!
9//! A write doesn't take effect at once: the value waits, Changes_Pending
10//! reads TRUE, and a read of the property returns the value written, while
11//! the transport keeps working with the old one, so a Read-BDT answers with
12//! the BDT in use and the foreign device keeps registering where it did
13//! (Clause 12.56.13, 12.56.34). A ReinitializeDevice ACTIVATE_CHANGES or
14//! WARMSTART puts the waiting values into effect through the transport
15//! ([`NetworkPortObject::activate_changes`]).
16//!
17//! A written value is checked by the transport when it is written, so one
18//! it would refuse is refused then and changes nothing: a BBMD's value on
19//! its own (a BDT against the row policy, a global address as an IPv4
20//! unicast host), and a BBMD address and time-to-live as the registration
21//! they would make together with the other value waiting. A BBMD's values
22//! are checked together at activation (a NAT BBMD's BDT must list its
23//! global address and be two-hop only), so they can be written in any
24//! order. The rows take
25//! writes only when the port's owner answers ReinitializeDevice
26//! (`set_activation_internal`); otherwise a written value could never take
27//! effect, and the write is WRITE_ACCESS_DENIED.
28
29use bacnet_types::bip_port::{BbmdChanges, ForeignDeviceChanges};
30use bacnet_types::enums::PropertyIdentifier as P;
31use bacnet_types::error::Error;
32use bacnet_types::primitives::PropertyValue;
33
34use super::bip_mode::{bdt_value, host_n_port_value, LiveMode};
35use super::NetworkPortObject;
36use crate::common;
37
38/// The values written to a port and waiting for activation. Only the
39/// current mode's half is ever set: publishing a mode clears both.
40#[derive(Debug, Clone, Default, PartialEq, Eq)]
41pub(super) struct Pending {
42    /// A BBMD's rows.
43    bbmd: BbmdChanges,
44    /// A foreign device's rows.
45    foreign: ForeignDeviceChanges,
46}
47
48impl Pending {
49    fn is_empty(&self) -> bool {
50        self.bbmd.is_empty() && self.foreign.is_empty()
51    }
52}
53
54impl NetworkPortObject {
55    /// The value written to `property` and waiting for activation, if any.
56    pub(super) fn pending_value(&self, property: P) -> Option<Result<PropertyValue, Error>> {
57        let pending = &self.pending;
58        match property {
59            P::BBMD_BROADCAST_DISTRIBUTION_TABLE => pending
60                .bbmd
61                .broadcast_distribution_table
62                .as_deref()
63                .map(bdt_value),
64            P::BBMD_ACCEPT_FD_REGISTRATIONS => pending
65                .bbmd
66                .accept_foreign_device_registrations
67                .map(|accept| Ok(PropertyValue::Boolean(accept))),
68            P::BACNET_IP_NAT_TRAVERSAL => pending
69                .bbmd
70                .nat_traversal
71                .map(|nat| Ok(PropertyValue::Boolean(nat))),
72            P::BACNET_IP_GLOBAL_ADDRESS => {
73                pending.bbmd.global_address.as_ref().map(host_n_port_value)
74            }
75            P::FD_BBMD_ADDRESS => pending.foreign.bbmd.as_ref().map(host_n_port_value),
76            P::FD_SUBSCRIPTION_LIFETIME => pending
77                .foreign
78                .subscription_lifetime
79                .map(|ttl| Ok(PropertyValue::Unsigned(ttl.into()))),
80            _ => None,
81        }
82    }
83
84    /// Take a write to a property the port's mode lets clients change;
85    /// `None` for any other property, or a port in another mode.
86    pub(super) fn write_pending(
87        &mut self,
88        property: P,
89        array_index: Option<u32>,
90        value: &PropertyValue,
91    ) -> Option<Result<(), Error>> {
92        let row = match &self.mode {
93            LiveMode::Bbmd(_) => {
94                matches!(
95                    property,
96                    P::BBMD_BROADCAST_DISTRIBUTION_TABLE | P::BBMD_ACCEPT_FD_REGISTRATIONS
97                ) || (nat_row(property) && self.serves_nat())
98            }
99            LiveMode::Foreign(_) => {
100                matches!(property, P::FD_BBMD_ADDRESS | P::FD_SUBSCRIPTION_LIFETIME)
101            }
102            LiveMode::Normal => false,
103        };
104        if !row {
105            return None;
106        }
107        // A value nothing could activate would wait for ever: without an
108        // owner that answers ReinitializeDevice, or a transport that takes
109        // changes, the rows stay read-only (Clause 16.4 ties pending changes
110        // to ACTIVATE_CHANGES).
111        if !self.activates_changes() {
112            return Some(Err(common::write_access_denied_error()));
113        }
114        if array_index.is_some() {
115            return Some(Err(common::property_is_not_an_array_error()));
116        }
117        Some(match &self.mode {
118            LiveMode::Bbmd(tables) => {
119                // The value written, alone.
120                let mut changes = BbmdChanges::default();
121                let decoded = match (property, value) {
122                    (
123                        P::BBMD_BROADCAST_DISTRIBUTION_TABLE,
124                        PropertyValue::ApplicationData(octets),
125                    ) => bacnet_encoding::constructed::decode_bdt_entry_list(octets)
126                        .map_err(|_| common::invalid_data_encoding_error())
127                        .map(|table| changes.broadcast_distribution_table = Some(table)),
128                    (P::BBMD_ACCEPT_FD_REGISTRATIONS, PropertyValue::Boolean(accept)) => {
129                        changes.accept_foreign_device_registrations = Some(*accept);
130                        Ok(())
131                    }
132                    (P::BACNET_IP_NAT_TRAVERSAL, PropertyValue::Boolean(nat)) => {
133                        changes.nat_traversal = Some(*nat);
134                        Ok(())
135                    }
136                    (P::BACNET_IP_GLOBAL_ADDRESS, PropertyValue::ApplicationData(octets)) => {
137                        decode_host_n_port(octets)
138                            .map(|global| changes.global_address = Some(global))
139                    }
140                    _ => Err(common::invalid_data_type_error()),
141                };
142                // Checked alone; the rules that tie the values together (a
143                // NAT BBMD's BDT lists its global address) wait for
144                // activation, so they can be written in any order.
145                decoded
146                    .and_then(|()| tables.check_value(&changes))
147                    .map(|()| merge(&mut self.pending.bbmd, changes))
148            }
149            LiveMode::Foreign(registration) => {
150                let mut changes = self.pending.foreign.clone();
151                let decoded = match (property, value) {
152                    (P::FD_BBMD_ADDRESS, PropertyValue::ApplicationData(octets)) => {
153                        decode_host_n_port(octets).map(|bbmd| changes.bbmd = Some(bbmd))
154                    }
155                    (P::FD_SUBSCRIPTION_LIFETIME, PropertyValue::Unsigned(ttl)) => {
156                        // Unsigned16 (Clause 12.56.38).
157                        u16::try_from(*ttl)
158                            .map(|ttl| changes.subscription_lifetime = Some(ttl))
159                            .map_err(|_| common::value_out_of_range_error())
160                    }
161                    _ => Err(common::invalid_data_type_error()),
162                };
163                // The pair is checked as it would register, so a value that
164                // only works with the other one waiting is judged with it.
165                decoded
166                    .and_then(|()| registration.check(&changes))
167                    .map(|()| self.pending.foreign = changes)
168            }
169            // No row is writable in NORMAL mode, so this isn't reached.
170            LiveMode::Normal => Err(common::write_access_denied_error()),
171        })
172    }
173
174    /// Whether the pending values would still be taken, changing nothing:
175    /// the check a ReinitializeDevice makes before its handler runs.
176    pub fn check_pending_changes(&self) -> Result<(), Error> {
177        self.check_multicast()?;
178        if self.pending.is_empty() {
179            return Ok(());
180        }
181        match &self.mode {
182            LiveMode::Bbmd(tables) => tables.check(&self.pending.bbmd),
183            LiveMode::Foreign(registration) => registration.check(&self.pending.foreign),
184            LiveMode::Normal => Err(common::write_access_denied_error()),
185        }
186    }
187
188    /// Whether written values wait for activation: Changes_Pending.
189    pub(super) fn changes_pending(&self) -> bool {
190        !self.pending.is_empty() || self.multicast.is_pending()
191    }
192
193    /// Whether written values can be activated, so the pending-activation
194    /// rows take writes: a ReinitializeDevice owner activates them, and the
195    /// transport takes them.
196    pub(super) fn activates_changes(&self) -> bool {
197        self.activation && self.mode.can_change()
198    }
199
200    /// Put the values written to this port into effect, as a
201    /// ReinitializeDevice ACTIVATE_CHANGES or WARMSTART does (Clause
202    /// 12.56.13), and clear Changes_Pending. Whether there were any.
203    ///
204    /// The transport takes all of them or none: when it refuses, the error
205    /// comes back and they stay pending. Every waiting value is checked
206    /// first, so a refused multicast group leaves the mode's values waiting
207    /// too; the mode's values then take effect, and the group last.
208    pub fn activate_changes(&mut self) -> Result<bool, Error> {
209        if !self.changes_pending() {
210            return Ok(false);
211        }
212        self.check_pending_changes()?;
213        // Only a NORMAL port lends a group that can change, and NORMAL has
214        // no mode rows to write, so the two halves never wait together and
215        // the order below can't leave one half applied and the other
216        // refused. A BBMD that serves a group (#941) lends it read-only,
217        // since its own BDT row and its group go together (Annex J.8.3):
218        // making it writable needs one activation for both (#1963).
219        debug_assert!(
220            self.pending.is_empty() || !self.multicast.is_pending(),
221            "mode values and a multicast group pending together"
222        );
223        if !self.pending.is_empty() {
224            self.activate_mode_changes()?;
225        }
226        self.activate_multicast()?;
227        Ok(true)
228    }
229
230    /// Put the mode's waiting values into effect, and clear them.
231    fn activate_mode_changes(&mut self) -> Result<(), Error> {
232        match &self.mode {
233            LiveMode::Bbmd(tables) => tables.activate(&self.pending.bbmd)?,
234            LiveMode::Foreign(registration) => registration.activate(&self.pending.foreign)?,
235            // A port whose mode changed dropped its pending values then.
236            LiveMode::Normal => return Err(common::write_access_denied_error()),
237        }
238        self.pending = Pending::default();
239        Ok(())
240    }
241}
242
243/// Add `written`'s values to `pending`.
244fn merge(pending: &mut BbmdChanges, written: BbmdChanges) {
245    if written.broadcast_distribution_table.is_some() {
246        pending.broadcast_distribution_table = written.broadcast_distribution_table;
247    }
248    if written.accept_foreign_device_registrations.is_some() {
249        pending.accept_foreign_device_registrations = written.accept_foreign_device_registrations;
250    }
251    if written.nat_traversal.is_some() {
252        pending.nat_traversal = written.nat_traversal;
253    }
254    if written.global_address.is_some() {
255        pending.global_address = written.global_address;
256    }
257}
258
259/// A written FD_BBMD_Address or BACnet_IP_Global_Address: exactly one
260/// BACnetHostNPort.
261fn decode_host_n_port(octets: &[u8]) -> Result<bacnet_types::constructed::BACnetHostNPort, Error> {
262    match bacnet_encoding::constructed::decode_host_n_port(octets, 0) {
263        Ok((address, end)) if end == octets.len() => Ok(address),
264        _ => Err(common::invalid_data_encoding_error()),
265    }
266}
267
268/// The rows a write leaves pending for activation, in whichever mode has
269/// them.
270pub(super) fn writable_pending_row(property: P) -> bool {
271    matches!(
272        property,
273        P::BBMD_BROADCAST_DISTRIBUTION_TABLE
274            | P::BBMD_ACCEPT_FD_REGISTRATIONS
275            | P::FD_BBMD_ADDRESS
276            | P::FD_SUBSCRIPTION_LIFETIME
277    ) || nat_row(property)
278}
279
280/// The two NAT rows (Clause 12.56.32, 12.56.33).
281pub(super) fn nat_row(property: P) -> bool {
282    matches!(
283        property,
284        P::BACNET_IP_NAT_TRAVERSAL | P::BACNET_IP_GLOBAL_ADDRESS
285    )
286}
287
288impl NetworkPortObject {
289    /// Whether this port serves the NAT rows: an IPv4 port in BBMD mode
290    /// whose transport can run behind a NAT router.
291    pub(super) fn serves_nat(&self) -> bool {
292        self.ip
293            .as_ref()
294            .is_some_and(super::ip_config::IpConfig::is_ipv4)
295            && self.mode.has_nat_rows()
296    }
297}
bacnet_objects/network_port/pending.rs

bacnet_objects/network_port/
pending.rs
