1.1.18.9 Publishing
Topic Aliases
To use topic aliases the alias must first be associated with the topic name in the broker.
To associate a topic name with an alias the MQTT application should call WDRV_WINC_MQTTPublish
with a valid pTopicName
function argument as well as valid topicAlias
field within the WDRV_WINC_MQTT_PUB_PROP
structure with the WDRV_WINC_MQTT_MSG_INFO
structure passed to WDRV_WINC_MQTTPublish
.
WDRV_WINC_MQTT_MSG_INFO msgInfo; WDRV_WINC_MQTT_PUB_PROP pubProp; uint8_t topicData[5] = {1, 2, 3, 4, 5}; /* Initialize the message information structure to default values. */ WDRV_WINC_MQTTMsgInfoDefaultSet(&msgInfo); /* Initialize the publish property structure to default values. */ WDRV_WINC_MQTTPubPropDefaultSet(&pubProp); /* Set the Topic Alias property to 15. */ WDRV_WINC_MQTTPubPropTopicAliasSet(&pubProp, 15); /* Associate publish property structure with message information structure. */ WDRV_WINC_MQTTMsgInfoPubPropSet(&msgInfo, &pubProp); /* Publish 5 bytes of data to a topic "TopicName" with alias 15. */ WDRV_WINC_MQTTPublish(wdrvHandle, &msgInfo, "TopicName", topicData, sizeof(topicData), mqttPublishCallback, 0, NULL);
Subsequently the MQTT application can omit the pTopicName
function argument.
/* Publish 5 bytes of data to a topic with alias 15. */
WDRV_WINC_MQTTPublish(wdrvHandle, &msgInfo, NULL, topicData, sizeof(topicData), mqttPublishCallback, 0, NULL);
Publish Handle vs Packet ID
When calling WDRV_WINC_MQTTPublish
the caller can elect to store the publish handle, this is a short term handle available in case of immediate problems with the publish. Once a publish has been sent, if required, it will be issued a packet ID which will represent the publish operation long term.
Publish Status Callback
The WDRV_WINC_MQTT_PUB_STATUS_CALLBACK
registered with WDRV_WINC_MQTTPublish
is called whenever there is a status update on a publish operation. Depending on the QoS level of the publish there may be different status actions.
QoS = 0
For QoS 0 the only status will be if the publish fails to send. The status callback will then be called with the publish handle and the error condition.
Successful publishes receive no further feedback so no further status updates will be available.
QoS > 0
For QoS > 0 the MQTT client receive status feedback of the transmission to the broker, this will be made available via the status callback. Once accepted for transmission a packet ID replaces the publish handle and will be included in further status updates.
Publish Stages and Status Callback
The table below shows the expect status callback parameters for each possible publish event.
Event | Publish Handle | Packet ID | Status |
---|---|---|---|
QoS 0 Sent | n/a | n/a | n/a |
QoS 0 Error | Valid | 0 | WDRV_WINC_MQTT_PUB_STATUS_ERROR |
QoS 1 Sent | Valid | Valid | WDRV_WINC_MQTT_PUB_STATUS_SENT |
QoS 1 PUBACK | n/a | Valid | WDRV_WINC_MQTT_PUB_STATUS_RECV |
QoS 1 Error | n/a | Valid | WDRV_WINC_MQTT_PUB_STATUS_ERROR |
QoS 2 Sent | Valid | Valid | WDRV_WINC_MQTT_PUB_STATUS_SENT |
QoS 2 PUBCOMP | n/a | Valid | WDRV_WINC_MQTT_PUB_STATUS_RECV |
QoS 2 Error | n/a | Valid | WDRV_WINC_MQTT_PUB_STATUS_ERROR |