toad 0.19.1

Universal implementation of the CoAP networking protocol
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

use naan::prelude::MonadOnce;
use toad_array::Array;
use toad_msg::{MessageOptions, OptNumber, OptValue};

use super::{Method, Req};
use crate::option::common_options;
use crate::platform::{self, PlatformTypes};
use crate::ToCoapValue;

/// Errors encounterable while using ReqBuilder
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Error<P>
  where P: PlatformTypes,
        platform::toad_msg::opt::OptValue<P>: Clone + Eq + core::fmt::Debug,
        platform::toad_msg::opt::SetError<P>: Clone + core::fmt::Debug + Eq
{
  /// Ran out of storage space for options
  SetOptionError(platform::toad_msg::opt::SetError<P>),

  /// You tried to set multiple values for a non-repeatable option
  #[allow(missing_docs)]
  OptionNotRepeatable {
    number: OptNumber,
    old: platform::toad_msg::opt::OptValue<P>,
    new: platform::toad_msg::opt::OptValue<P>,
  },
}

/// Build a request
///
/// note: this is highly experimental and will likely move and change roles. Do not use.
///
/// ```
/// use toad::req::ReqBuilder;
/// use toad::std::{dtls, PlatformTypes as Std};
/// use toad::ContentFormat;
///
/// let payload = r#"""{
///              "name": "Jameson",
///              "say": "Hello"
///            }"""#;
///
/// let request = ReqBuilder::<Std<dtls::Y>>::get("say_stuff").accept(ContentFormat::Json)
///                                                           .content_format(ContentFormat::Json)
///                                                           .payload(payload)
///                                                           .build()
///                                                           .unwrap();
///
/// let rep = send(&request);
/// assert_eq!(rep.payload_string().unwrap(), "Hello, Jameson!");
/// # fn send(req: &toad::req::Req<Std<dtls::Y>>) -> toad::resp::Resp<Std<dtls::Y>> {
/// #   let mut rep = toad::resp::Resp::for_request(req).unwrap();
/// #   rep.set_payload("Hello, Jameson!".bytes());
/// #   rep
/// # }
/// ```
#[derive(Clone, Debug)]
pub struct ReqBuilder<P>
  where P: PlatformTypes,
        platform::toad_msg::opt::OptValue<P>: Clone + Eq + core::fmt::Debug,
        platform::toad_msg::opt::SetError<P>: Clone + core::fmt::Debug + Eq
{
  inner: Result<Req<P>, Error<P>>,
}

impl<P> ReqBuilder<P>
  where P: PlatformTypes,
        platform::toad_msg::opt::OptValue<P>: Clone + Eq + core::fmt::Debug,
        platform::toad_msg::opt::SetError<P>: Clone + core::fmt::Debug + Eq
{
  fn new(method: Method, path: impl AsRef<str>) -> Self {
    Self { inner: Ok(Req::new(method, path)) }
  }

  /// Creates a GET request
  pub fn get(path: impl AsRef<str>) -> Self {
    Self::new(Method::GET, path)
  }

  /// Creates a PUT request
  pub fn put(path: impl AsRef<str>) -> Self {
    Self::new(Method::PUT, path)
  }

  /// Creates a POST request
  pub fn post(path: impl AsRef<str>) -> Self {
    Self::new(Method::POST, path)
  }

  /// Creates a DELETE request
  pub fn delete(path: impl AsRef<str>) -> Self {
    Self::new(Method::DELETE, path)
  }

  /// Set the value of a non-repeatable option.
  ///
  /// If the option has already been set, this will yield `Err(Error::OptionNotRepeatable)`.
  pub fn option<V: ToCoapValue>(mut self, number: OptNumber, value: V) -> Self {
    self.inner =
      self.inner.and_then(|mut req| {
                  let val = OptValue(value.to_coap_value::<platform::toad_msg::opt::Bytes<P>>());
                  match req.as_mut().remove(number) {
                    | Some(existing) => {
                      Err(Error::OptionNotRepeatable { number,
                                                       old: existing.into_iter().next().unwrap(),
                                                       new: val })
                    },
                    | None => req.msg_mut()
                                 .set(number, val)
                                 .map_err(Error::SetOptionError)
                                 .map(|_| req),
                  }
                });

    self
  }

  ///
  pub fn add_option<V: ToCoapValue>(mut self, number: OptNumber, value: V) -> Self {
    self.inner = self.inner.and_then(|mut req| {
                             let val =
                               OptValue(value.to_coap_value::<platform::toad_msg::opt::Bytes<P>>());
                             req.msg_mut()
                                .set(number, val)
                                .map_err(Error::SetOptionError)
                                .map(|_| req)
                           });

    self
  }

  /// Set the payload of the request
  pub fn payload<V: ToCoapValue>(mut self, value: V) -> Self {
    self.inner
        .as_mut()
        .discard_mut(|i: &mut &mut Req<P>| Ok(i.set_payload(value)))
        .ok();
    self
  }

  /// Unwrap the builder into the built request
  pub fn build(self) -> Result<Req<P>, Error<P>> {
    self.inner
  }

  common_options!(P);
}