openthread/ot/
message.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
5//! Module for all things related to OpenThread messages.
6
7use crate::prelude_internal::*;
8use num_derive::FromPrimitive;
9
10/// Message Priority.
11/// Functional equivalent of [`otsys::otMessagePriority`](crate::otsys::otMessagePriority).
12#[derive(Debug, Copy, Clone, Eq, Ord, PartialOrd, PartialEq, FromPrimitive)]
13pub enum Priority {
14    /// Low message priority.
15    /// Equivalent to [`crate::otsys::OT_MESSAGE_PRIORITY_LOW`]
16    Low = OT_MESSAGE_PRIORITY_LOW as isize,
17
18    /// Normal message priority.
19    /// Equivalent to [`crate::otsys::OT_MESSAGE_PRIORITY_NORMAL`]
20    ///
21    /// This is the default priority.
22    Normal = OT_MESSAGE_PRIORITY_NORMAL as isize,
23
24    /// High message priority.
25    /// Equivalent to [`crate::otsys::OT_MESSAGE_PRIORITY_HIGH`]
26    High = OT_MESSAGE_PRIORITY_HIGH as isize,
27}
28
29impl Default for Priority {
30    /// The default priority is `Priority::Normal`.
31    fn default() -> Self {
32        Priority::Normal
33    }
34}
35
36impl Priority {
37    /// Returns value as a [`otsys::otMessagePriority`](crate::otsys::otMessagePriority).
38    pub fn as_ot_message_priority(self) -> otMessagePriority {
39        self as otMessagePriority
40    }
41}
42
43impl From<otMessagePriority> for Priority {
44    fn from(x: otMessagePriority) -> Self {
45        use num::FromPrimitive;
46        Self::from_u32(x).unwrap_or_else(|| panic!("Unknown otMessagePriority value: {x}"))
47    }
48}
49
50impl From<Priority> for otMessagePriority {
51    fn from(x: Priority) -> Self {
52        x.as_ot_message_priority()
53    }
54}
55
56impl From<u8> for Priority {
57    fn from(x: u8) -> Self {
58        use num::FromPrimitive;
59        Self::from_u8(x).unwrap_or_else(|| panic!("Unknown otMessagePriority value: {x}"))
60    }
61}
62
63impl From<Priority> for u8 {
64    #[allow(clippy::unnecessary_fallible_conversions)]
65    fn from(x: Priority) -> Self {
66        x.try_into().unwrap()
67    }
68}
69
70/// Message Info.
71/// Functional equivalent of `otsys::otMessageInfo`.
72#[derive(Clone)]
73#[repr(transparent)]
74pub struct Info(pub otMessageInfo);
75
76impl_ot_castable!(Info, otMessageInfo);
77
78impl AsRef<Info> for Info {
79    fn as_ref(&self) -> &Info {
80        self
81    }
82}
83
84impl Info {
85    /// Creates a new message info instance.
86    pub fn new(local: SockAddr, remote: SockAddr) -> Info {
87        Info(otMessageInfo {
88            mSockAddr: local.addr().into_ot(),
89            mPeerAddr: remote.addr().into_ot(),
90            mSockPort: local.port(),
91            mPeerPort: remote.port(),
92            ..otMessageInfo::default()
93        })
94    }
95
96    /// The ECN status of the packet, represented as in the IPv6 header.
97    pub fn ecn(&self) -> u8 {
98        self.0.mEcn()
99    }
100
101    /// Sets the the ECN status of the packet.
102    pub fn set_ecn(&mut self, ecn: u8) {
103        self.0.set_mEcn(ecn)
104    }
105
106    /// Gets the IPv6 Hop Limit value.
107    pub fn hop_limit(&self) -> u8 {
108        self.0.mHopLimit
109    }
110
111    /// Sets the IPv6 Hop Limit value.
112    pub fn set_hop_limit(&mut self, hop_limit: u8) {
113        self.0.mHopLimit = hop_limit
114    }
115
116    /// TRUE if packets sent/received via host interface, FALSE otherwise.
117    pub fn is_host_interface(&self) -> bool {
118        self.0.mIsHostInterface()
119    }
120
121    /// Set to TRUE if packets sent/received via host interface, FALSE otherwise.
122    pub fn set_host_interface(&mut self, host_interface: bool) {
123        self.0.set_mIsHostInterface(host_interface)
124    }
125
126    /// TRUE if allowing looping back multicast, FALSE otherwise.
127    pub fn multicast_loop(&self) -> bool {
128        self.0.mMulticastLoop()
129    }
130
131    /// Set to TRUE to allow looping back multicast, FALSE otherwise.
132    pub fn set_multicast_loop(&mut self, multicast_loop: bool) {
133        self.0.set_mMulticastLoop(multicast_loop)
134    }
135
136    /// TRUE if allowing IPv6 Hop Limit 0 in mHopLimit, FALSE otherwise.
137    pub fn allow_zero_hop_limit(&self) -> bool {
138        self.0.mAllowZeroHopLimit()
139    }
140
141    /// Set to TRUE to allow IPv6 Hop Limit 0 in mHopLimit, FALSE otherwise.
142    pub fn set_allow_zero_hop_limit(&mut self, allow_zero_hop_limit: bool) {
143        self.0.set_mAllowZeroHopLimit(allow_zero_hop_limit)
144    }
145
146    /// Local address and port.
147    pub fn sock_name(&self) -> SockAddr {
148        SockAddr::new(Ip6Address::from_ot(self.0.mSockAddr), self.0.mSockPort)
149    }
150
151    /// Remote address and port.
152    pub fn peer_name(&self) -> SockAddr {
153        SockAddr::new(Ip6Address::from_ot(self.0.mPeerAddr), self.0.mPeerPort)
154    }
155}
156
157impl std::fmt::Debug for Info {
158    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
159        f.debug_struct("otMessageInfo")
160            .field("sock_name", &self.sock_name())
161            .field("peer_name", &self.peer_name())
162            .field("ecn", &self.ecn())
163            .field("hop_limit", &self.hop_limit())
164            .field("allow_zero_hop_limit", &self.allow_zero_hop_limit())
165            .field("multicast_loop", &self.multicast_loop())
166            .field("is_host_interface", &self.is_host_interface())
167            .finish()
168    }
169}
170
171/// Message Settings.
172/// Functional equivalent of `otsys::otMessageSettings`.
173#[derive(Debug, Clone)]
174#[repr(transparent)]
175pub struct Settings(pub otMessageSettings);
176
177impl_ot_castable!(Settings, otMessageSettings);
178
179impl AsRef<Settings> for Settings {
180    fn as_ref(&self) -> &Settings {
181        self
182    }
183}
184
185impl Default for Settings {
186    fn default() -> Self {
187        Settings(otMessageSettings {
188            mLinkSecurityEnabled: true,
189            mPriority: OT_MESSAGE_PRIORITY_NORMAL.try_into().unwrap(),
190        })
191    }
192}
193
194impl Settings {
195    /// Returns settings with the priority set as indicated.
196    pub fn set_priority(mut self, priority: Priority) -> Self {
197        self.0.mPriority = priority.into();
198        self
199    }
200
201    /// Returns settings with the link_security flag set as indicated.
202    pub fn set_link_security(mut self, enabled: bool) -> Self {
203        self.0.mLinkSecurityEnabled = enabled;
204        self
205    }
206}
207
208/// OpenThread Message. Functional equivalent of [`otsys::otMessage`](crate::otsys::otMessage).
209///
210/// This type cannot be instantiated directly: owned instances are
211/// passed around in an [`ot::Box<ot::Message>`], or [`OtMessageBox`](crate::OtMessageBox)
212/// for short.
213///
214/// `otMessage` instances keep a reference to their `otInstance`, so this type does not
215/// implement `Send` nor `Sync`.
216#[repr(transparent)]
217pub struct Message<'a>(otMessage, PhantomData<*mut otMessage>, PhantomData<&'a ()>);
218
219impl std::fmt::Debug for Message<'_> {
220    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
221        f.debug_struct("otMessage")
222            .field("otPtr", &self.as_ot_ptr())
223            .field("len", &self.len())
224            .field("offset", &self.offset())
225            .field("RSSI", &self.rssi())
226            .finish()
227    }
228}
229
230// SAFETY: `Message` transparently wraps around an opaque type and is
231//         never used by value nor passed by value.
232unsafe impl ot::Boxable for Message<'_> {
233    type OtType = otMessage;
234    unsafe fn finalize(&mut self) {
235        otMessageFree(self.as_ot_ptr())
236    }
237}
238
239impl<'a> Message<'a> {
240    /// Functional equivalent of [`otsys::otIp6NewMessage`](crate::otsys::otIp6NewMessage).
241    pub fn ip6_new<T: ot::Boxable<OtType = otInstance>>(
242        instance: &'a T,
243        settings: Option<&Settings>,
244    ) -> Result<ot::Box<Message<'a>>, ot::NoBufs> {
245        unsafe {
246            // This is safe because we own the `otMessage*` resulting from
247            // `otIp6NewMessage`. Safety is also dependent on the correctness
248            //  of the implementation of `otIp6NewMessage`.
249            ot::Box::from_ot_ptr(otIp6NewMessage(
250                instance.as_ot_ptr(),
251                settings.map(|x| x.as_ref().as_ot_ptr()).unwrap_or(null()),
252            ))
253        }
254        .ok_or(ot::NoBufs)
255    }
256
257    /// Functional equivalent of
258    /// [`otsys::otIp6NewMessageFromBuffer`](crate::otsys::otIp6NewMessageFromBuffer).
259    ///
260    /// Note that, due to limitation in how the underlying method can report errors,
261    /// it is impossible to differentiate the "NoBufs" error condition from the "IPv6 header
262    /// malformed" error condition, hence the unusual error type.
263    pub fn ip6_new_from_bytes<T: ot::Boxable<OtType = otInstance>, D: AsRef<[u8]>>(
264        instance: &'a T,
265        data: D,
266        settings: Option<&Settings>,
267    ) -> Result<ot::Box<Message<'a>>, ot::MalformedOrNoBufs> {
268        let data = data.as_ref();
269        unsafe {
270            // SAFETY: This is safe because we own the `otMessage*` resulting from
271            //         `otIp6NewMessageFromBuffer`. Safety is also dependent on the correctness
272            //         of the implementation of `otIp6NewMessageFromBuffer`.
273            ot::Box::from_ot_ptr(otIp6NewMessageFromBuffer(
274                instance.as_ot_ptr(),
275                data.as_ptr(),
276                data.len().try_into().expect("ot::Message::ip6_new_from_bytes: Buffer too large"),
277                settings.map(|x| x.as_ref().as_ot_ptr()).unwrap_or(null()),
278            ))
279        }
280        .ok_or(ot::MalformedOrNoBufs)
281    }
282
283    /// Functional equivalent of [`otsys::otIp4NewMessage`](crate::otsys::otIp4NewMessage).
284    pub fn ip4_new<T: ot::Boxable<OtType = otInstance>>(
285        instance: &'a T,
286        settings: Option<&Settings>,
287    ) -> Result<ot::Box<Message<'a>>, ot::NoBufs> {
288        unsafe {
289            // This is safe because we own the `otMessage*` resulting from
290            // `otIp4NewMessage`. Safety is also dependent on the correctness
291            //  of the implementation of `otIp4NewMessage`.
292            ot::Box::from_ot_ptr(otIp4NewMessage(
293                instance.as_ot_ptr(),
294                settings.map(|x| x.as_ref().as_ot_ptr()).unwrap_or(null()),
295            ))
296        }
297        .ok_or(ot::NoBufs)
298    }
299}
300
301impl<'a> Message<'a> {
302    /// Functional equivalent of [`otsys::otIp6NewMessage`](crate::otsys::otIp6NewMessage).
303    pub fn udp_new<T: ot::Boxable<OtType = otInstance>>(
304        instance: &'a T,
305        settings: Option<&Settings>,
306    ) -> Result<ot::Box<Message<'a>>, ot::NoBufs> {
307        unsafe {
308            // This is safe because we own the `otMessage*` resulting from
309            // `otUdpNewMessage`. Safety is also dependent on the correctness
310            //  of the implementation of `otUdpNewMessage`.
311            ot::Box::from_ot_ptr(otUdpNewMessage(
312                instance.as_ot_ptr(),
313                settings.map(|x| x.as_ref().as_ot_ptr()).unwrap_or(null()),
314            ))
315        }
316        .ok_or(ot::NoBufs)
317    }
318}
319
320impl Message<'_> {
321    /// Functional equivalent of [`otsys::otMessageAppend`](crate::otsys::otMessageAppend).
322    ///
323    /// The length of `data` must be less than 2^16, or else the method will return
324    /// an `Err` with [`ot::Error::InvalidArgs`].
325    pub fn append(&mut self, data: &[u8]) -> Result {
326        Error::from(unsafe {
327            // We verify that the length of the slice will fit into
328            // the length argument type, throwing an error if this is not possible.
329            otMessageAppend(
330                self.as_ot_ptr(),
331                data.as_ptr() as *const ::std::os::raw::c_void,
332                data.len().try_into().or(Err(Error::InvalidArgs))?,
333            )
334        })
335        .into()
336    }
337
338    /// Functional equivalent of
339    /// [`otsys::otMessageIsLinkSecurityEnabled`](crate::otsys::otMessageIsLinkSecurityEnabled).
340    pub fn is_link_security_enabled(&self) -> bool {
341        unsafe { otMessageIsLinkSecurityEnabled(self.as_ot_ptr()) }
342    }
343
344    /// Functional equivalent of [`otsys::otMessageGetLength`](crate::otsys::otMessageGetLength).
345    #[allow(clippy::len_without_is_empty)]
346    pub fn len(&self) -> usize {
347        unsafe { otMessageGetLength(self.as_ot_ptr()).into() }
348    }
349
350    /// Functional equivalent of [`otsys::otMessageSetLength`](crate::otsys::otMessageSetLength).
351    ///
352    /// In addition to the error codes outlined in `otsys::otMessageSetLength`, this method
353    /// will return `Err(Error::InvalidArgs)` if the `len` parameter is larger than 65,535 bytes.
354    pub fn set_len(&mut self, len: usize) -> Result {
355        Error::from(unsafe {
356            // SAFETY: We verify that the given length will fit into the
357            //         the length argument type, throwing an error if this is not possible.
358            otMessageSetLength(self.as_ot_ptr(), len.try_into().or(Err(Error::InvalidArgs))?)
359        })
360        .into()
361    }
362
363    /// Functional equivalent of [`otsys::otMessageGetOffset`](crate::otsys::otMessageGetOffset).
364    pub fn offset(&self) -> usize {
365        unsafe { otMessageGetOffset(self.as_ot_ptr()).into() }
366    }
367
368    /// Functional equivalent of [`otsys::otMessageSetOffset`](crate::otsys::otMessageSetOffset).
369    ///
370    /// Calling this method with an `offset` larger than or equal to exceed 2^16 will cause a panic.
371    pub fn set_offset(&mut self, offset: usize) {
372        unsafe {
373            // SAFETY: We verify that the given offset will fit into the
374            //         the offset argument type and panic if this is not possible.
375            otMessageSetOffset(
376                self.as_ot_ptr(),
377                offset.try_into().expect("ot::Message::set_offset: Offset too large"),
378            )
379        }
380    }
381
382    /// This function sets/forces the message to be forwarded using direct transmission.
383    /// Functional equivalent of
384    /// [`otsys::otMessageSetDirectTransmission`](crate::otsys::otMessageSetDirectTransmission).
385    ///
386    /// Default setting for a new message is `false`.
387    pub fn set_direct_transmission(&mut self, direct_transmission: bool) {
388        unsafe {
389            otMessageSetDirectTransmission(self.as_ot_ptr(), direct_transmission);
390        }
391    }
392
393    /// Functional equivalent of [`otsys::otMessageGetRss`](crate::otsys::otMessageGetRss).
394    pub fn rssi(&self) -> Decibels {
395        unsafe { otMessageGetRss(self.as_ot_ptr()) }
396    }
397
398    /// Renders this message to a new `Vec<u8>` using
399    /// [`otsys::otMessageRead`](crate::otsys::otMessageRead).
400    pub fn to_vec(&self) -> Vec<u8> {
401        let mut buffer = Vec::with_capacity(self.len());
402        #[allow(clippy::uninit_vec)] // TODO(https://fxbug.dev/42177056)
403        unsafe {
404            buffer.set_len(self.len());
405            otMessageRead(
406                self.as_ot_ptr(),
407                0,
408                buffer.as_mut_ptr() as *mut core::ffi::c_void,
409                otMessageGetLength(self.as_ot_ptr()),
410            );
411        }
412        buffer
413    }
414}
415
416/// Message buffer info.
417/// Functional equivalent of [`otsys::otBufferInfo`](crate::otsys::otBufferInfo).
418#[derive(Debug, Default, Copy, Clone)]
419#[repr(transparent)]
420pub struct BufferInfo(pub otBufferInfo);
421
422impl_ot_castable!(BufferInfo, otBufferInfo);
423
424/// Trait for probing message buffer internal metrics.
425pub trait MessageBuffer {
426    /// Functional equivalent of [`otsys::otMessageGetBufferInfo`](crate::otsys::otMessageGetBufferInfo).
427    fn get_buffer_info(&self) -> BufferInfo;
428}
429
430impl<T: MessageBuffer + Boxable> MessageBuffer for ot::Box<T> {
431    fn get_buffer_info(&self) -> BufferInfo {
432        self.as_ref().get_buffer_info()
433    }
434}
435
436impl MessageBuffer for Instance {
437    fn get_buffer_info(&self) -> BufferInfo {
438        let mut ret = BufferInfo::default();
439        unsafe {
440            otMessageGetBufferInfo(self.as_ot_ptr(), ret.as_ot_mut_ptr());
441        }
442        ret
443    }
444}
openthread/ot/message.rs

openthread/ot/
message.rs
