mqtt_set_lwt

Sets the Last Will and Testament message.

C Language

int mqtt_set_lwt( MQTT handle, const char* topic, const char* payload, int length, enum MQTT_QOS qos, enum MQTT_RETAIN_FLAG retainFlag);

Example MQTT Vuser Functions

Arguments

Name Comments
handle The MQTT client handle returned by mqtt_create.
topic The destination topic as a NULL-terminated string, for example: myhome/kitchen/temperature/lwt
payload

The message payload as a pointer to a binary buffer or a NULL-terminated string.

length The message payload length in bytes. Pass MQTT_AUTO for NULL-terminated strings.
qos The required quality of service (QoS). An element of the MQTT_QOS enum. One of:
  • MQTT_QOS_DEFAULT - The value from the runtime settings.
  • MQTT_QOS0 - 0
  • MQTT_QOS1 - 1
  • MQTT_QOS2 - 2
retainFlag

The message retention flag. An element of the MQTT_RETAIN_FLAG enum. One of:

  • MQTT_NORETAIN - Instructs the broker not to store the message in this topic.

  • MQTT_RETAIN - Instructs the broker to store the last retained message in this topic together with its QoS. Only one message is stored per topic, so the last retained message always replaces any previously stored message. Useful for providing the latest status to new subscribers when they subscribe to a topic, so they do not need to wait for the next status update.

General

mqtt_set_lwt sets the message the broker sends to other subscribers of the specified topic when the client disconnects unexpectedly. For example, the message is sent when the client disconnects because of network problems. Call this function before mqtt_connect.

If invalid arguments are passed, the Vuser aborts, even if Continue on error is set.

Return Values

MQTT_SUCCESS or MQTT_FAIL

Parameterization

Standard parameterization is available for this function.

Exception: payload cannot be parametrized.

Example

MQTT client = mqtt_create();

/* LWT message "Sensor 1 disconnected" will be posted to topic "sensors/lwt" and stored with default QoS in case of unexpected disconnect */

mqtt_set_lwt(client, "sensors/lwt", "Sensor 1 disconnected", MQTT_AUTO, MQTT_DEFAULT, MQTT_RETAIN);

mqtt_connect(client, "tcp://test.broker.com:1883");