rust_mqtt/client/
event.rs

1//! Contains the main `Event` and content types the client can emit.
2
3use heapless::Vec;
4
5use crate::{
6    bytes::Bytes,
7    types::{
8        IdentifiedQoS, MqttBinary, MqttString, PacketIdentifier, ReasonCode, TopicName, VarByteInt,
9    },
10};
11
12#[allow(unused_imports)]
13use crate::types::QoS;
14
15/// Events emitted by the client when receiving an MQTT packet.
16#[derive(Debug)]
17#[cfg_attr(feature = "defmt", derive(defmt::Format))]
18pub enum Event<'e, const MAX_SUBSCRIPTION_IDENTIFIERS: usize> {
19    /// The server sent a PINGRESP packet.
20    Pingresp,
21
22    /// The server sent a PUBLISH packet.
23    ///
24    /// The client has acted as follows:
25    /// - [`QoS`] 0: No action
26    /// - [`QoS`] 1: A PUBACK packet has been sent to the server.
27    /// - [`QoS`] 2: A PUBREC packet has been sent to the server and the packet identifier is tracked as in flight
28    Publish(Publish<'e, MAX_SUBSCRIPTION_IDENTIFIERS>),
29
30    /// The server sent a SUBACK packet matching a SUBSCRIBE packet.
31    ///
32    /// The subscription process is complete and was successful if the reason code indicates success.
33    /// The SUBSCRIBE packet won't have to be resent.
34    Suback(Suback),
35
36    /// The server sent an UNSUBACK packet matching an UNSUBSCRIBE packet.
37    ///
38    /// The unsubscription process is complete and was successful if the reason code indicates success.
39    /// The UNSUBSCRIBE packet won't have to be resent.
40    Unsuback(Suback),
41
42    /// The server sent a PUBACK or PUBREC with an erroneous reason code,
43    /// therefore rejecting the publication.
44    ///
45    /// The included reason code is always erroneous.
46    ///
47    /// The publication process is aborted.
48    PublishRejected(Pubrej),
49
50    /// The server sent a PUBACK packet matching a [`QoS`] 1 PUBLISH packet
51    /// confirming that the PUBLISH has been received.
52    ///
53    /// The included reason code is always successful.
54    ///
55    /// The [`QoS`] 1 publication process is complete,
56    /// the PUBLISH packet won't have to be resent.
57    PublishAcknowledged(Puback),
58
59    /// The server sent a PUBREC packet matching a [`QoS`] 2 PUBLISH packet
60    /// confirming that the PUBLISH has been received.
61    ///
62    /// The included reason code is always successful.
63    ///
64    /// The client has responded with a PUBREL packet.
65    ///
66    /// The first handshake of the [`QoS`] 2 publication process is complete,
67    /// the PUBLISH packet won't have to be resent.
68    PublishReceived(Puback),
69
70    /// The server sent a PUBREL packet matching a [`QoS`] 2 PUBREC packet
71    /// confirming that the PUBREC has been received.
72    ///
73    /// The included reason code is always successful.
74    ///
75    /// The client has responded with a PUBCOMP packet.
76    ///
77    /// The [`QoS`] 2 publication process is complete,
78    /// the PUBREC packet won't have to be resent.
79    PublishReleased(Puback),
80
81    /// The server sent a PUBCOMP packet matching a [`QoS`] 2 PUBREL packet
82    /// confirming that the PUBREL has been received.
83    ///
84    /// The included reason code is always successful.
85    ///
86    /// The [`QoS`] 2 publication process is complete,
87    /// the PUBREL packet won't have to be resent.
88    PublishComplete(Puback),
89
90    /// The server sent a SUBACK, PUBACK, PUBREC, PUBREL or PUBCOMP
91    /// packet with a packet identifier that is not in flight (anymore).
92    ///
93    /// The client has not responded to the server or has responded appropriately
94    /// to prevent a potential protocol deadlock.
95    Ignored,
96
97    /// The server sent a [`QoS`] 2 PUBLISH packet which would cause a duplicate.
98    ///
99    /// The client has responded with a PUBREC packet.
100    Duplicate,
101}
102
103/// Content of [`Event::Suback`].
104#[derive(Debug)]
105#[cfg_attr(feature = "defmt", derive(defmt::Format))]
106pub struct Suback {
107    /// Packet identifier of the acknowledged SUBSCRIBE packet.
108    pub packet_identifier: PacketIdentifier,
109    /// Reason code returned for the subscription.
110    pub reason_code: ReasonCode,
111}
112
113/// Content of [`Event::Publish`].
114#[derive(Debug)]
115#[cfg_attr(feature = "defmt", derive(defmt::Format))]
116pub struct Publish<'p, const MAX_SUBSCRIPTION_IDENTIFIERS: usize> {
117    /// The DUP flag in the PUBLISH packet. If set to false, it indicates that this is the first occasion
118    /// the server has attempted to send this publication.
119    pub dup: bool,
120
121    /// The quality of service the server determined to use for this publication. It is the minimum of
122    /// the matching subscription with the highest quality of service level and the quality of service of
123    /// the publishing client's publication.
124    ///
125    /// If the quality of service is greater than 0, this includes the non-zero packet identifier of the
126    /// PUBLISH packet.
127    pub identified_qos: IdentifiedQoS,
128
129    /// The retain flag in the PUBLISH packet. If set to true, it indicates that the publication is the
130    /// result of a retained message. If set to false, this publication having been retained depends on
131    /// the retain as published flag of the matching subscription.
132    pub retain: bool,
133
134    /// The exact topic of this publication.
135    pub topic: TopicName<'p>,
136
137    /// If present, indicates whether the payload is UTF-8. This value is set by the publisher and is
138    /// NOT verified by the client library.
139    /// This is equal to the payload format indicator property of the PUBLISH packet.
140    pub payload_format_indicator: Option<bool>,
141
142    /// The message expiry interval in seconds.
143    /// This is calculated by subtracting the elapsed time since the publish from the message expiry
144    /// interval in original publication.
145    pub message_expiry_interval: Option<u32>,
146
147    /// Identifies an incoming publication as a request and specifies the topic which the response should
148    /// be published on.
149    pub response_topic: Option<TopicName<'p>>,
150
151    /// Present in incoming requests and responses. In either case this is arbitrary binary data used for
152    /// associating either the following response with this specific request or in case of a response,
153    /// link back to the original request.
154    pub correlation_data: Option<MqttBinary<'p>>,
155
156    /// The subscription identifiers in the PUBLISH packet. If the vector is full, this list might not
157    /// be exhaustive.
158    pub subscription_identifiers: Vec<VarByteInt, MAX_SUBSCRIPTION_IDENTIFIERS>,
159
160    /// The content type property of the PUBLISH packet
161    pub content_type: Option<MqttString<'p>>,
162
163    /// The application message of this publication.
164    pub message: Bytes<'p>,
165}
166
167/// Content of [`Event::PublishAcknowledged`], [`Event::PublishReceived`],
168/// [`Event::PublishReleased`], and [`Event::PublishComplete`].
169///
170/// The reason code is always successful.
171#[derive(Debug)]
172#[cfg_attr(feature = "defmt", derive(defmt::Format))]
173pub struct Puback {
174    /// Packet identifier of the acknowledged PUBLISH packet.
175    pub packet_identifier: PacketIdentifier,
176    /// Reason code of this state in the publication process
177    pub reason_code: ReasonCode,
178}
179
180/// Content of [`Event::PublishRejected`].
181///
182/// The reason code is always erroneous.
183#[derive(Debug)]
184#[cfg_attr(feature = "defmt", derive(defmt::Format))]
185pub struct Pubrej {
186    /// Packet identifier of the rejected PUBLISH packet.
187    pub packet_identifier: PacketIdentifier,
188    /// Reason code of the rejection.
189    pub reason_code: ReasonCode,
190}
rust_mqtt/client/event.rs

rust_mqtt/client/
event.rs
