How to migrate an MQTT application from v3 to v4.

The MQTT library has been redesigned in v4 as a thread-aware library supporting asynchronous operations. New features such as persistent session support and retry of QoS 1 publish messages have also been added.

The features of the MQTT libraries in v3 and v4 are defined by the common MQTT 3.1.1 spec; therefore, the two versions are similar.

Removed features

The following features which were present in v3 were removed in v4.

Auto-reconnect
Version 3 has an auto-reconnect feature triggered through a call to aws_iot_mqtt_yield. In version 4, aws_iot_mqtt_yield has been removed and replaced with background tasks.
Workaround: When a version 4 API call returns IOT_MQTT_NETWORK_ERROR or the version 4 MQTT disconnect callback is invoked, call IotMqtt_Connect through the application. The application should employ an exponential backoff strategy when re-establishing connections.

Data Types

The following table lists equivalent data types in v3 and v4.

Version 3	Version 4	Notes
enum QoS	IotMqttQos_t	MQTT Quality of service.
AWS_IoT_Client	IotMqttConnection_t	MQTT connection handle.
IoT_Publish_Message_Params	IotMqttPublishInfo_t	Parameters of an MQTT publish.
IoT_MQTT_Will_Options IoT_Client_Connect_Params	IotMqttConnectInfo_t	Parameters of an MQTT connect. The two v3 structs are combined in v4.
IoT_Client_Init_Params	None	The members of this struct in v3 handled setup of the network connection. This has been moved to Networking in v4.

Functions

The following table lists equivalent API functions in v3 and v4. These functions are the API functions declared in:

In v3: aws_iot_mqtt_client_interface.h
In v4: MQTT functions

Version 3	Version 4	Notes
aws_iot_mqtt_init	IotMqtt_Init	In v3, this function initializes a single client. In v4, this function initializes the entire library.
aws_iot_mqtt_free	IotMqtt_Cleanup	In v3, this function frees a single client. In v4, this function cleans up the entire library.
aws_iot_mqtt_connect	IotMqtt_Connect
aws_iot_mqtt_publish	IotMqtt_PublishSync	IotMqtt_PublishAsync is the equivalent asynchronous function.
aws_iot_mqtt_subscribe	IotMqtt_SubscribeSync	IotMqtt_SubscribeAsync is the equivalent asynchronous function.
aws_iot_mqtt_resubscribe	None	Function removed because auto-reconnect was removed.
aws_iot_mqtt_unsubscribe	IotMqtt_UnsubscribeSync	IotMqtt_UnsubscribeAsync is the equivalent asynchronous function.
aws_iot_mqtt_disconnect	IotMqtt_Disconnect
aws_iot_mqtt_yield	None	Removed in favor of background tasks. Nothing needs to be changed in an application.
aws_iot_mqtt_attempt_reconnect	None	Function removed because auto-reconnect was removed.