Determines whether a clean session is used once connected.
This property determines whether or not the control should instruct the server to use a clean session when it connects. (Note that this property must be set to the desired value before calling Connect.)
By default, CleanSession is true, so the server will discard any state data previously associated with the current ClientId once the control has connected successfully. In addition, the server will not save any state data when the control disconnects.
Setting CleanSession to False before connecting will cause the server to re-associate any previously stored state data for the current ClientId. The server will also save any state data that exists when the control is disconnected.
The server-side session state consists of:
- whether a session is present (see SessionPresent),
- client subscriptions (including subscription identifiers in MQTT 5),
- QoS 1 and 2 messages sent to the client pending transmission or completed acknowledgment (and optionally pending QoS 0 messages),
- QoS 2 messages received from the client but not completely acknowledged, and
- the SessionExpInterval (in MQTT 5).
Note that retained messages are not deleted as a result of a session ending, but are not part of the session state.
Client-Side Session State
When setting CleanSession to False, it is important that the RestoreSession method be used to load any previously saved (client-side) session data from a previous session before calling Connect. (Successful calls to RestoreSession will automatically set CleanSession to False.)
Similarly, once disconnected, save the string returned by SaveSession for later use. The saved session information may be used when connecting with CleanSession set to False at a later time.
The client-side session state consists of:
- QoS 1 and QoS 2 messages which have been sent to the Server, but have not been completely acknowledged, and
- QoS 2 messages which have been received from the Server, but have not been completely acknowledged.
MQTT 5 Notes
In MQTT 5, the "Clean Session" flag from v3.1.1 is split into a "Clean Start" flag indicating that the server should discard previously saved session data from this connection, and a SessionExpInterval controlling the length of time the server should preserve the session data after disconnection.
In MQTT 5, this property acts only as the "Clean Start" flag. It determines whether or not the control should instruct the server to discard any previously stored session data associated with the current ClientId and start a new clean session.
For more information on session expiration in MQTT 5, see the SessionExpInterval config. Setting CleanSession to True in v3.1.1 is equivalent to setting CleanSession to True AND setting SessionExpInterval to 0 in MQTT 5.
As with MQTT 3.1.1, it is important for the client to save and restore its own session data on connection and disconnection depending on the value of CleanSession, and to manage its preservation depending on SessionExpInterval.
This property is not available at design time.