Enum Qos

#[repr(u8)]
pub enum Qos {
    AtMostOnce = 0,
    AtLeastOnce = 1,
    ExactlyOnce = 2,
}

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

impl Clone for Qos

fn clone(&self) -> Qos

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Qos

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Qos

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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”

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Ord for Qos

fn cmp(&self, other: &Qos) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Qos

fn eq(&self, other: &Qos) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Qos

fn partial_cmp(&self, other: &Qos) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Qos

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<u8> for Qos

type Error = TryFromPrimitiveError<Qos>

The type returned in the event of a conversion error.

fn try_from(number: u8) -> Result<Self, TryFromPrimitiveError<Self>>

Performs the conversion.

impl TryFromPrimitive for Qos

const NAME: &'static str = "Qos"

type Primitive = u8

type Error = TryFromPrimitiveError<Qos>

fn try_from_primitive( number: Self::Primitive, ) -> Result<Self, TryFromPrimitiveError<Self>>

impl Copy for Qos

impl Eq for Qos

impl StructuralPartialEq for Qos