#[repr(u8)]pub enum Qos {
AtMostOnce = 0,
AtLeastOnce = 1,
ExactlyOnce = 2,
}
Expand description
MQTT Quality of Service levels
Defines the delivery guarantee levels for MQTT message publishing and subscription. Each QoS level provides different guarantees about message delivery, with higher levels providing stronger guarantees at the cost of increased overhead.
The QoS level is specified in PUBLISH packets and affects how the message is handled by both the sender and receiver according to the MQTT protocol specification.
§QoS Level Descriptions
- QoS 0 (At Most Once): Fire-and-forget delivery. Messages are delivered at most once, or not at all. No acknowledgment is required.
- QoS 1 (At Least Once): Acknowledged delivery. Messages are delivered at least once. Duplicates may occur but will be handled by the receiver.
- QoS 2 (Exactly Once): Assured delivery. Messages are delivered exactly once using a four-part handshake protocol.
§Protocol Behavior
Each QoS level has specific protocol requirements:
- QoS 0: PUBLISH packet is sent without expecting acknowledgment
- QoS 1: PUBLISH packet must be acknowledged with PUBACK
- QoS 2: PUBLISH packet initiates a handshake: PUBLISH -> PUBREC -> PUBREL -> PUBCOMP
§Examples
use mqtt_protocol_core::mqtt;
// Fire-and-forget message delivery
let qos0 = mqtt::packet::Qos::AtMostOnce;
// Acknowledged delivery with possible duplicates
let qos1 = mqtt::packet::Qos::AtLeastOnce;
// Exactly-once delivery with handshake
let qos2 = mqtt::packet::Qos::ExactlyOnce;
// Convert from byte value
let qos_from_byte = mqtt::packet::Qos::try_from(1u8).unwrap();
assert_eq!(qos_from_byte, mqtt::packet::Qos::AtLeastOnce);
Variants§
AtMostOnce = 0
QoS level 0: At most once delivery
Messages are delivered at most once, or not at all. There is no acknowledgment of delivery and no retry mechanism. This is the fastest delivery method but provides no guarantee that the message will be received.
This level is suitable for:
- High-frequency sensor data where missing occasional readings is acceptable
- Applications where message loss is tolerable
- Scenarios where network bandwidth and battery life are critical
AtLeastOnce = 1
QoS level 1: At least once delivery
Messages are delivered at least once. The receiver acknowledges delivery with a PUBACK packet. If the sender doesn’t receive the acknowledgment within a reasonable time, it retransmits the message. Duplicate messages may occur and should be handled by the application.
This level is suitable for:
- Applications that can handle duplicate messages
- Scenarios where message delivery is important but duplicates are acceptable
- Most general-purpose messaging use cases
ExactlyOnce = 2
QoS level 2: Exactly once delivery
Messages are delivered exactly once using a four-part handshake protocol (PUBLISH -> PUBREC -> PUBREL -> PUBCOMP). This guarantees that messages are neither lost nor duplicated, but requires the most network traffic and processing overhead.
This level is suitable for:
- Financial transactions or billing information
- Critical control messages
- Applications where duplicate processing would cause serious problems
Trait Implementations§
Source§impl<'de> Deserialize<'de> for Qos
impl<'de> Deserialize<'de> for Qos
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
Source§impl Display for Qos
Implementation of Display
for Qos
impl Display for Qos
Implementation of Display
for Qos
Formats the QoS level as a human-readable string representation.
This allows QoS values to be used with println!
, format!
, and
other string formatting operations.
§Output Format
Qos::AtMostOnce
-> “AtMostOnce”Qos::AtLeastOnce
-> “AtLeastOnce”Qos::ExactlyOnce
-> “ExactlyOnce”
Source§impl Ord for Qos
impl Ord for Qos
Source§impl PartialOrd for Qos
impl PartialOrd for Qos
Source§impl TryFromPrimitive for Qos
impl TryFromPrimitive for Qos
impl Copy for Qos
impl Eq for Qos
impl StructuralPartialEq for Qos
Auto Trait Implementations§
impl Freeze for Qos
impl RefUnwindSafe for Qos
impl Send for Qos
impl Sync for Qos
impl Unpin for Qos
impl UnwindSafe for Qos
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
Source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.