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