openthread/ot/
thread.rs

1// Copyright 2021 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::prelude_internal::*;
6
7/// Iterator type for neighbor info
8#[allow(missing_debug_implementations)]
9pub struct NeighborInfoIterator<'a, T: ?Sized> {
10    ot_instance: &'a T,
11    ot_iter: otNeighborInfoIterator,
12}
13
14impl<T: ?Sized + Thread> Iterator for NeighborInfoIterator<'_, T> {
15    type Item = NeighborInfo;
16    fn next(&mut self) -> Option<Self::Item> {
17        self.ot_instance.iter_next_neighbor_info(&mut self.ot_iter)
18    }
19}
20
21/// Methods from the [OpenThread "Thread General" Module][1].
22///
23/// [1]: https://openthread.io/reference/group/api-thread-general
24pub trait Thread {
25    /// Functional equivalent of
26    /// [`otsys::otThreadBecomeLeader`](crate::otsys::otThreadBecomeLeader).
27    fn become_leader(&self) -> Result;
28
29    /// Functional equivalent of
30    /// [`otsys::otThreadBecomeRouter`](crate::otsys::otThreadBecomeRouter).
31    fn become_router(&self) -> Result;
32
33    /// Functional equivalent of
34    /// [`otsys::otThreadGetChildInfoById`](crate::otsys::otThreadGetChildInfoById).
35    fn get_child_info_by_id(&self, child_id: u16) -> Result<otChildInfo>;
36
37    /// Functional equivalent of
38    /// [`otsys::otThreadGetLeaderData`](crate::otsys::otThreadGetLeaderData).
39    fn get_leader_data(&self) -> Result<LeaderData>;
40
41    /// Functional equivalent of
42    /// [`otsys::otThreadGetLeaderWeight`](crate::otsys::otThreadGetLeaderWeight).
43    fn get_leader_weight(&self) -> u8;
44
45    /// Functional equivalent of
46    /// [`otsys::otThreadGetNetworkKey`](crate::otsys::otThreadGetNetworkKey).
47    #[must_use]
48    fn get_network_key(&self) -> NetworkKey;
49
50    /// Functional equivalent of
51    /// [`otsys::otThreadSetNetworkKey`](crate::otsys::otThreadSetNetworkKey).
52    fn set_network_key(&self, key: &NetworkKey) -> Result;
53
54    /// Similar to [`get_network_name_as_slice`], but returns
55    /// an [`ot::NetworkName`](crate::ot::NetworkName).
56    #[must_use]
57    fn get_network_name(&self) -> NetworkName {
58        NetworkName::try_from_slice(self.get_network_name_as_slice()).unwrap()
59    }
60
61    /// Functional equivalent of
62    /// [`otsys::otThreadGetNetworkName`](crate::otsys::otThreadGetNetworkName).
63    #[must_use]
64    fn get_network_name_as_slice(&self) -> &[u8];
65
66    /// Functional equivalent of
67    /// [`otsys::otThreadSetNetworkName`](crate::otsys::otThreadSetNetworkName).
68    fn set_network_name(&self, name: &NetworkName) -> Result;
69
70    /// Functional equivalent of
71    /// [`otsys::otThreadIsSingleton`](crate::otsys::otThreadIsSingleton).
72    #[must_use]
73    fn is_singleton(&self) -> bool;
74
75    /// Functional equivalent of
76    /// [`otsys::otThreadGetExtendedPanId`](crate::otsys::otThreadGetExtendedPanId).
77    #[must_use]
78    fn get_extended_pan_id(&self) -> &ExtendedPanId;
79
80    /// Functional equivalent of
81    /// [`otsys::otThreadSetExtendedPanId`](crate::otsys::otThreadSetExtendedPanId).
82    fn set_extended_pan_id(&self, xpanid: &ExtendedPanId) -> Result;
83
84    /// Functional equivalent of [`otsys::otThreadSetEnabled`](crate::otsys::otThreadSetEnabled).
85    fn thread_set_enabled(&self, enabled: bool) -> Result;
86
87    /// Functional equivalent of
88    /// [`otsys::otThreadGetDeviceRole`](crate::otsys::otThreadGetDeviceRole).
89    #[must_use]
90    fn get_device_role(&self) -> DeviceRole;
91
92    /// Functional equivalent of
93    /// [`otsys::otThreadGetPartitionId`](crate::otsys::otThreadGetPartitionId).
94    fn get_partition_id(&self) -> u32;
95
96    /// Functional equivalent of [`otsys::otThreadGetRloc16`](crate::otsys::otThreadGetRloc16).
97    fn get_rloc16(&self) -> u16;
98
99    /// Functional equivalent of [`otsys::otThreadGetLinkMode`](crate::otsys::otThreadGetLinkMode).
100    fn get_link_mode(&self) -> ot::LinkModeConfig;
101
102    /// Functional equivalent of [`otsys::otThreadSetLinkMode`](crate::otsys::otThreadSetLinkMode).
103    fn set_link_mode(&self, link_mode_config: ot::LinkModeConfig) -> Result;
104
105    /// Gets the full RLOC address.
106    fn get_rloc(&self) -> std::net::Ipv6Addr;
107
108    /// Functional equivalent of
109    /// [`otsys::otThreadGetMeshLocalEid`](crate::otsys::otThreadGetMeshLocalEid).
110    fn get_mesh_local_eid(&self) -> std::net::Ipv6Addr;
111
112    /// Functional equivalent of
113    /// [`otsys::otThreadGetLinkLocalIp6Address`](crate::otsys::otThreadGetLinkLocalIp6Address).
114    fn get_link_local_addr(&self) -> std::net::Ipv6Addr;
115
116    /// Functional equivalent of
117    /// [`otsys::otThreadGetLinkLocalAllThreadNodesMulticastAddress`](crate::otsys::otThreadGetLinkLocalAllThreadNodesMulticastAddress).
118    fn get_link_local_all_nodes_multicast_addr(&self) -> std::net::Ipv6Addr;
119
120    /// Functional equivalent of
121    /// [`otsys::otThreadGetMeshLocalPrefix`](crate::otsys::otThreadGetMeshLocalPrefix).
122    fn get_mesh_local_prefix(&self) -> &MeshLocalPrefix;
123
124    /// Fucntional equivalent of
125    /// [`otsys::otThreadGetRouterInfo`](crate::otsys::otThreadGetRouterInfo).
126    fn get_router_info(&self, router_id: u16) -> Result<RouterInfo>;
127
128    /// Functional equivalent of
129    /// [`otsys::otThreadGetIp6Counters`](crate::otsys::otThreadGetIp6Counters).
130    fn get_ip6_counters(&self) -> &IpCounters;
131
132    /// Functional equivalent of
133    /// [`otsys::otThreadGetNextNeighborInfo`](crate::otsys::otThreadGetNextNeighborInfo).
134    // TODO: Determine if the underlying implementation of
135    //       this method has undefined behavior when network data
136    //       is being mutated while iterating. If it is undefined,
137    //       we may need to make it unsafe and provide a safe method
138    //       that collects the results.
139    fn iter_next_neighbor_info(&self, ot_iter: &mut otNeighborInfoIterator)
140        -> Option<NeighborInfo>;
141
142    /// Returns an iterator for iterating over external routes.
143    fn iter_neighbor_info(&self) -> NeighborInfoIterator<'_, Self> {
144        NeighborInfoIterator {
145            ot_instance: self,
146            ot_iter: OT_NEIGHBOR_INFO_ITERATOR_INIT.try_into().unwrap(),
147        }
148    }
149}
150
151impl<T: Thread + Boxable> Thread for ot::Box<T> {
152    fn become_leader(&self) -> Result<()> {
153        self.as_ref().become_leader()
154    }
155    fn become_router(&self) -> Result<()> {
156        self.as_ref().become_router()
157    }
158    fn get_child_info_by_id(&self, child_id: u16) -> Result<otChildInfo> {
159        self.as_ref().get_child_info_by_id(child_id)
160    }
161    fn get_leader_data(&self) -> Result<LeaderData> {
162        self.as_ref().get_leader_data()
163    }
164
165    fn get_leader_weight(&self) -> u8 {
166        self.as_ref().get_leader_weight()
167    }
168
169    fn get_network_key(&self) -> NetworkKey {
170        self.as_ref().get_network_key()
171    }
172
173    fn set_network_key(&self, key: &NetworkKey) -> Result {
174        self.as_ref().set_network_key(key)
175    }
176    fn get_network_name_as_slice(&self) -> &[u8] {
177        self.as_ref().get_network_name_as_slice()
178    }
179
180    fn set_network_name(&self, name: &NetworkName) -> Result {
181        self.as_ref().set_network_name(name)
182    }
183
184    fn is_singleton(&self) -> bool {
185        self.as_ref().is_singleton()
186    }
187
188    fn get_extended_pan_id(&self) -> &ExtendedPanId {
189        self.as_ref().get_extended_pan_id()
190    }
191
192    fn set_extended_pan_id(&self, xpanid: &ExtendedPanId) -> Result {
193        self.as_ref().set_extended_pan_id(xpanid)
194    }
195
196    fn thread_set_enabled(&self, enabled: bool) -> Result {
197        self.as_ref().thread_set_enabled(enabled)
198    }
199
200    fn get_device_role(&self) -> DeviceRole {
201        self.as_ref().get_device_role()
202    }
203
204    fn get_partition_id(&self) -> u32 {
205        self.as_ref().get_partition_id()
206    }
207
208    fn get_rloc16(&self) -> u16 {
209        self.as_ref().get_rloc16()
210    }
211
212    fn get_link_mode(&self) -> ot::LinkModeConfig {
213        self.as_ref().get_link_mode()
214    }
215
216    fn set_link_mode(&self, link_mode_config: ot::LinkModeConfig) -> Result {
217        self.as_ref().set_link_mode(link_mode_config)
218    }
219
220    fn get_rloc(&self) -> std::net::Ipv6Addr {
221        self.as_ref().get_rloc()
222    }
223
224    fn get_mesh_local_eid(&self) -> std::net::Ipv6Addr {
225        self.as_ref().get_mesh_local_eid()
226    }
227
228    fn get_link_local_addr(&self) -> std::net::Ipv6Addr {
229        self.as_ref().get_link_local_addr()
230    }
231
232    fn get_link_local_all_nodes_multicast_addr(&self) -> std::net::Ipv6Addr {
233        self.as_ref().get_link_local_all_nodes_multicast_addr()
234    }
235
236    fn get_mesh_local_prefix(&self) -> &MeshLocalPrefix {
237        self.as_ref().get_mesh_local_prefix()
238    }
239
240    fn get_router_info(&self, router_id: u16) -> Result<RouterInfo> {
241        self.as_ref().get_router_info(router_id)
242    }
243
244    fn get_ip6_counters(&self) -> &IpCounters {
245        self.as_ref().get_ip6_counters()
246    }
247
248    fn iter_next_neighbor_info(
249        &self,
250        ot_iter: &mut otNeighborInfoIterator,
251    ) -> Option<NeighborInfo> {
252        self.as_ref().iter_next_neighbor_info(ot_iter)
253    }
254}
255
256impl Thread for Instance {
257    fn become_leader(&self) -> Result<()> {
258        Error::from(unsafe { otThreadBecomeLeader(self.as_ot_ptr()) }).into()
259    }
260
261    fn become_router(&self) -> Result<()> {
262        Error::from(unsafe { otThreadBecomeRouter(self.as_ot_ptr()) }).into()
263    }
264
265    fn get_child_info_by_id(&self, child_id: u16) -> Result<otChildInfo> {
266        let mut ret: otChildInfo = Default::default();
267        Error::from(unsafe { otThreadGetChildInfoById(self.as_ot_ptr(), child_id, &mut ret) })
268            .into_result()?;
269        Ok(ret)
270    }
271
272    fn get_leader_data(&self) -> Result<LeaderData> {
273        let mut ret = LeaderData::default();
274        Error::from(unsafe { otThreadGetLeaderData(self.as_ot_ptr(), ret.as_ot_mut_ptr()) })
275            .into_result()?;
276        Ok(ret)
277    }
278
279    fn get_leader_weight(&self) -> u8 {
280        unsafe { otThreadGetLeaderWeight(self.as_ot_ptr()) }
281    }
282
283    fn get_network_key(&self) -> NetworkKey {
284        let mut ret = NetworkKey::default();
285        unsafe { otThreadGetNetworkKey(self.as_ot_ptr(), ret.as_ot_mut_ptr()) }
286        ret
287    }
288
289    fn set_network_key(&self, key: &NetworkKey) -> Result {
290        Error::from(unsafe { otThreadSetNetworkKey(self.as_ot_ptr(), key.as_ot_ptr()) })
291            .into_result()
292    }
293
294    #[allow(clippy::unnecessary_cast)]
295    fn get_network_name_as_slice(&self) -> &[u8] {
296        unsafe {
297            let slice = std::slice::from_raw_parts(
298                otThreadGetNetworkName(self.as_ot_ptr()) as *const u8,
299                OT_NETWORK_NAME_MAX_SIZE as usize,
300            );
301            let first_zero_index =
302                slice.iter().position(|&x| x == 0).unwrap_or(OT_NETWORK_NAME_MAX_SIZE as usize);
303            &slice[0..first_zero_index]
304        }
305    }
306
307    fn set_network_name(&self, name: &NetworkName) -> Result {
308        Error::from(unsafe { otThreadSetNetworkName(self.as_ot_ptr(), name.as_c_str()) })
309            .into_result()
310    }
311
312    fn is_singleton(&self) -> bool {
313        unsafe { otThreadIsSingleton(self.as_ot_ptr()) }
314    }
315
316    fn get_extended_pan_id(&self) -> &ExtendedPanId {
317        unsafe {
318            let xpanid = otThreadGetExtendedPanId(self.as_ot_ptr());
319            ExtendedPanId::ref_from_ot_ptr(xpanid)
320        }
321        .unwrap()
322    }
323
324    fn set_extended_pan_id(&self, xpanid: &ExtendedPanId) -> Result {
325        Error::from(unsafe { otThreadSetExtendedPanId(self.as_ot_ptr(), xpanid.as_ot_ptr()) })
326            .into_result()
327    }
328
329    fn thread_set_enabled(&self, enabled: bool) -> Result {
330        Error::from(unsafe { otThreadSetEnabled(self.as_ot_ptr(), enabled) }).into_result()
331    }
332
333    fn get_device_role(&self) -> ot::DeviceRole {
334        unsafe { otThreadGetDeviceRole(self.as_ot_ptr()) }.into()
335    }
336
337    fn get_partition_id(&self) -> u32 {
338        unsafe { otThreadGetPartitionId(self.as_ot_ptr()) }
339    }
340
341    fn get_rloc16(&self) -> u16 {
342        unsafe { otThreadGetRloc16(self.as_ot_ptr()) }
343    }
344
345    fn get_link_mode(&self) -> ot::LinkModeConfig {
346        unsafe { otThreadGetLinkMode(self.as_ot_ptr()) }.into()
347    }
348
349    fn set_link_mode(&self, link_mode_config: ot::LinkModeConfig) -> Result {
350        Error::from(unsafe { otThreadSetLinkMode(self.as_ot_ptr(), link_mode_config.into()) })
351            .into_result()
352    }
353
354    fn get_rloc(&self) -> std::net::Ipv6Addr {
355        std::net::Ipv6Addr::from_ot(unsafe { *otThreadGetRloc(self.as_ot_ptr()) })
356    }
357
358    fn get_mesh_local_eid(&self) -> std::net::Ipv6Addr {
359        std::net::Ipv6Addr::from_ot(unsafe { *otThreadGetMeshLocalEid(self.as_ot_ptr()) })
360    }
361
362    fn get_link_local_addr(&self) -> std::net::Ipv6Addr {
363        std::net::Ipv6Addr::from_ot(unsafe { *otThreadGetLinkLocalIp6Address(self.as_ot_ptr()) })
364    }
365
366    fn get_link_local_all_nodes_multicast_addr(&self) -> std::net::Ipv6Addr {
367        std::net::Ipv6Addr::from_ot(unsafe {
368            *otThreadGetLinkLocalAllThreadNodesMulticastAddress(self.as_ot_ptr())
369        })
370    }
371
372    fn get_mesh_local_prefix(&self) -> &MeshLocalPrefix {
373        unsafe { MeshLocalPrefix::ref_from_ot_ptr(otThreadGetMeshLocalPrefix(self.as_ot_ptr())) }
374            .unwrap()
375    }
376
377    fn get_router_info(&self, router_id: u16) -> Result<RouterInfo> {
378        let mut ret = RouterInfo::default();
379        Error::from(unsafe {
380            otThreadGetRouterInfo(self.as_ot_ptr(), router_id, ret.as_ot_mut_ptr())
381        })
382        .into_result()?;
383        Ok(ret)
384    }
385
386    fn get_ip6_counters(&self) -> &IpCounters {
387        unsafe { IpCounters::ref_from_ot_ptr(otThreadGetIp6Counters(self.as_ot_ptr())) }.unwrap()
388    }
389
390    fn iter_next_neighbor_info(
391        &self,
392        ot_iter: &mut otNeighborInfoIterator,
393    ) -> Option<NeighborInfo> {
394        unsafe {
395            let mut ret = NeighborInfo::default();
396            match Error::from(otThreadGetNextNeighborInfo(
397                self.as_ot_ptr(),
398                ot_iter as *mut otNeighborInfoIterator,
399                ret.as_ot_mut_ptr(),
400            )) {
401                Error::NotFound => None,
402                Error::None => Some(ret),
403                err => unreachable!("Unexpected error from otThreadGetNextNeighborInfo: {:?}", err),
404            }
405        }
406    }
407}
openthread/ot/thread.rs

openthread/ot/
thread.rs
