mqtt_publish

Publishes a message.

C Language

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

ExampleMQTT Vuser Functions

Arguments

NameComments
handleThe MQTT client handle returned by mqtt_create.
topicThe destination topic as a null-terminated string, for example myhome/kitchen/temperature/1.
payloadThe message payload as a pointer to a binary buffer or a null-terminated string.
lengthThe message payload length in bytes. Pass MQTT_AUTO for NULL-terminated strings.
qosThe required quality of service. An element of the MQTT_QOS enum. One of:
  • MQTT_QOS_DEFAULT - Value from 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_publish publishes a message to the specified topic.

If the connection is lost during an mqtt_publish operation where QoS = 0, the client will not try to publish again after reconnecting, and a warning will be displayed in the script's output.

You can limit the number of published messages in the incoming message queue (Inbox) by setting the MQTT runtime setting, Maximum number of pending messages in the Inbox. (Default: 1000 messages.) If the Inbox contains more than the defined number of messages, the script will end with an error.

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

/* Publish message "20 degrees" to the topic "sensors/temperature/room1" and store the message with default QoS.

The length is a null-terminated string that is calculated automatically because MQTT_AUTO is passed.

*/

mqtt_publish(client, "sensors/temperature/room1", "20 degrees", MQTT_AUTO, MQTT_DEFAULT, MQTT_RETAIN);