Enum RetainHandling 

#[repr(u8)]
pub enum RetainHandling {
    SendRetained = 0,
    SendRetainedIfNotExists = 1,
    DoNotSendRetained = 2,
}

Retain Handling Option for MQTT Subscriptions

This enum defines how retained messages should be handled when establishing a new subscription. It corresponds to bits 4-5 in the Subscription Options byte as specified in the MQTT v5.0 protocol specification.

Retained messages are messages that the broker stores and delivers to new subscribers immediately upon subscription. The retain handling option controls this behavior, allowing subscribers to specify whether they want to receive existing retained messages.

Protocol Specification

The retain handling option is encoded in bits 4-5 of the Subscription Options:

• Bits 4-5: 00 = Send retained messages at subscribe
• Bits 4-5: 01 = Send retained messages only for new subscriptions
• Bits 4-5: 10 = Do not send retained messages at subscribe
• Bits 4-5: 11 = Reserved (invalid)

Use Cases

• SendRetained: Useful when a subscriber always wants the latest retained value
• SendRetainedIfNotExists: Prevents duplicate retained messages on subscription renewal
• DoNotSendRetained: For subscribers that only want new messages

Examples

use mqtt_protocol_core::mqtt;

// Always receive retained messages when subscribing
let always_retained = mqtt::packet::RetainHandling::SendRetained;

// Only receive retained messages for new subscriptions
let new_only = mqtt::packet::RetainHandling::SendRetainedIfNotExists;

// Never receive retained messages
let no_retained = mqtt::packet::RetainHandling::DoNotSendRetained;

// Convert from byte value
let from_byte = mqtt::packet::RetainHandling::try_from(1u8).unwrap();
assert_eq!(from_byte, mqtt::packet::RetainHandling::SendRetainedIfNotExists);

Variants

SendRetained = 0

Send retained messages at the time of the subscribe

When a subscription is established, the broker will immediately send any retained messages that match the topic filter to the subscriber. This is the default behavior and ensures subscribers always receive the most recent retained value for matching topics.

This option is suitable for:

• Status monitoring applications that need current state
• Subscribers that always want the latest retained value
• Applications where missing the current retained value would be problematic

SendRetainedIfNotExists = 1

Send retained messages at subscribe only if the subscription does not currently exist

The broker will send retained messages only if this is a completely new subscription. If the client already has an active subscription to the same topic filter (even with different QoS), retained messages will not be sent again. This prevents duplicate delivery of retained messages.

This option is suitable for:

• Preventing duplicate retained messages during connection recovery
• Applications that upgrade/downgrade subscription QoS levels
• Scenarios where processing the same retained message twice is undesirable

DoNotSendRetained = 2

Do not send retained messages at the time of the subscribe

The broker will not send any retained messages when the subscription is established, regardless of whether matching retained messages exist. The subscriber will only receive newly published messages after the subscription is active.

This option is suitable for:

• Event-driven applications that only care about new events
• Applications where retained messages represent historical data
• Scenarios where the current retained value is not relevant to the subscriber

Trait Implementations

impl Clone for RetainHandling

fn clone(&self) -> RetainHandling

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RetainHandling

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

Formats the value using the given formatter.

impl Default for RetainHandling

Implementation of Default for RetainHandling

Returns SendRetained as the default retain handling behavior. This matches the MQTT protocol default where retained messages are sent to new subscribers unless explicitly configured otherwise.

Returns

RetainHandling::SendRetained - The default retain handling behavior

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RetainHandling

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for RetainHandling

Implementation of Display for RetainHandling

Formats the retain handling option as a human-readable string representation. This allows retain handling values to be used with println!, format!, and other string formatting operations.

Output Format

• RetainHandling::SendRetained -> “SendRetained”
• RetainHandling::SendRetainedIfNotExists -> “SendRetainedIfNotExists”
• RetainHandling::DoNotSendRetained -> “DoNotSendRetained”

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

Formats the value using the given formatter.

impl Ord for RetainHandling

fn cmp(&self, other: &RetainHandling) -> 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 RetainHandling

fn eq(&self, other: &RetainHandling) -> 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 RetainHandling

fn partial_cmp(&self, other: &RetainHandling) -> 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 RetainHandling

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 RetainHandling

type Error = TryFromPrimitiveError<RetainHandling>

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 RetainHandling

const NAME: &'static str = "RetainHandling"

type Primitive = u8

type Error = TryFromPrimitiveError<RetainHandling>

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

impl Copy for RetainHandling

impl Eq for RetainHandling

impl StructuralPartialEq for RetainHandling