net-wire 0.1.0

Allocation-free no_std wire views and codecs for network protocols.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! ICMPv4 caller-buffer builder.

use core::fmt;

use super::message::{HEADER_LENGTH, Icmpv4MessageMut};
use super::types::Icmpv4Type;

/// Failure to construct an ICMPv4 message in caller-provided storage.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Icmpv4MessageBuildError {
    /// The type was not supplied.
    MissingType,
    /// The code was not supplied.
    MissingCode,
    /// The requested common header and body length cannot be represented as a `usize`.
    MessageLengthTooLarge,
    /// The buffer cannot hold the requested message.
    BufferTooShort {
        /// Required bytes.
        required: usize,
        /// Available bytes.
        available: usize,
    },
}

impl fmt::Display for Icmpv4MessageBuildError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::MissingType => formatter.write_str("missing ICMPv4 type"),
            Self::MissingCode => formatter.write_str("missing ICMPv4 code"),
            Self::MessageLengthTooLarge => {
                formatter.write_str("ICMPv4 message length exceeds the platform limit")
            }
            Self::BufferTooShort {
                required,
                available,
            } => write!(
                formatter,
                "ICMPv4 buffer is too short: need {required} bytes, have {available}"
            ),
        }
    }
}

/// Builds an ICMPv4 common header in caller-owned storage.
pub struct Icmpv4MessageBuilder<'a> {
    buffer: &'a mut [u8],
    body_length: usize,
    message_type: Option<Icmpv4Type>,
    code: Option<u8>,
}

impl<'a> Icmpv4MessageBuilder<'a> {
    /// Starts a builder for `body_length` bytes, which are left untouched.
    pub fn new(buffer: &'a mut [u8], body_length: usize) -> Self {
        Self {
            buffer,
            body_length,
            message_type: None,
            code: None,
        }
    }
    /// Supplies the ICMPv4 message type.
    pub fn message_type(mut self, value: Icmpv4Type) -> Self {
        self.message_type = Some(value);
        self
    }
    /// Supplies the ICMPv4 message code.
    pub fn code(mut self, value: u8) -> Self {
        self.code = Some(value);
        self
    }
    /// Validates all inputs, writes the common header, and computes its complete checksum.
    ///
    /// Body bytes and capacity beyond the requested message are preserved. On error, the whole
    /// caller-provided buffer is unchanged.
    pub fn build(self) -> Result<Icmpv4MessageMut<'a>, Icmpv4MessageBuildError> {
        let message_type = self
            .message_type
            .ok_or(Icmpv4MessageBuildError::MissingType)?;
        let code = self.code.ok_or(Icmpv4MessageBuildError::MissingCode)?;
        let length = HEADER_LENGTH
            .checked_add(self.body_length)
            .ok_or(Icmpv4MessageBuildError::MessageLengthTooLarge)?;
        if self.buffer.len() < length {
            return Err(Icmpv4MessageBuildError::BufferTooShort {
                required: length,
                available: self.buffer.len(),
            });
        }
        let bytes = &mut self.buffer[..length];
        bytes[0] = message_type.raw();
        bytes[1] = code;
        bytes[2] = 0;
        bytes[3] = 0;
        let mut result = Icmpv4MessageMut::from_validated(bytes);
        result.update_checksum();
        Ok(result)
    }
}