Module session

MQTT client providing a managed connection with automatic reconnection across a single MQTT session.

This module provides several key components for using an MQTT session:

• Session - Manages the lifetime of the MQTT session
• SessionManagedClient - Sends MQTT messages to the broker
• SessionPubReceiver - Receives MQTT messages from the broker
• SessionConnectionMonitor - Provides information about MQTT connection state
• SessionExitHandle - Allows the user to exit the session gracefully

Session lifespan

Each instance of Session is single use - after configuring a Session, and creating any other necessary components from it, calling the run method will consume the Session and block (asynchronously) until the MQTT session shared between client and broker ends. Note that a MQTT session can span multiple connects and disconnects to the broker.

The MQTT session can be ended one of three ways:

1. The MQTT broker ends the MQTT session
2. The ReconnectPolicy configured on the Session halts reconnection attempts, causing the Session to end the MQTT session.
3. The user uses the SessionExitHandle to end the MQTT session.
   The SessionExitHandle currently only causes the exit of the Session client not the end of the MQTT session shared with the broker. This limitation will be fixed in future updates.

Sending and receiving data over MQTT

A Session can be used to create a SessionManagedClient for sending data (i.e. outgoing MQTT PUBLISH, MQTT SUBSCRIBE, MQTT UNSUBSCRIBE), and can in turn be used to create a SessionPubReceiver for receiving incoming data (i.e. incoming MQTT PUBLISH).

SessionPubReceivers can be either filtered or unfiltered - a filtered receiver will only receive messages that match a specific topic filter, while an unfiltered receiver will receive all messages that do not match another existing filter.

Note that in order to receive incoming data, you must both subscribe to the topic filter of interest using the SessionManagedClient and create a SessionPubReceiver (filtered or unfiltered). If an incoming message is received that does not match any SessionPubReceivers, it will be acknowledged to the MQTT broker and discarded. Thus, in order to guarantee that messages will not be lost, you should create the SessionPubReceiver before subscribing to the topic filter.

Modules

• managed_client
  Internal implementation of SessionManagedClient and SessionPubReceiver.
• reconnect_policy
  Reconnect policies for a Session.

Structs

• Session
  Client that manages connections over a single MQTT session.
• SessionConfigError
  Error configuring a Session.
• SessionConnectionMonitor
  Monitor for connection changes in the Session.
• SessionError
  Error describing why a Session ended prematurely
• SessionExitError
  Error type for exiting a Session using the SessionExitHandle.
• SessionExitHandle
  Handle used to end an MQTT session.
• SessionManagedClient
  An MQTT client that has it’s connection state externally managed by a Session. Can be used to send messages and create receivers for incoming messages.
• SessionOptions
  Options for configuring a new Session
• SessionOptionsBuilder
  Builder for SessionOptions.
• SessionPubReceiver
  Receive and acknowledge incoming MQTT messages.

Enums

• SessionExitErrorKind
  An enumeration of categories of SessionExitError
• SessionOptionsBuilderError
  Error type for SessionOptionsBuilder