Crate lmc

This crate provides a basic MQTT client implementation with a high-level, asynchronous interface.

Connecting

Connecting to a broker can be achieved using the Client::connect() function, by passing a hostname (or IP address) together with Options:

Publishing messages

The basic ways to publish messages are:

• Client::publish_qos_0() to publish a message with a Quality of Service of “AtMostOnce”. Unfortunately, there is no way to know if and when this message has reached the broker safely.
• Client::publish_qos_1() to publish a message with a Quality of Service of “AtLeastOnce”. By setting await_ack to true, it is possible to wait for the acknowledgment packet and make sure that the broker has received the message.
• Client::publish_qos_2() to publish a message with a Quality of Service of “ExactlyOnce”. By specifying a value other than PublishEvent::None to await_event, it is possible to wait for the acknowledgment packet and make sure that the broker has received the message.

If it is not necessary to wait for the publish packet to be sent, Client::publish_no_wait() can also be used. Finally, Client::try_publish() also be used to attempt to publish a packet with no need for any await.

Subscribing to topics

There are multiple ways to subscribe to topics, each of them have their own limitations:

• Client::subscribe_lossy() will create a subscription based on a bounded queue. If the queue is full when the message is received, it will not be pushed onto that queue and may be lost.
• Client::subscribe_unbounded() will create a subscription based on an unbounded queue, bypassing the limitations of a bounded subscription at a slightly increased performance cost.
• Client::subscribe_fast_callback() will cause the passed function to be called every time a message is received. However, the function must be thread-safe and cannot block.

There is also Client::subscribe_void(), which can be used to only establish an MQTT subscription with the broker. However, none of the messages can be obtained until a normal LMC subscription is created (including retained messages). This might be used if you wish to “pre-subscribe” to a topic, but only occasionally care about the messages.

Note that LMC subscriptions and MQTT subscriptions are not the same thing. LMC subscriptions are created using any of the subscribe methods. MQTT subscriptions are created by the implementation, as a result of the creation of an LMC subscription to a new topic. If an LMC subscription exists for a given topic, that means that an MQTT subscription already exists and there is thus no need to create a new one. This does mean that only the first LMC subscription will receive the retained messages of a particular topic (if there are any). So, if the first subscription is a “void” subscription, retained messages will be lost.

MQTT subscriptions can only be cancelled (unsubscribed) by calling Client::unsubscribe() directly. Since v0.2, LMC will not automatically unsubscribe from topics anymore. This means that even after dropping the MPSC channels of lossy & unlossy subscriptions, and removing fast callback subscriptions, the MQTT subscription with the broker is maintained but the messages will be ignored (effectively becoming a “void” subscription) until Client::unsubscribe() is called.

Re-exports

pub use options::Options;

pub use options::LastWill;

Modules

options

subs

Structs

Client

A clonable, thread-safe handle to an MQTT client that can be used to publish messages, and subscribe/unsubscribe to/from topics.

ClientShutdownHandle

An owned handle that can be used to disconnect and shutdown an MQTT client’s transceiver task and obtain its ShutdownStatus.

Message

A message received from the broker. Its contents are wrapped in an Arc, so this value can be safely cloned with no extra mallocs.

MessageInfo

A simple struct containing the flags used by the broker to transmit the message, as well as the packet ID (if applicable).

PublishFlags

This struct allows the developer to create and parse valid publish flags. See MQTT v3 protocol for more information.

ShutdownStatus

Describes the state in which the client’s transceiver task finished.

Enums

ConnectError

An enumeration of all the errors that could happen while establishing a connection to the broker.

PublishError

An enumeration specifying what went wrong while trying to publish a message using any of Client’s publish functions.

PublishEvent

Enumerates the different stages of publishing a message with QoS::ExactlyOnce that can be awaited on.

QoS

The maximum Quality of Service used to transmit and receive messages.

ServerConnectError

An enumeration of all the possible error codes returned by the broker in response to the client’s CONNECT packet.

SubscribeError

An enumeration specifying what went wrong while trying to subscribe to a topic using any of Client’s subscribe functions.

SubscriptionStatus

The status of a topic subscription. Can be queried using Client::get_subscription_status().

TimeoutKind

This enum specifies which operation in particular triggered a timeout while trying to connect to the broker.

TryPublishError

An enumeration specifying what went wrong while trying to publish a message using Client::try_publish().