IotMqtt_PublishAsync

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

IotMqttError_t IotMqtt_PublishAsync( IotMqttConnection_t mqttConnection,
                                     const IotMqttPublishInfo_t * pPublishInfo,
                                     uint32_t flags,
                                     const IotMqttCallbackInfo_t * pCallbackInfo,
                                     IotMqttOperation_t * const pPublishOperation );

This function transmits 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]	mqttConnection	The MQTT connection to use for the publish.
[in]	pPublishInfo	MQTT publish parameters.
[in]	flags	Flags which modify the behavior of this function. See MQTT Function Flags.
[in]	pCallbackInfo	Asynchronous notification of this function's completion.
[out]	pPublishOperation	Set 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:

• IOT_MQTT_SUCCESS
• IOT_MQTT_NETWORK_ERROR
• IOT_MQTT_SCHEDULING_ERROR
• IOT_MQTT_BAD_RESPONSE
• IOT_MQTT_RETRY_NO_RESPONSE (if pPublishInfo->retryMs and pPublishInfo->retryLimit were set).

If this function fails before queuing an publish operation (regardless of QoS), it will return one of:

• IOT_MQTT_NOT_INITIALIZED
• IOT_MQTT_BAD_PARAMETER
• IOT_MQTT_NO_MEMORY

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.
IotMqttPublishInfo_t publishInfo = IOT_MQTT_PUBLISH_INFO_INITIALIZER;
 
// Set the publish information. QoS 0 example (retain not used):
publishInfo.qos = IOT_MQTT_QOS_0;
publishInfo.pTopicName = "some/topic/name";
publishInfo.topicNameLength = 15;
publishInfo.pPayload = "payload";
publishInfo.payloadLength = 8;
 
// 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):
IotMqttOperation_t qos1Operation = IOT_MQTT_OPERATION_INITIALIZER;
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,
                                                  IOT_MQTT_FLAG_WAITABLE,
                                                  NULL,
                                                  &qos1Operation );
 
// Wait up to 5 seconds for the publish to complete.
if( qos1Result == IOT_MQTT_STATUS_PENDING )
{
    qos1Result = IotMqtt_Wait( qos1Operation, 5000 );
}