Struct SubOpts

pub struct SubOpts { /* private fields */ }

MQTT Subscription Options

Represents the subscription options byte used in SUBSCRIBE packets as defined in MQTT v5.0 specification. This single byte contains multiple bit fields that control various aspects of subscription behavior including QoS level, retain handling, and MQTT v5.0 specific flags.

Bit Layout

The subscription options byte is structured as follows:

Bit:  7  6  5  4  3  2  1  0
     [Reserved] [RH] [RAP][NL][QoS]

Where:

• Bits 0-1: QoS level (0, 1, or 2)
• Bit 2: No Local flag (NL)
• Bit 3: Retain As Published flag (RAP)
• Bits 4-5: Retain Handling option (RH)
• Bits 6-7: Reserved (must be 0)

Examples

use mqtt_protocol_core::mqtt;

// Create default subscription options (QoS 0, all flags false)
let opts = mqtt::packet::SubOpts::new();

// Configure specific options
let opts = mqtt::packet::SubOpts::new()
    .set_qos(mqtt::packet::Qos::AtLeastOnce)
    .set_nl(true)  // No Local flag
    .set_rap(true) // Retain As Published flag
    .set_rh(mqtt::packet::RetainHandling::DoNotSendRetained);

// Parse from byte value
let opts = mqtt::packet::SubOpts::from_u8(0x25).unwrap();

Implementations

impl SubOpts

pub fn new() -> Self

Create new subscription options with default values

Creates a SubOpts instance with all options set to their default values:

• QoS: AtMostOnce (0)
• No Local flag: false
• Retain As Published flag: false
• Retain Handling: SendRetained (0)

Returns

A new SubOpts instance with default settings

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new();
assert_eq!(opts.qos(), mqtt::packet::Qos::AtMostOnce);
assert_eq!(opts.nl(), false);
assert_eq!(opts.rap(), false);

pub fn from_u8(value: u8) -> Result<Self, MqttError>

Create subscription options from a byte value

Parses a subscription options byte and validates that all fields contain valid values according to the MQTT v5.0 specification. This method performs comprehensive validation to ensure protocol compliance.

Parameters

• value - The subscription options byte to parse

Returns

• Ok(SubOpts) - Successfully parsed and validated subscription options
• Err(MqttError::MalformedPacket) - If any field contains invalid values

Validation Rules

1. Reserved bits (6-7) must be 0
2. QoS value (bits 0-1) must be 0, 1, or 2
3. Retain Handling value (bits 4-5) must be 0, 1, or 2

Examples

use mqtt_protocol_core::mqtt;

// Valid subscription options byte
let opts = mqtt::packet::SubOpts::from_u8(0x25).unwrap();

// Invalid: reserved bits set
assert!(mqtt::packet::SubOpts::from_u8(0xC0).is_err());

// Invalid: QoS value 3
assert!(mqtt::packet::SubOpts::from_u8(0x03).is_err());

pub fn qos(&self) -> Qos

Get the QoS level from subscription options

Extracts and returns the Quality of Service level from bits 0-1 of the subscription options byte. The QoS level determines the delivery guarantee for messages matching this subscription.

Returns

The QoS level as a Qos enum value:

• Qos::AtMostOnce for value 0
• Qos::AtLeastOnce for value 1
• Qos::ExactlyOnce for value 2

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new().set_qos(mqtt::packet::Qos::AtLeastOnce);
assert_eq!(opts.qos(), mqtt::packet::Qos::AtLeastOnce);

pub fn set_qos(self, qos: Qos) -> Self

Set the QoS level in subscription options

Updates bits 0-1 of the subscription options byte with the specified QoS level. This method uses a builder pattern, consuming and returning the SubOpts instance to allow method chaining.

Parameters

• qos - The QoS level to set

Returns

The updated SubOpts instance with the new QoS level

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new()
    .set_qos(mqtt::packet::Qos::ExactlyOnce);
assert_eq!(opts.qos(), mqtt::packet::Qos::ExactlyOnce);

pub fn nl(&self) -> bool

Get the No Local flag from subscription options

Extracts the No Local flag from bit 2 of the subscription options byte. When set to true, messages published by this client will not be forwarded back to it, even if it has a matching subscription.

This flag is useful for preventing message loops in scenarios where a client both publishes and subscribes to the same topics.

Returns

true if the No Local flag is set, false otherwise

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new().set_nl(true);
assert_eq!(opts.nl(), true);

pub fn set_nl(self, nl: bool) -> Self

Set the No Local flag in subscription options

Updates bit 2 of the subscription options byte with the specified No Local flag value. This method uses a builder pattern, consuming and returning the SubOpts instance to allow method chaining.

Parameters

• nl - The No Local flag value to set

Returns

The updated SubOpts instance with the new No Local flag

Examples

use mqtt_protocol_core::mqtt;

// Enable No Local to prevent message loops
let opts = mqtt::packet::SubOpts::new().set_nl(true);
assert_eq!(opts.nl(), true);

pub fn rap(&self) -> bool

Get the Retain As Published flag from subscription options

Extracts the Retain As Published flag from bit 3 of the subscription options byte. When set to true, messages forwarded to this subscription will keep their original RETAIN flag value. When false, forwarded messages will have their RETAIN flag set to 0.

This flag affects how the broker handles the RETAIN flag when forwarding messages to this specific subscription.

Returns

true if the Retain As Published flag is set, false otherwise

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new().set_rap(true);
assert_eq!(opts.rap(), true);

pub fn set_rap(self, rap: bool) -> Self

Set the Retain As Published flag in subscription options

Updates bit 3 of the subscription options byte with the specified Retain As Published flag value. This method uses a builder pattern, consuming and returning the SubOpts instance to allow method chaining.

Parameters

• rap - The Retain As Published flag value to set

Returns

The updated SubOpts instance with the new Retain As Published flag

Examples

use mqtt_protocol_core::mqtt;

// Preserve original RETAIN flag in forwarded messages
let opts = mqtt::packet::SubOpts::new().set_rap(true);
assert_eq!(opts.rap(), true);

pub fn rh(&self) -> RetainHandling

Get the Retain Handling option from subscription options

Extracts and returns the Retain Handling option from bits 4-5 of the subscription options byte. This option controls how retained messages are handled when the subscription is established.

Returns

The retain handling option as a RetainHandling enum value:

• RetainHandling::SendRetained for value 0
• RetainHandling::SendRetainedIfNotExists for value 1
• RetainHandling::DoNotSendRetained for value 2

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new()
    .set_rh(mqtt::packet::RetainHandling::DoNotSendRetained);
assert_eq!(opts.rh(), mqtt::packet::RetainHandling::DoNotSendRetained);

pub fn set_rh(self, rh: RetainHandling) -> Self

Set the Retain Handling option in subscription options

Updates bits 4-5 of the subscription options byte with the specified retain handling option. This method uses a builder pattern, consuming and returning the SubOpts instance to allow method chaining.

Parameters

• rh - The retain handling option to set

Returns

The updated SubOpts instance with the new retain handling option

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new()
    .set_rh(mqtt::packet::RetainHandling::SendRetainedIfNotExists);
assert_eq!(opts.rh(), mqtt::packet::RetainHandling::SendRetainedIfNotExists);

pub fn to_buffer(&self) -> &[u8; 1]

Get the raw subscription options byte buffer

Returns a reference to the internal byte buffer containing the encoded subscription options. This can be used for direct serialization to the MQTT wire format.

Returns

A reference to the single-byte buffer containing the encoded options

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new().set_qos(mqtt::packet::Qos::AtLeastOnce);
let buffer = opts.to_buffer();
assert_eq!(buffer[0] & 0x03, 1); // QoS bits should be 01

Trait Implementations

impl Clone for SubOpts

fn clone(&self) -> SubOpts

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SubOpts

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

Formats the value using the given formatter.

impl Default for SubOpts

Implementation of Default for SubOpts

Creates subscription options with all default values. This is equivalent to calling SubOpts::new().

fn default() -> Self

Returns the “default value” for a type.

impl Display for SubOpts

Implementation of Display for SubOpts

Formats the subscription options as a JSON string for human-readable output. This is particularly useful for logging and debugging purposes. If JSON serialization fails, an error message is displayed instead.

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

Formats the value using the given formatter.

impl Ord for SubOpts

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

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

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

Implementation of Serialize for SubOpts

Serializes the subscription options to a structured format with individual fields for each option. This allows the options to be serialized to JSON format with clear field names and values.

Serialized Fields

• qos: Quality of Service level as a string
• nl: No Local flag as a boolean
• rap: Retain As Published flag as a boolean
• rh: Retain Handling option as a string

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for SubOpts

impl Eq for SubOpts

impl StructuralPartialEq for SubOpts