Interface definition for MQTT client.

#include "stddef.h"
#include "stdbool.h"
#include "stdint.h"
#include "AWS_SDK/aws_iot_src/utils/aws_iot_error.h"

Data Structures
struct	MQTTCallbackParams
	MQTT Callback Function Parameters. More...

struct	MQTTClient_t
	MQTT Client Type Definition. More...

struct	MQTTConnectParams
	MQTT Connection Parameters. More...

struct	MQTTMessageParams
	MQTT Message Parameters. More...

struct	MQTTPublishParams
	MQTT Publish Parameters. More...

struct	MQTTSubscribeParams
	MQTT Subscription Parameters. More...

struct	MQTTwillOptions
	Last Will and Testament Definition. More...

Typedefs
typedef void(*	iot_disconnect_handler )(void)
	Disconnect Callback Handler Type. More...

typedef int32_t(*	iot_message_handler )(MQTTCallbackParams params)
	MQTT Callback Function. More...

typedef IoT_Error_t(*	pConnectFunc_t )(MQTTConnectParams *pParams)

typedef IoT_Error_t(*	pDisconnectFunc_t )(void)

typedef bool(*	pIsAutoReconnectEnabledFunc_t )(void)

typedef bool(*	pIsConnectedFunc_t )(void)

typedef IoT_Error_t(*	pPublishFunc_t )(MQTTPublishParams *pParams)

typedef IoT_Error_t(*	pReconnectFunc_t )()

typedef IoT_Error_t(*	pSetAutoReconnectStatusFunc_t )(bool)

typedef IoT_Error_t(*	pSubscribeFunc_t )(MQTTSubscribeParams *pParams)

typedef IoT_Error_t(*	pUnsubscribeFunc_t )(char *pTopic)

typedef IoT_Error_t(*	pYieldFunc_t )(int timeout)

Enumerations
enum	MQTT_Ver_t { MQTT_3_1 = 3, MQTT_3_1_1 = 4 }
	MQTT Version Type. More...

enum	QoSLevel { QOS_0, QOS_1, QOS_2 }
	Quality of Service Type. More...

Functions
bool	aws_iot_is_autoreconnect_enabled (void)
	Is the MQTT client set to reconnect automatically? More...

bool	aws_iot_is_mqtt_connected (void)
	Is the MQTT client currently connected? More...

IoT_Error_t	aws_iot_mqtt_attempt_reconnect (void)
	MQTT Manual Re-Connection Function. More...

IoT_Error_t	aws_iot_mqtt_autoreconnect_set_status (bool value)
	Enable or Disable AutoReconnect on Network Disconnect. More...

IoT_Error_t	aws_iot_mqtt_connect (MQTTConnectParams *pParams)
	MQTT Connection Function. More...

IoT_Error_t	aws_iot_mqtt_disconnect (void)
	Disconnect an MQTT Connection. More...

void	aws_iot_mqtt_init (MQTTClient_t *pClient)
	Set the MQTT client. More...

IoT_Error_t	aws_iot_mqtt_publish (MQTTPublishParams *pParams)
	Publish an MQTT message on a topic. More...

IoT_Error_t	aws_iot_mqtt_subscribe (MQTTSubscribeParams *pParams)
	Subscribe to an MQTT topic. More...

IoT_Error_t	aws_iot_mqtt_unsubscribe (char *pTopic)
	Unsubscribe to an MQTT topic. More...

IoT_Error_t	aws_iot_mqtt_yield (int timeout)
	Yield to the MQTT client. More...

Variables
const MQTTCallbackParams	MQTTCallbackParamsDefault

const MQTTConnectParams	MQTTConnectParamsDefault

const MQTTMessageParams	MQTTMessageParamsDefault

const MQTTPublishParams	MQTTPublishParamsDefault

const MQTTSubscribeParams	MQTTSubscribeParamsDefault

const MQTTwillOptions	MQTTwillOptionsDefault

typedef void(* iot_disconnect_handler)(void)

Disconnect Callback Handler Type.

Defining a TYPE for definition of disconnect callback function pointers.

typedef int32_t(* iot_message_handler)(MQTTCallbackParams params)

MQTT Callback Function.

Defines a type for the function pointer which stores the message callback function. A pointer to the desired callback function to be invoked upon receipt of a message on a subscribed toipc. Supplied upon subscribing to a topic.

typedef IoT_Error_t(* pConnectFunc_t)(MQTTConnectParams *pParams)

typedef IoT_Error_t(* pDisconnectFunc_t)(void)

typedef bool(* pIsAutoReconnectEnabledFunc_t)(void)

typedef bool(* pIsConnectedFunc_t)(void)

typedef IoT_Error_t(* pPublishFunc_t)(MQTTPublishParams *pParams)

typedef IoT_Error_t(* pReconnectFunc_t)()

typedef IoT_Error_t(* pSetAutoReconnectStatusFunc_t)(bool)

typedef IoT_Error_t(* pSubscribeFunc_t)(MQTTSubscribeParams *pParams)

typedef IoT_Error_t(* pUnsubscribeFunc_t)(char *pTopic)

typedef IoT_Error_t(* pYieldFunc_t)(int timeout)

enum MQTT_Ver_t

MQTT Version Type.

Defining an MQTT version type.

Enumerator
MQTT_3_1	MQTT 3.1 (protocol message byte = 3)
MQTT_3_1_1	MQTT 3.1.1 (protocol message byte = 4)

enum QoSLevel

Quality of Service Type.

Defining a QoS type.

Note: QoS 2 is NOT supported by the AWS IoT Service at the time of this SDK release.

Enumerator
QOS_0	QoS 0 = at most once delivery.
QOS_1	QoS 1 = at least once delivery.
QOS_2	QoS 2 is NOT supported.

bool aws_iot_is_autoreconnect_enabled ( void )

Is the MQTT client set to reconnect automatically?

Called to determine if the MQTT client is set to reconnect automatically. Used to support logic in the device application around reconnecting

Returns: true = enabled, false = disabled

References MQTTIsAutoReconnectEnabled().

Referenced by aws_iot_mqtt_init(), and disconnectCallbackHandler().

bool aws_iot_is_mqtt_connected ( void )

Is the MQTT client currently connected?

Called to determine if the MQTT client is currently connected. Used to support logic in the device application around reconnecting and managing offline state.

Returns: true = connected, false = not currently connected

References MQTTIsConnected().

Referenced by aws_iot_mqtt_init().

IoT_Error_t aws_iot_mqtt_attempt_reconnect ( void )

MQTT Manual Re-Connection Function.

Called to establish an MQTT connection with the AWS IoT Service using parameters from the last time a connection was attempted Use after disconnect to start the reconnect process manually Makes only one reconnect attempt

Returns: An IoT Error Type defining successful/failed connection

References GENERIC_ERROR, MQTT_NETWORK_ALREADY_CONNECTED_ERROR, MQTT_NETWORK_DISCONNECTED_ERROR, MQTT_NETWORK_RECONNECTED, MQTT_NULL_VALUE_ERROR, MQTT_RECONNECT_TIMED_OUT, MQTTAttemptReconnect(), NETWORK_ALREADY_CONNECTED, NETWORK_DISCONNECTED, NETWORK_RECONNECT_TIMED_OUT, NULL_VALUE_ERROR, and RECONNECT_SUCCESSFUL.

Referenced by aws_iot_mqtt_init(), and disconnectCallbackHandler().

IoT_Error_t aws_iot_mqtt_autoreconnect_set_status ( bool value )

Enable or Disable AutoReconnect on Network Disconnect.

Called to enable or disabled the auto reconnect features provided with the SDK

Parameters

value set to true for enabling and false for disabling

Returns: IoT_Error_t Type defining successful/failed API call

References MQTT_NULL_VALUE_ERROR, NONE_ERROR, NULL_VALUE_ERROR, and setAutoReconnectEnabled().

Referenced by aws_iot_mqtt_init(), and main().

IoT_Error_t aws_iot_mqtt_connect ( MQTTConnectParams * pParams )

MQTT Connection Function.

Called to establish an MQTT connection with the AWS IoT Service

Parameters

pParams Pointer to MQTT connection parameters

Returns: An IoT Error Type defining successful/failed connection

References AWS_IOT_MQTT_RX_BUF_LEN, AWS_IOT_MQTT_TX_BUF_LEN, MQTTPacket_connectData::cleansession, clientDisconnectHandler, MQTTPacket_connectData::clientID, CONNECTION_ERROR, MQTTString::cstring, TLSConnectParams::DestinationPort, MQTTConnectParams::disconnectHandler, MQTTConnectParams::enableAutoReconnect, iot_tls_init(), MQTTConnectParams::isCleansession, isPowerCycle, MQTTwillOptions::isRetained, MQTTConnectParams::isSSLHostnameVerify, MQTTConnectParams::isWillMsgPresent, MQTTPacket_connectData::keepAliveInterval, MQTTConnectParams::KeepAliveInterval_sec, MQTTPacket_willOptions::message, MQTT_3_1, MQTT_3_1_1, MQTT_NETWORK_ALREADY_CONNECTED_ERROR, MQTTClient(), MQTTConnectParams::mqttCommandTimeout_ms, MQTTConnect(), MQTTPacket_connectData_initializer, MQTTConnectParams::MQTTVersion, MQTTPacket_connectData::MQTTVersion, NETWORK_ALREADY_CONNECTED, NONE_ERROR, NULL, NULL_VALUE_ERROR, pahoDisconnectHandler(), MQTTPacket_connectData::password, MQTTConnectParams::pClientID, TLSConnectParams::pDestinationURL, TLSConnectParams::pDeviceCertLocation, MQTTConnectParams::pDeviceCertLocation, TLSConnectParams::pDevicePrivateKeyLocation, MQTTConnectParams::pDevicePrivateKeyLocation, MQTTConnectParams::pHostURL, MQTTwillOptions::pMessage, MQTTConnectParams::port, MQTTConnectParams::pPassword, TLSConnectParams::pRootCALocation, MQTTConnectParams::pRootCALocation, MQTTwillOptions::pTopicName, MQTTConnectParams::pUserName, MQTTwillOptions::qos, MQTTPacket_willOptions::qos, readbuf, MQTTPacket_willOptions::retained, TLSConnectParams::ServerVerificationFlag, setDisconnectHandler(), SUCCESS, TLSConnectParams::timeout_ms, MQTTConnectParams::tlsHandshakeTimeout_ms, MQTTPacket_willOptions::topicName, MQTTPacket_connectData::username, MQTTConnectParams::will, MQTTPacket_connectData::will, MQTTPacket_connectData::willFlag, and writebuf.

Referenced by aws_iot_mqtt_init(), and main().

IoT_Error_t aws_iot_mqtt_disconnect ( void )

Disconnect an MQTT Connection.

Called to send a disconnect message to the broker.

Returns: An IoT Error Type defining successful/failed send of the disconnect control packet.

References DISCONNECT_ERROR, MQTTDisconnect(), and NONE_ERROR.

Referenced by aws_iot_mqtt_init().

void aws_iot_mqtt_init ( MQTTClient_t * pClient )

Set the MQTT client.

This function provides a way to pass in an MQTT client implementation to the AWS IoT MQTT wrapper layer. This is done through function pointers to the interface functions.

References aws_iot_is_autoreconnect_enabled(), aws_iot_is_mqtt_connected(), aws_iot_mqtt_attempt_reconnect(), aws_iot_mqtt_autoreconnect_set_status(), aws_iot_mqtt_connect(), aws_iot_mqtt_disconnect(), aws_iot_mqtt_publish(), aws_iot_mqtt_subscribe(), aws_iot_mqtt_unsubscribe(), aws_iot_mqtt_yield(), MQTTClient_t::connect, MQTTClient_t::disconnect, MQTTClient_t::isAutoReconnectEnabled, MQTTClient_t::isConnected, MQTTClient_t::publish, MQTTClient_t::reconnect, MQTTClient_t::setAutoReconnectStatus, MQTTClient_t::subscribe, MQTTClient_t::unsubscribe, and MQTTClient_t::yield.

IoT_Error_t aws_iot_mqtt_publish ( MQTTPublishParams * pParams )

Publish an MQTT message on a topic.

Called to publish an MQTT message on a topic.

Note: Call is blocking. In the case of a QoS 0 message the function returns after the message was successfully passed to the TLS layer. In the case of QoS 1 the function returns after the receipt of the PUBACK control packet.

Parameters

pParams Pointer to MQTT publish parameters

Returns: An IoT Error Type defining successful/failed publish

References MQTTMessage::dup, MQTTMessage::id, MQTTMessageParams::id, MQTTMessageParams::isDuplicate, MQTTMessageParams::isRetained, MQTTPublishParams::MessageParams, MQTTPublish(), NONE_ERROR, MQTTMessage::payload, MQTTMessage::payloadlen, MQTTMessageParams::PayloadLen, MQTTMessageParams::pPayload, MQTTPublishParams::pTopic, PUBLISH_ERROR, MQTTMessage::qos, MQTTMessageParams::qos, and MQTTMessage::retained.

Referenced by aws_iot_mqtt_init(), and main().

IoT_Error_t aws_iot_mqtt_subscribe ( MQTTSubscribeParams * pParams )

Subscribe to an MQTT topic.

Called to send a subscribe message to the broker requesting a subscription to an MQTT topic.

Note: Call is blocking. The call returns after the receipt of the SUBACK control packet.

Parameters

pParams Pointer to MQTT subscribe parameters

Returns: An IoT Error Type defining successful/failed subscription

References MQTTSubscribeParams::mHandler, MQTTSubscribe(), NONE_ERROR, pahoMessageCallback(), MQTTSubscribeParams::pTopic, MQTTSubscribeParams::qos, and SUBSCRIBE_ERROR.

Referenced by aws_iot_mqtt_init(), and main().

IoT_Error_t aws_iot_mqtt_unsubscribe ( char * pTopic )

Unsubscribe to an MQTT topic.

Called to send an usubscribe message to the broker requesting removal of a subscription to an MQTT topic.

Note: Call is blocking. The call returns after the receipt of the UNSUBACK control packet.

Parameters

pTopic Pointer to the requested topic string. Ensure the string is null terminated

Returns: An IoT Error Type defining successful/failed unsubscription

References MQTTUnsubscribe(), NONE_ERROR, and UNSUBSCRIBE_ERROR.

Referenced by aws_iot_mqtt_init().

IoT_Error_t aws_iot_mqtt_yield ( int timeout )

Yield to the MQTT client.

Called to yield the current thread to the underlying MQTT client. This time is used by the MQTT client to manage PING requests to monitor the health of the TCP connection as well as periodically check the socket receive buffer for subscribe messages. Yield() must be called at a rate faster than the keepalive interval. It must also be called at a rate faster than the incoming message rate as this is the only way the client receives processing time to manage incoming messages.

Parameters

timeout Maximum number of milliseconds to pass thread execution to the client.

Returns: An IoT Error Type defining successful/failed client processing. If this call results in an error it is likely the MQTT connection has dropped. iot_is_mqtt_connected can be called to confirm.

References MQTT_ATTEMPTING_RECONNECT, MQTT_BUFFER_RX_MESSAGE_INVALID, MQTT_NETWORK_DISCONNECTED_ERROR, MQTT_NETWORK_RECONNECTED, MQTT_NULL_VALUE_ERROR, MQTT_RECONNECT_TIMED_OUT, MQTTPACKET_BUFFER_TOO_SHORT, MQTTYield(), NETWORK_ATTEMPTING_RECONNECT, NETWORK_DISCONNECTED, NETWORK_RECONNECT_TIMED_OUT, NONE_ERROR, NULL_VALUE_ERROR, RECONNECT_SUCCESSFUL, RX_MESSAGE_BIGGER_THAN_MQTT_RX_BUF, RX_MESSAGE_INVALID, SUCCESS, and YIELD_ERROR.