Callback Functions

Callback functions are used by the µC/MQTT-client stack. Their purpose is to notify the upper application of certain activities occurring in the µC/MQTT-client core.

Each particular callback for every event is set with MQTTc_ConnSetParam and is optional. The p_arg parameter passed in every callback is also set via MQTTc_ConnSetParam with the MQTTc_PARAM_TYPE_CALLBACK_ARG_PTR type.

No blocking calls (delays, pending on an OS object, etc.) or long operations should ever be done in any of these callbacks. These callbacks are executed from the MQTTc stack internal task and if it is delayed or blocked, the whole MQTTc stack will be delayed/blocked, too, preventing the reception or transmission of any message on any connection.

On Complete Callbacks

The following callbacks  are of type MQTTc_CMPL_CALLBACK. Even though they are optional, they are necessary to know that a particular message has been completely sent, in order to re-use it for another message. The generic complete callback may be used to emulate all other callbacks in this category.

Table - MQTTc On Complete Callback Functions
Trigger EventDescriptionMQTTc_ConnSetParam type
Any message completed (in this section, not a received PUBLISH message)Generic notification for any event.MQTTc_PARAM_TYPE_CALLBACK_ON_COMPL
CONNECT message completedNotify that a CONNECT message has completed.MQTTc_PARAM_TYPE_CALLBACK_ON_CONNECT_CMPL
PUBLISH (to broker) message completedNotify that a PUBLISH message has completed.MQTTc_PARAM_TYPE_CALLBACK_ON_PUBLISH_CMPL
SUBSCRIBE message completedNotify that a SUBSCRIBE message has completed.MQTTc_PARAM_TYPE_CALLBACK_ON_SUBSCRIBE_CMPL
UNSUBSCRIBE message completedNotify that an UNSUBSCRIBE message has completed.MQTTc_PARAM_TYPE_CALLBACK_ON_UNSUBSCRIBE_CMPL
PINGREQ message completedNotify that a PINGREQ message has completed.MQTTc_PARAM_TYPE_CALLBACK_ON_PINGREQ_CMPL
DISCONNECT message completedNotify that a DISCONNECT message has completed.MQTTc_PARAM_TYPE_CALLBACK_ON_DISCONNECT_CMPL

On Error Callback

This callback is of type MQTTc_ERR_CALLBACK. Even though it is optional, it is recommended to have it, to know if a problem occurs.

Table - MQTTc On Error Callback Function
Trigger EventDescriptionMQTTc_ConnSetParam type
At any time an error occurs on the connection and is not related to a particular messageNotify that an error occurred on the connection.MQTTc_PARAM_TYPE_CALLBACK_ON_ERR_CALLBACK


On PUBLISH message received callback

This callback is of type MQTTc_PUBLISH_RX_CALLBACK. This callback is required only if the application expects to receive data from the broker. If not, it will never be called.

Table - MQTTc On PUBLISH received Callback Function
Trigger EventDescriptionMQTTc_ConnSetParam type
A PUBLISH message has been completely receivedNotify that a PUBLISH message has completed to be received.MQTTc_PARAM_TYPE_CALLBACK_ON_PUBLISH_RX