AWS IoT Device SDK C: MQTT
MQTT 3.1.1 client library
Return to main page ↑
IotMqtt_PublishAsync

Publishes a message to the given topic name and optionally receive an asynchronous notification when the publish completes.

const IotMqttPublishInfo_t * pPublishInfo,
uint32_t flags,
const IotMqttCallbackInfo_t * pCallbackInfo,
IotMqttOperation_t * const pPublishOperation );

This function sends an MQTT PUBLISH packet to the server. A PUBLISH packet contains a payload and a topic name. Any clients with a subscription on a topic filter matching the PUBLISH topic name will receive a copy of the PUBLISH packet from the server.

If a PUBLISH packet fails to reach the server and it is not a QoS 0 message, it will be retransmitted. See IotMqttPublishInfo_t for a description of the retransmission strategy.

Attention
QoS 2 messages are currently unsupported. Only 0 or 1 are valid for message QoS.
Parameters
[in]mqttConnectionThe MQTT connection to use for the publish.
[in]pPublishInfoMQTT publish parameters.
[in]flagsFlags which modify the behavior of this function. See MQTT Function Flags.
[in]pCallbackInfoAsynchronous notification of this function's completion (NULL to disable).
[out]pPublishOperationSet to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the publish operation completes.
Returns
This function will return IOT_MQTT_STATUS_PENDING upon success for QoS 1 publishes. For a QoS 0 publish it returns IOT_MQTT_SUCCESS upon success.
Upon completion of a QoS 1 publish (either through an IotMqttCallbackInfo_t or IotMqtt_Wait), the status will be one of:
If this function fails before queuing an publish operation (regardless of QoS), it will return one of:
Note
The parameters pCallbackInfo and pPublishOperation should only be used for QoS 1 publishes. For QoS 0, they should both be NULL.
See also
IotMqtt_PublishSync for a blocking variant of this function.

Example

// An initialized and connected MQTT connection.
IotMqttConnection_t mqttConnection;
// Publish information.
// Set the publish information. QoS 0 example (retain not used):
publishInfo.qos = IOT_MQTT_QOS_0;
publishInfo.pTopicName = "some/topic/name";
publishInfo.topicNameLength = ( uint16_t ) strlen( publishInfo.pTopicName );
publishInfo.pPayload = "payload";
publishInfo.payloadLength = strlen( publishInfo.pPayload );
// QoS 0 publish should return IOT_MQTT_SUCCESS upon success.
IotMqttError_t qos0Result = IotMqtt_PublishAsync( mqttConnection,
&publishInfo,
0,
NULL,
NULL );
// QoS 1 with retry example (using same topic name and payload as QoS 0 example):
publishInfo.qos = IOT_MQTT_QOS_1;
publishInfo.retryMs = 1000; // Retry if no response is received in 1 second.
publishInfo.retryLimit = 5; // Retry up to 5 times.
// QoS 1 publish should return IOT_MQTT_STATUS_PENDING upon success.
IotMqttError_t qos1Result = IotMqtt_PublishAsync( mqttConnection,
&publishInfo,
NULL,
&qos1Operation );
// Wait up to 5 seconds for the publish to complete.
if( qos1Result == IOT_MQTT_STATUS_PENDING )
{
qos1Result = IotMqtt_Wait( qos1Operation, 5000 );
}