API referencestd/mqtt

std/mqtt

Public declarations, types, methods, and source contracts for std/mqtt.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/mqtt"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
bytes core/bytes mqtt.dodo
io std/io mqtt.dodo
text std/text mqtt.dodo

PORT

Constant · Source

MQTT 3.1.1 (OASIS, protocol level 4) packets and topic rules. Portable and allocation-free: no socket, clock or heap. Encoders write caller bytes and return the frame length; decoded views borrow the frame they came from.

pub const PORT: u16 = 1883

MAX_REMAINING

Constant · Source

pub const MAX_REMAINING: usize = 268435455

MAX_STRING

Constant · Source

pub const MAX_STRING: usize = 65535

ErrorKind

Enum · Source

pub enum ErrorKind {
    Malformed, PacketTooLarge, BufferFull, InvalidTopic, InvalidFilter, InvalidInput,
    Protocol, Refused, Rejected, Resolve, Connect, Network, Closed, TimedOut
}

Error

Struct · Source

pub struct Error {
    pub kind: ErrorKind
    // CONNACK return code for Refused, SUBACK return code for Rejected, the
    // numeric operating-system code for network failures, otherwise 0.
    pub code: i32
}

Error.format

Function · Source

Only fixed kind names and numeric metadata; never topics or payloads.

pub fn format<F>(&self, output: &mut F) -> void!io.Error

failure

Function · Source

pub fn failure(kind: ErrorKind, code: i32) -> Error

ACCEPTED

Constant · Source

CONNACK return codes.

pub const ACCEPTED: u8 = 0

UNACCEPTABLE_PROTOCOL

Constant · Source

pub const UNACCEPTABLE_PROTOCOL: u8 = 1

IDENTIFIER_REJECTED

Constant · Source

pub const IDENTIFIER_REJECTED: u8 = 2

SERVER_UNAVAILABLE

Constant · Source

pub const SERVER_UNAVAILABLE: u8 = 3

BAD_CREDENTIALS

Constant · Source

pub const BAD_CREDENTIALS: u8 = 4

NOT_AUTHORIZED

Constant · Source

pub const NOT_AUTHORIZED: u8 = 5

SUBSCRIBE_FAILURE

Constant · Source

SUBACK return code for a refused subscription.

pub const SUBSCRIBE_FAILURE: u8 = 128

QoS

Enum · Source

pub enum QoS {
    AtMostOnce, AtLeastOnce, ExactlyOnce
}

qos_level

Function · Source

pub fn qos_level(qos: &QoS) -> u8

qos_from

Function · Source

pub fn qos_from(level: u8) -> Option<QoS>

PacketKind

Enum · Source

pub enum PacketKind {
    Connect, Connack, Publish, Puback, Pubrec, Pubrel, Pubcomp,
    Subscribe, Suback, Unsubscribe, Unsuback, Pingreq, Pingresp, Disconnect
}

valid_string

Function · Source

MQTT strings are UTF-8 without U+0000, at most 65535 bytes.

pub fn valid_string(data: &[u8]) -> bool

valid_topic

Function · Source

A topic name, as published: non-empty and free of the + and # wildcards.

pub fn valid_topic(topic: &[u8]) -> bool

valid_filter

Function · Source

A topic filter, as subscribed: + fills a whole level, # only the last one.

pub fn valid_filter(filter: &[u8]) -> bool

matches

Function · Source

Whether a valid filter selects a valid topic name. Wildcards in the first level never match topics beginning with $, such as $SYS/broker/uptime.

pub fn matches(filter: &[u8], topic: &[u8]) -> bool

Connect

Struct · Source

Session settings sent in CONNECT. Empty username, password and will_topic mean absent; MQTT 3.1.1 permits a password only together with a username.

pub struct Connect {
    pub client_id: &[u8]
    pub username: &[u8]
    pub password: &[u8]
    pub keep_alive_s: u16
    pub clean_session: bool
    pub will_topic: &[u8]
    pub will_payload: &[u8]
    pub will_qos: QoS
    pub will_retain: bool
}

Connect.new

Function · Source

pub fn new(client_id: &[u8]) -> Connect from(client_id)

encode_connect

Function · Source

pub fn encode_connect(output: &mut[u8], connect: &Connect) -> usize!Error

encode_publish_head

Function · Source

Everything of a PUBLISH except its payload, so large payloads can be sent from their own storage. packet_id must be 0 for QoS 0, otherwise non-zero.

pub fn encode_publish_head(output: &mut[u8], topic: &[u8], payload_len: usize, qos: QoS, retain: bool,
duplicate: bool, packet_id: u16) -> usize!Error

encode_publish

Function · Source

pub fn encode_publish(output: &mut[u8], topic: &[u8], payload: &[u8], qos: QoS, retain: bool,
duplicate: bool, packet_id: u16) -> usize!Error

encode_subscribe

Function · Source

pub fn encode_subscribe(output: &mut[u8], packet_id: u16, filter: &[u8], qos: QoS) -> usize!Error

encode_unsubscribe

Function · Source

pub fn encode_unsubscribe(output: &mut[u8], packet_id: u16, filter: &[u8]) -> usize!Error

encode_ack

Function · Source

PUBACK, PUBREC, PUBREL, PUBCOMP or UNSUBACK for a non-zero packet identifier.

pub fn encode_ack(output: &mut[u8], kind: PacketKind, packet_id: u16) -> usize!Error

encode_connack

Function · Source

pub fn encode_connack(output: &mut[u8], session_present: bool, return_code: u8) -> usize!Error

encode_suback

Function · Source

One return code per requested filter: the granted QoS or SUBSCRIBE_FAILURE.

pub fn encode_suback(output: &mut[u8], packet_id: u16, codes: &[u8]) -> usize!Error

encode_pingreq

Function · Source

pub fn encode_pingreq(output: &mut[u8]) -> usize!Error

encode_pingresp

Function · Source

pub fn encode_pingresp(output: &mut[u8]) -> usize!Error

encode_disconnect

Function · Source

pub fn encode_disconnect(output: &mut[u8]) -> usize!Error

frame_length

Function · Source

Total length of the frame starting at data[0], once its fixed header is complete; none while more header bytes are needed. The frame itself may still be incomplete: compare the result with data.len.

pub fn frame_length(data: &[u8]) -> Option<usize>!Error

Packet

Struct · Source

One decoded control packet. Views borrow the frame. payload is the PUBLISH application message, the SUBACK return codes, or the rest of a CONNECT, SUBSCRIBE or UNSUBSCRIBE body (after the packet identifier).

pub struct Packet {
    pub kind: PacketKind
    pub flags: u8
    // Bytes of the whole frame, including the fixed header.
    pub length: usize
    // 0 when the packet carries no identifier.
    pub packet_id: u16
    pub topic: &[u8]
    pub payload: &[u8]
    pub qos: QoS
    pub retain: bool
    pub duplicate: bool
    pub session_present: bool
    pub return_code: u8
}

decode

Function · Source

Decodes the complete frame at data[0]. Bytes after it are not inspected.

pub fn decode(data: &[u8]) -> Packet!Error from(data)

decode_connect

Function · Source

The CONNECT body (Packet.payload) as a client sent it. A protocol name or level other than MQTT 3.1.1 fails with Protocol and the level as code, so a server can answer UNACCEPTABLE_PROTOCOL.

pub fn decode_connect(body: &[u8]) -> Connect!Error from(body)

Entry

Struct · Source

One filter of a SUBSCRIBE or UNSUBSCRIBE payload (Packet.payload). next is the offset of the following entry; it equals payload.len after the last. Filters are not validated, so a server can refuse them one by one.

pub struct Entry {
    pub filter: &[u8]
    pub qos: u8
    pub next: usize
}

subscribe_entry

Function · Source

pub fn subscribe_entry(payload: &[u8], offset: usize) -> Entry!Error from(payload)

unsubscribe_entry

Function · Source

pub fn unsubscribe_entry(payload: &[u8], offset: usize) -> Entry!Error from(payload)

topic_level

Function · Source

The level at index of a topic, counting from 0, or empty if the topic has fewer levels: topic_level(b“home/kitchen/light”, 1) is b“kitchen”.

pub fn topic_level(topic: &[u8], index: usize) -> &[u8] from(topic)

Message

Struct · Source

An application message, as handlers receive it.

pub struct Message {
    pub topic: &[u8]
    pub payload: &[u8]
    pub qos: QoS
    pub retain: bool
    pub duplicate: bool
}

Message.new

Function · Source

pub fn new(topic: &[u8], payload: &[u8]) -> Message from(topic, payload)

Message.level

Function · Source

See topic_level: message.level(1) of home/kitchen/light is b“kitchen”.

pub fn level(&self, index: usize) -> &[u8] from(self)

Message.matches

Function · Source

pub fn matches(&self, filter: &[u8]) -> bool

Outbox

Struct · Source

Messages a handler publishes. The app or broker sends them after the handler returns, in order. Storage is bounded; a full outbox fails with BufferFull and keeps the messages queued before it.

pub struct Outbox {
    // Private implementation fields omitted.
}

Outbox.new

Function · Source

pub fn new(data: &mut[u8]) -> Outbox from(data)

Outbox.publish

Function · Source

pub fn publish(&mut self, topic: &[u8], payload: &[u8]) -> void!Error

Outbox.publish_with

Function · Source

pub fn publish_with(&mut self, topic: &[u8], payload: &[u8], qos: QoS, retain: bool) -> void!Error

Outbox.len

Function · Source

pub fn len(&self) -> usize

Outbox.next

Function · Source

Start with cursor := 0usize and call until it returns none.

pub fn next(&self, cursor: &mut usize) -> Option<Message> from(self)

Outbox.clear

Function · Source

pub fn clear(&mut self)

Reply

Struct · Source

Ready-made handlers. reply publishes a fixed payload to a fixed topic for every matching message; forward republishes each payload to another topic.

pub struct Reply {
    // Private implementation fields omitted.
}

Reply.handle

Function · Source

pub fn handle(&mut self, message: &Message, outbox: &mut Outbox) -> void!Error

reply

Function · Source

pub fn reply(topic: &[u8], payload: &[u8]) -> Reply from(topic, payload)

Forward

Struct · Source

pub struct Forward {
    // Private implementation fields omitted.
}

Forward.handle

Function · Source

pub fn handle(&mut self, message: &Message, outbox: &mut Outbox) -> void!Error

forward

Function · Source

pub fn forward(topic: &[u8]) -> Forward from(topic)

Dispatch

Struct · Source

What dispatching one message did: matching handlers run and failures.

pub struct Dispatch {
    pub handled: usize
    pub failed: usize
    pub failure: Option<Error>
}

Dispatch.new

Function · Source

pub fn new() -> Dispatch

NoRoutes

Struct · Source

Topic routes used by std/mqtt/app and std/mqtt/broker. Each registration wraps the previous chain, so handlers keep their own types and state with no allocation. Every handler whose filter matches runs, in registration order.

pub struct NoRoutes {

}

NoRoutes.dispatch

Function · Source

pub fn dispatch(&mut self, message: &Message, outbox: &mut Outbox, outcome: &mut Dispatch)

NoRoutes.len

Function · Source

pub fn len(&self) -> usize

NoRoutes.filter

Function · Source

pub fn filter(&self, index: usize) -> &[u8] from(self)

Routes

Struct · Source

pub struct Routes<A, H> {
    // Private implementation fields omitted.
}

Routes.dispatch

Function · Source

pub fn dispatch(&mut self, message: &Message, outbox: &mut Outbox, outcome: &mut Dispatch)

Routes.len

Function · Source

pub fn len(&self) -> usize

Routes.filter

Function · Source

pub fn filter(&self, index: usize) -> &[u8] from(self)

route

Function · Source

pub fn route<A, H>(previous: A, filter: &[u8], handler: H) -> Routes<A, H> from(previous, filter, handler)

RegistrationError

Struct · Source

The first invalid registration, kept by fluent builders until build/run: an invalid filter, or (kind InvalidInput) a zero task interval.

pub struct RegistrationError {
    pub kind: ErrorKind
    pub filter: &[u8]
    pub index: usize
}

RegistrationError.format

Function · Source

pub fn format<F>(&self, output: &mut F) -> void!io.Error

check_filter

Function · Source

pub fn check_filter(filter: &[u8], index: usize) -> Option<RegistrationError> from(filter)

RunError

Struct · Source

One error boundary for fluent setup and serving, as returned by app and broker serve calls.

pub struct RunError {
    pub registration: Option<RegistrationError>
    pub serving: Option<Error>
}

RunError.format

Function · Source

pub fn format<F>(&self, output: &mut F) -> void!io.Error

DELIVERY_BYTES

Constant · Source

In-process test result: what the matching handlers did with one message. Published messages are copied, so a Delivery outlives the app or broker.

pub const DELIVERY_BYTES: usize = 1024

Delivery

Struct · Source

pub struct Delivery {
    pub handled: usize
    pub failure: Option<Error>
    // Private implementation fields omitted.
}

Delivery.len

Function · Source

pub fn len(&self) -> usize

Delivery.published

Function · Source

pub fn published(&self, index: usize) -> Option<Message> from(self)

Delivery.contains

Function · Source

pub fn contains(&self, topic: &[u8], payload: &[u8]) -> bool

Delivery.expect_handled

Function · Source

pub fn expect_handled(self, expected: usize) -> Delivery

Delivery.expect_ok

Function · Source

pub fn expect_ok(self) -> Delivery

Delivery.expect_failure

Function · Source

pub fn expect_failure(self) -> Delivery

Delivery.expect_published

Function · Source

pub fn expect_published(self, expected: usize) -> Delivery

Delivery.expect_publish

Function · Source

pub fn expect_publish(self, topic: &[u8], payload: &[u8]) -> Delivery

capture

Function · Source

Runs runner.dispatch(message, outbox, outcome) and records the result. App and broker test helpers use this; most programs call those instead.

pub fn capture<R>(runner: &mut R, message: &Message) -> Delivery

Search every guide, reference page, and API declaration.