Struct SubEntry

pub struct SubEntry { /* private fields */ }

MQTT Subscription Entry

Represents a single subscription entry consisting of a topic filter and subscription options. This structure is used in SUBSCRIBE packets to specify what topics to subscribe to and how messages should be handled.

Each subscription entry contains:

• A topic filter string that may include wildcards (+ and #)
• Subscription options that control message delivery behavior

Topic Filter Format

Topic filters follow MQTT specification rules:

• Single-level wildcard: + matches any single level
• Multi-level wildcard: # matches any number of levels (must be last)
• Example: home/+/temperature or sensors/#

Wire Format

In the MQTT wire protocol, each subscription entry is encoded as:

1. Topic filter as an MQTT string (2-byte length + UTF-8 bytes)
2. Subscription options as a single byte

Examples

use mqtt_protocol_core::mqtt;

// Basic subscription with default options
let entry = mqtt::packet::SubEntry::new(
    "sensors/temperature",
    mqtt::packet::SubOpts::new()
).unwrap();

// Subscription with custom options
let opts = mqtt::packet::SubOpts::new()
    .set_qos(mqtt::packet::Qos::AtLeastOnce)
    .set_nl(true);
let entry = mqtt::packet::SubEntry::new("home/+/status", opts).unwrap();

Implementations

impl SubEntry

pub fn new( topic_filter: impl AsRef<str>, sub_opts: SubOpts, ) -> Result<Self, MqttError>

Create a new subscription entry

Creates a SubEntry with the specified topic filter and subscription options. The topic filter is validated to ensure it’s a valid UTF-8 string and within the MQTT size limits (maximum 65,535 bytes).

Parameters

• topic_filter - The topic filter string (may contain wildcards + and #)
• sub_opts - The subscription options controlling message delivery

Returns

• Ok(SubEntry) - Successfully created subscription entry
• Err(MqttError::MalformedPacket) - If topic filter exceeds maximum length

Examples

use mqtt_protocol_core::mqtt;

// Basic subscription
let entry = mqtt::packet::SubEntry::new(
    "sensors/temperature",
    mqtt::packet::SubOpts::new()
).unwrap();

// Subscription with wildcards and custom options
let opts = mqtt::packet::SubOpts::new().set_qos(mqtt::packet::Qos::AtLeastOnce);
let entry = mqtt::packet::SubEntry::new("home/+/status", opts).unwrap();

pub fn topic_filter(&self) -> &str

Get the topic filter as a string slice

Returns the topic filter string for this subscription entry. The topic filter may contain MQTT wildcards (+ for single level, # for multiple levels).

Returns

A string slice containing the topic filter

Examples

use mqtt_protocol_core::mqtt;

let entry = mqtt::packet::SubEntry::new("sensors/+/temperature",
                                       mqtt::packet::SubOpts::new()).unwrap();
assert_eq!(entry.topic_filter(), "sensors/+/temperature");

pub fn sub_opts(&self) -> &SubOpts

Get the subscription options

Returns a reference to the subscription options that control how messages matching this topic filter should be delivered.

Returns

A reference to the SubOpts containing the subscription options

Examples

use mqtt_protocol_core::mqtt;

let opts = mqtt::packet::SubOpts::new().set_qos(mqtt::packet::Qos::AtLeastOnce);
let entry = mqtt::packet::SubEntry::new("test/topic", opts).unwrap();
assert_eq!(entry.sub_opts().qos(), mqtt::packet::Qos::AtLeastOnce);

pub fn set_topic_filter( &mut self, topic_filter: String, ) -> Result<(), MqttError>

Set the topic filter for this subscription entry

Updates the topic filter with a new value. The new topic filter is validated to ensure it’s valid UTF-8 and within size limits.

Parameters

• topic_filter - The new topic filter string

Returns

• Ok(()) - Topic filter updated successfully
• Err(MqttError::MalformedPacket) - If topic filter exceeds maximum length

Examples

use mqtt_protocol_core::mqtt;

let mut entry = mqtt::packet::SubEntry::new("old/topic",
                                          mqtt::packet::SubOpts::new()).unwrap();
entry.set_topic_filter("new/topic".to_string()).unwrap();
assert_eq!(entry.topic_filter(), "new/topic");

pub fn set_sub_opts(&mut self, sub_opts: SubOpts)

Set the subscription options for this entry

Updates the subscription options that control how messages matching this topic filter should be delivered.

Parameters

• sub_opts - The new subscription options

Examples

use mqtt_protocol_core::mqtt;

let mut entry = mqtt::packet::SubEntry::new("test/topic",
                                          mqtt::packet::SubOpts::new()).unwrap();
let new_opts = mqtt::packet::SubOpts::new().set_qos(mqtt::packet::Qos::ExactlyOnce);
entry.set_sub_opts(new_opts);
assert_eq!(entry.sub_opts().qos(), mqtt::packet::Qos::ExactlyOnce);

pub fn to_buffers(&self) -> Vec<IoSlice<'_>>

Create IoSlice buffers for efficient network I/O

Returns a vector of IoSlice objects that can be used for vectored I/O operations, allowing zero-copy writes to network sockets. The buffers contain the complete wire format representation of this subscription entry.

Returns

A vector of IoSlice buffers containing:

1. Topic filter with length prefix
2. Subscription options byte

Examples

use mqtt_protocol_core::mqtt;

let entry = mqtt::packet::SubEntry::new("test/topic",
                                       mqtt::packet::SubOpts::new()).unwrap();
let buffers = entry.to_buffers();
// Can be used with vectored write operations
// socket.write_vectored(&buffers)?;

pub fn size(&self) -> usize

Get the total encoded size of this subscription entry

Returns the number of bytes this subscription entry will occupy in the MQTT wire format, including the topic filter with its length prefix and the subscription options byte.

Returns

The total size in bytes for the wire format representation

Examples

use mqtt_protocol_core::mqtt;

let entry = mqtt::packet::SubEntry::new("test",
                                       mqtt::packet::SubOpts::new()).unwrap();
// Size = 2 bytes (length prefix) + 4 bytes ("test") + 1 byte (options) = 7 bytes
assert_eq!(entry.size(), 7);

pub fn parse(data: &[u8]) -> Result<(Self, usize), MqttError>

Parse a subscription entry from byte data

Decodes a subscription entry from the MQTT wire format, which consists of a topic filter (MQTT string with length prefix) followed by a subscription options byte.

Parameters

• data - Byte buffer containing the encoded subscription entry

Returns

• Ok((SubEntry, bytes_consumed)) - Successfully parsed entry and number of bytes consumed
• Err(MqttError::MalformedPacket) - If the data is malformed or incomplete

Wire Format

1. Topic filter as MQTT string (2-byte length + UTF-8 bytes)
2. Subscription options as single byte

Examples

use mqtt_protocol_core::mqtt;

// Buffer containing: length=4, "test", options=0x01
let buffer = &[0x00, 0x04, b't', b'e', b's', b't', 0x01];
let (entry, consumed) = mqtt::packet::SubEntry::parse(buffer).unwrap();

assert_eq!(entry.topic_filter(), "test");
assert_eq!(entry.sub_opts().qos(), mqtt::packet::Qos::AtLeastOnce);
assert_eq!(consumed, 7);

Trait Implementations

impl Clone for SubEntry

fn clone(&self) -> SubEntry

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SubEntry

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

Formats the value using the given formatter.

impl Default for SubEntry

Implementation of Default for SubEntry

Creates a subscription entry with default values:

• Empty topic filter string
• Default subscription options (QoS 0, all flags false)

Note: An empty topic filter is not valid for actual MQTT usage but provides a default state for initialization purposes.

fn default() -> Self

Returns the “default value” for a type.

impl Display for SubEntry

Implementation of Display for SubEntry

Formats the subscription entry 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 SubEntry

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

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

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

Implementation of Serialize for SubEntry

Serializes the subscription entry to a structured format with separate fields for the topic filter and subscription options. This provides a clear JSON representation suitable for debugging and logging.

Serialized Fields

• topic_filter: The topic filter string
• options: The subscription options as a structured object

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for SubEntry

impl StructuralPartialEq for SubEntry