Struct Client 

pub struct Client { /* private fields */ }

A synchronous client, communicates with MQTT EventLoop.

This is cloneable and can be used to synchronously publish, subscribe through the EventLoop/Connection, which is to be polled in parallel by iterating over the object returned by Connection.iter() in a separate thread.

NOTE: The EventLoop/Connection must be regularly polled(.next() in case of Connection) in order to send, receive and process packets from the broker, i.e. move ahead.

An asynchronous channel handle can also be extracted if necessary.

Implementations

impl Client

pub const fn builder(options: MqttOptions) -> ClientBuilder

Create a builder for a Client.

The returned ClientBuilder only builds the synchronous client pair, which keeps the terminal build() method aligned with this entry point.

pub const fn from_sender(request_tx: Sender<Request>) -> Self

Create a new Client from a channel Sender.

This is mostly useful for creating a test instance where you can listen on the corresponding receiver.

pub fn publish<T, V>( &self, topic: T, qos: QoS, retain: bool, payload: V, ) -> Result<(), ClientError>

where T: Into<PublishTopic>, V: Into<Vec<u8>>,

Sends a MQTT Publish to the EventLoop

Errors

Returns an error if the topic is invalid or if the request cannot be queued on the event loop.

pub fn try_publish<T, V>( &self, topic: T, qos: QoS, retain: bool, payload: V, ) -> Result<(), ClientError>

where T: Into<PublishTopic>, V: Into<Vec<u8>>,

Attempts to send a MQTT Publish to the EventLoop.

Errors

Returns an error if the topic is invalid or if the request cannot be queued immediately on the event loop.

pub const fn prepare_ack(&self, publish: &Publish) -> Option<ManualAck>

Prepares a MQTT PubAck/PubRec packet for manual acknowledgement.

Returns None for QoS0 publishes, which do not require acknowledgement.

pub fn manual_ack(&self, ack: ManualAck) -> Result<(), ClientError>

Sends a prepared MQTT PubAck/PubRec to the EventLoop.

Errors

Returns an error if the acknowledgement cannot be queued on the event loop.

pub fn try_manual_ack(&self, ack: ManualAck) -> Result<(), ClientError>

Attempts to send a prepared MQTT PubAck/PubRec to the EventLoop.

Errors

Returns an error if the acknowledgement cannot be queued immediately on the event loop.

pub fn ack(&self, publish: &Publish) -> Result<(), ClientError>

Sends a MQTT PubAck/PubRec to the EventLoop based on publish QoS. Only needed if the manual_acks flag is set.

Errors

Returns an error if the derived acknowledgement cannot be queued on the event loop.

pub fn try_ack(&self, publish: &Publish) -> Result<(), ClientError>

Attempts to send a MQTT PubAck/PubRec to the EventLoop based on publish QoS. Only needed if the manual_acks flag is set.

Errors

Returns an error if the derived acknowledgement cannot be queued immediately on the event loop.

pub fn subscribe<S: Into<String>>( &self, topic: S, qos: QoS, ) -> Result<(), ClientError>

Sends a MQTT Subscribe to the EventLoop

Errors

Returns an error if the topic filter is invalid or if the request cannot be queued on the event loop.

pub fn try_subscribe<S: Into<String>>( &self, topic: S, qos: QoS, ) -> Result<(), ClientError>

Sends a MQTT Subscribe to the EventLoop

Errors

Returns an error if the topic filter is invalid or if the request cannot be queued immediately on the event loop.

pub fn subscribe_many<T>(&self, topics: T) -> Result<(), ClientError>

where T: IntoIterator<Item = SubscribeFilter>,

Sends a MQTT Subscribe for multiple topics to the EventLoop

Errors

Returns an error if the filter list is invalid or if the request cannot be queued on the event loop.

pub fn try_subscribe_many<T>(&self, topics: T) -> Result<(), ClientError>

where T: IntoIterator<Item = SubscribeFilter>,

Attempts to send a MQTT Subscribe for multiple topics to the EventLoop.

Errors

Returns an error if the filter list is invalid or if the request cannot be queued immediately on the event loop.

pub fn unsubscribe<S: Into<String>>(&self, topic: S) -> Result<(), ClientError>

Sends a MQTT Unsubscribe to the EventLoop

Errors

Returns an error if the request cannot be queued on the event loop.

pub fn try_unsubscribe<S: Into<String>>( &self, topic: S, ) -> Result<(), ClientError>

Sends a MQTT Unsubscribe to the EventLoop

Errors

Returns an error if the request cannot be queued immediately on the event loop.

pub fn disconnect(&self) -> Result<(), ClientError>

Queues a graceful MQTT disconnect barrier.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete before sending MQTT DISCONNECT.

This request uses the normal client request channel. Under publish flow-control pressure, it may pass earlier QoS 1/ QoS 2 publishes that are not currently sendable; once observed, it becomes the graceful drain barrier.

Errors

Returns an error if the disconnect request cannot be queued on the event loop.

pub fn disconnect_with_timeout( &self, timeout: Duration, ) -> Result<(), ClientError>

Queues a graceful MQTT disconnect barrier with a drain timeout.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits up to timeout for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete. QoS 1 publishes complete on PUBACK, QoS 2 publishes complete on PUBCOMP, tracked subscribes complete on SUBACK, and tracked unsubscribes complete on UNSUBACK.

If the drain completes before the deadline, the event loop sends and flushes MQTT DISCONNECT. If the deadline expires first, polling returns ConnectionError::DisconnectTimeout and MQTT DISCONNECT is not sent.

This request uses the normal client request channel. The timeout starts only after the event loop observes this request, not necessarily when this method queues it.

Errors

Returns an error if the disconnect request cannot be queued on the event loop.

pub fn disconnect_now(&self) -> Result<(), ClientError>

Sends a MQTT disconnect immediately without waiting for in-flight requests.

This request uses a dedicated immediate shutdown channel, not the normal application request channel. It may bypass queued application work and does not wait for unresolved QoS 1/ QoS 2 publish handshakes.

Errors

Returns an error if the disconnect request cannot be queued on the event loop.

pub fn try_disconnect(&self) -> Result<(), ClientError>

Attempts to queue a graceful MQTT disconnect barrier.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete before sending MQTT DISCONNECT.

This request uses the normal client request channel. Under publish flow-control pressure, it may pass earlier QoS 1/ QoS 2 publishes that are not currently sendable; once observed, it becomes the graceful drain barrier.

Errors

Returns an error if the disconnect request cannot be queued immediately on the event loop.

pub fn try_disconnect_with_timeout( &self, timeout: Duration, ) -> Result<(), ClientError>

Attempts to queue a graceful MQTT disconnect barrier with a drain timeout.

Once the event loop observes this request, it stops processing later application work, flushes previously accepted QoS 0 publishes, and waits up to timeout for previously accepted outbound QoS 1/ QoS 2 publishes and tracked subscribe/unsubscribe requests to complete. QoS 1 publishes complete on PUBACK, QoS 2 publishes complete on PUBCOMP, tracked subscribes complete on SUBACK, and tracked unsubscribes complete on UNSUBACK.

If the drain completes before the deadline, the event loop sends and flushes MQTT DISCONNECT. If the deadline expires first, polling returns ConnectionError::DisconnectTimeout and MQTT DISCONNECT is not sent.

This request uses the normal client request channel. The timeout starts only after the event loop observes this request, not necessarily when this method queues it.

Errors

Returns an error if the disconnect request cannot be queued immediately on the event loop.

pub fn try_disconnect_now(&self) -> Result<(), ClientError>

Sends a MQTT disconnect immediately without waiting for in-flight requests.

This request uses a dedicated immediate shutdown channel, not the normal application request channel. It may bypass queued application work and does not wait for unresolved QoS 1/ QoS 2 publish handshakes.

Errors

Returns an error if the disconnect request cannot be queued immediately on the event loop.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.