MQTT API Reference
MQTT 3.1.1 client library
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 );
}
IOT_MQTT_STATUS_PENDING
MQTT operation queued, awaiting result.
Definition: iot_mqtt_types.h:129
IotMqttPublishInfo_t::retryLimit
uint32_t retryLimit
How many times to attempt retransmission.
Definition: iot_mqtt_types.h:400
IotMqttError_t
IotMqttError_t
Return codes of MQTT functions.
Definition: iot_mqtt_types.h:103
IotMqttCallbackInfo_t
MQTT callback function and context.
Definition: iot_mqtt_types.h:507
IotMqtt_PublishAsync
IotMqttError_t IotMqtt_PublishAsync(IotMqttConnection_t mqttConnection, const IotMqttPublishInfo_t *pPublishInfo, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pPublishOperation)
Publishes a message to the given topic name and optionally receive an asynchronous notification when ...
Definition: iot_mqtt_api.c:1619
IotMqttPublishInfo_t::pPayload
const void * pPayload
Payload of PUBLISH.
Definition: iot_mqtt_types.h:396
IotMqttOperation_t
struct _mqttOperation * IotMqttOperation_t
Opaque handle that references an in-progress MQTT operation.
Definition: iot_mqtt_types.h:88
IotMqttPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of IotMqttPublishInfo_t.pTopicName.
Definition: iot_mqtt_types.h:394
IotMqttPublishInfo_t::pTopicName
const char * pTopicName
Topic name of PUBLISH.
Definition: iot_mqtt_types.h:393
IotMqttPublishInfo_t::retryMs
uint32_t retryMs
If no response is received within this time, the message is retransmitted.
Definition: iot_mqtt_types.h:399
IotMqttConnection_t
struct _mqttConnection * IotMqttConnection_t
Opaque handle of an MQTT connection.
Definition: iot_mqtt_types.h:66
IotMqttPublishInfo_t::qos
IotMqttQos_t qos
QoS of message. Must be 0 or 1.
Definition: iot_mqtt_types.h:390
IOT_MQTT_QOS_0
Definition: iot_mqtt_types.h:305
IotMqttPublishInfo_t::payloadLength
size_t payloadLength
Length of IotMqttPublishInfo_t.pPayload. For LWT messages, this is limited to 65535.
Definition: iot_mqtt_types.h:397
IOT_MQTT_QOS_1
Definition: iot_mqtt_types.h:306
IotMqtt_Wait
IotMqttError_t IotMqtt_Wait(IotMqttOperation_t operation, uint32_t timeoutMs)
Waits for an operation to complete.
Definition: iot_mqtt_api.c:1916
IotMqttPublishInfo_t
Information on a PUBLISH message.
Definition: iot_mqtt_types.h:388
IOT_MQTT_FLAG_WAITABLE
#define IOT_MQTT_FLAG_WAITABLE
Allows the use of IotMqtt_Wait for blocking until completion.
Definition: iot_mqtt_types.h:1152
IOT_MQTT_PUBLISH_INFO_INITIALIZER
#define IOT_MQTT_PUBLISH_INFO_INITIALIZER
Initializer for IotMqttPublishInfo_t.
Definition: iot_mqtt_types.h:1126
IOT_MQTT_OPERATION_INITIALIZER
#define IOT_MQTT_OPERATION_INITIALIZER
Initializer for IotMqttOperation_t.
Definition: iot_mqtt_types.h:1134