rust_mqtt/client/options/
subscribe.rs

1use crate::types::{QoS, VarByteInt};
2
3/// Options for subscription included for every topic.
4#[derive(Debug, Clone, Copy)]
5#[cfg_attr(feature = "defmt", derive(defmt::Format))]
6pub struct Options {
7    /// Serverside retain handling configuration for this subscription.
8    pub retain_handling: RetainHandling,
9
10    /// If set to true, the server sets the retain flag of a PUBLISH packet matching
11    /// this subscription to the retain flag value of the original publication.
12    /// If set to false, the server sets the retain flag of a PUBLISH packet matching
13    /// this subscription to false. This does not apply for retained messages sent
14    /// directly after subscribing - these messages always have the retain flag set to 1.
15    pub retain_as_published: bool,
16
17    /// If set to true, the server does not forward any publications matching
18    /// this subscription to connections with client identifiers the same as
19    /// the client identifier of this connection.
20    /// If set to true on a shared subscription, a protocol error is triggered.
21    pub no_local: bool,
22
23    /// The maximum quality of service that the server can forward publications
24    /// matching this subscription with to the client. A quality of service level
25    /// lower than this can be granted by the server.
26    pub qos: QoS,
27
28    /// The subscription identifier of the subscription. The server will set
29    /// subscription identifier properties in its PUBLISH packets to the values of
30    /// all matching subscriptions with a subscription identifier.
31    pub subscription_identifier: Option<VarByteInt>,
32}
33
34impl Default for Options {
35    fn default() -> Self {
36        Self::new()
37    }
38}
39
40impl Options {
41    /// Creates options with values coherent to the [`Default`] implementations of the fields and
42    /// [`QoS::AtMostOnce`].
43    #[must_use]
44    pub const fn new() -> Self {
45        Self {
46            retain_handling: RetainHandling::AlwaysSend,
47            retain_as_published: false,
48            no_local: false,
49            qos: QoS::AtMostOnce,
50            subscription_identifier: None,
51        }
52    }
53
54    /// Sets the Quality of Service level.
55    #[must_use]
56    pub const fn qos(mut self, qos: QoS) -> Self {
57        self.qos = qos;
58        self
59    }
60    /// Sets the Quality of Service level to 1 (At Least Once).
61    #[must_use]
62    pub const fn at_least_once(self) -> Self {
63        self.qos(QoS::AtLeastOnce)
64    }
65    /// Sets the Quality of Service level to 1 (Exactly Once).
66    #[must_use]
67    pub const fn exactly_once(self) -> Self {
68        self.qos(QoS::ExactlyOnce)
69    }
70    /// Sets the serverside retain handling configuration for this subscription.
71    #[must_use]
72    pub const fn retain_handling(mut self, retain_handling: RetainHandling) -> Self {
73        self.retain_handling = retain_handling;
74        self
75    }
76    /// Sets the retain as published flag to true.
77    #[must_use]
78    pub const fn retain_as_published(mut self) -> Self {
79        self.retain_as_published = true;
80        self
81    }
82    /// Sets the no local flag to true.
83    #[must_use]
84    pub const fn no_local(mut self) -> Self {
85        self.no_local = true;
86        self
87    }
88    /// Sets the subscription identifier property.
89    #[must_use]
90    pub const fn subscription_identifier(mut self, subscription_identifier: VarByteInt) -> Self {
91        self.subscription_identifier = Some(subscription_identifier);
92        self
93    }
94}
95
96/// Serverside retain handling configuration for a subscription.
97#[derive(Debug, Clone, Copy, Default)]
98#[cfg_attr(feature = "defmt", derive(defmt::Format))]
99pub enum RetainHandling {
100    /// Retained messages are always sent at the time of the subscribe.
101    #[default]
102    AlwaysSend,
103    /// Retained messages are only sent if the subscription did not exist before.
104    SendIfNotSubscribedBefore,
105    /// Retained messages are never sent.
106    NeverSend,
107}
rust_mqtt/client/options/subscribe.rs

rust_mqtt/client/options/
subscribe.rs
