Share this page

# 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);

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/1`.
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. 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 Information

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);`

Tips to improve your search results... VuGen Function Reference Version 25.1-25.3 Function Reference 25.1-25.3 All View Local Help Center View Online Help Center Version: