MQTT Agent Interface. More...

#include "FreeRTOS.h"
#include "aws_mqtt_lib.h"
#include "aws_lib_init.h"

Data Structures
struct	MQTTAgentCallbackParams
	Passed by the library in the callback to inform the user of various events. More...

struct	MQTTAgentConnectParams
	Parameters passed to the MQTT_AGENT_Connect API. More...

struct	MQTTAgentSubscribeParams
	Parameters passed to the MQTT_AGENT_Subscribe API. More...

struct	MQTTAgentUnsubscribeParams
	Parameters passed to the MQTT_AGENT_Unsubscribe API. More...

struct	MQTTAgentPublishParams
	Parameters passed to the MQTT_AGENT_Publish API. More...

Macros
#define	mqttagentURL_IS_IP_ADDRESS 0x00000001
	Flags for the MQTT agent connect params. More...

#define	mqttagentREQUIRE_TLS 0x00000002

#define	mqttagentUSE_AWS_IOT_ALPN_443 0x00000004

Typedefs
typedef void *	MQTTAgentHandle_t
	Opaque handle to represent an MQTT client. More...

typedef struct MQTTAgentCallbackParams	MQTTAgentCallbackParams_t
	Passed by the library in the callback to inform the user of various events. More...

typedef BaseType_t(*	MQTTAgentCallback_t) (void pvUserData, const MQTTAgentCallbackParams_t const pxCallbackParams)
	Signature of the callback registered by the user to get notified of various events. More...

typedef struct MQTTAgentConnectParams	MQTTAgentConnectParams_t
	Parameters passed to the MQTT_AGENT_Connect API.

typedef struct MQTTAgentSubscribeParams	MQTTAgentSubscribeParams_t
	Parameters passed to the MQTT_AGENT_Subscribe API.

typedef struct MQTTAgentUnsubscribeParams	MQTTAgentUnsubscribeParams_t
	Parameters passed to the MQTT_AGENT_Unsubscribe API.

typedef struct MQTTAgentPublishParams	MQTTAgentPublishParams_t
	Parameters passed to the MQTT_AGENT_Publish API.

Enumerations
enum	MQTTAgentReturnCode_t { eMQTTAgentSuccess, eMQTTAgentFailure, eMQTTAgentTimeout, eMQTTAgentAPICalledFromCallback }
	Return codes. More...

enum	MQTTAgentEvent_t { eMQTTAgentPublish, eMQTTAgentDisconnect }
	Various events reported by the library in the callback. More...

Functions
	lib_initDECLARE_LIB_INIT (MQTT_AGENT_Init)
	MQTT library Init function. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Create (MQTTAgentHandle_t *const pxMQTTHandle)
	Creates a new MQTT client. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Delete (MQTTAgentHandle_t xMQTTHandle)
	Deletes the already created MQTT client. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Connect (MQTTAgentHandle_t xMQTTHandle, const MQTTAgentConnectParams_t *const pxConnectParams, TickType_t xTimeoutTicks)
	Establishes a connection with the MQTT broker. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Disconnect (MQTTAgentHandle_t xMQTTHandle, TickType_t xTimeoutTicks)
	Disconnects the connection with the MQTT broker. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Subscribe (MQTTAgentHandle_t xMQTTHandle, const MQTTAgentSubscribeParams_t *const pxSubscribeParams, TickType_t xTimeoutTicks)
	Subscribes to a given topic. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Unsubscribe (MQTTAgentHandle_t xMQTTHandle, const MQTTAgentUnsubscribeParams_t *const pxUnsubscribeParams, TickType_t xTimeoutTicks)
	Unsubscribes from a given topic. More...

MQTTAgentReturnCode_t	MQTT_AGENT_Publish (MQTTAgentHandle_t xMQTTHandle, const MQTTAgentPublishParams_t *const pxPublishParams, TickType_t xTimeoutTicks)
	Publishes a message to a given topic. More...

MQTTAgentReturnCode_t	MQTT_AGENT_ReturnBuffer (MQTTAgentHandle_t xMQTTHandle, MQTTBufferHandle_t xBufferHandle)
	Returns the buffer provided in the publish callback. More...

Detailed Description

MQTT Agent Interface.

Definition in file aws_mqtt_agent.h.

Macro Definition Documentation

◆ mqttagentREQUIRE_TLS

#define mqttagentREQUIRE_TLS 0x00000002

Set this bit in xFlags to use TLS.

Definition at line 129 of file aws_mqtt_agent.h.

◆ mqttagentURL_IS_IP_ADDRESS

#define mqttagentURL_IS_IP_ADDRESS 0x00000001

Flags for the MQTT agent connect params.

Set this bit in xFlags if the provided URL is an IP address.

Definition at line 128 of file aws_mqtt_agent.h.

◆ mqttagentUSE_AWS_IOT_ALPN_443

#define mqttagentUSE_AWS_IOT_ALPN_443 0x00000004

Set this bit in xFlags to use AWS IoT support for MQTT over TLS port 443.

Definition at line 130 of file aws_mqtt_agent.h.

Typedef Documentation

◆ MQTTAgentCallback_t

typedef BaseType_t( * MQTTAgentCallback_t) (void *pvUserData, const MQTTAgentCallbackParams_t *const pxCallbackParams)

Signature of the callback registered by the user to get notified of various events.

The user can register an optional callback to get notified of various events.

Parameters

[in]	pvUserData	The user data as provided in the connect parameters while connecting.
[in]	pxCallbackParams	The event and related data.

Returns

The return value is ignored in all other cases except publish (i.e. eMQTTAgentPublish event):

If pdTRUE is returned - The ownership of the buffer passed in the callback (xBuffer in MQTTPublishData_t) lies with the user.
If pdFALSE is returned - The ownership of the buffer passed in the callback (xBuffer in MQTTPublishData_t) remains with the library and it is recycled as soon as the callback returns.
The user should take the ownership of the buffer containing the received message from the broker by returning pdTRUE from the callback if the user wants to use the buffer after the callback is over. The user should return the buffer whenever done by calling the MQTT_AGENT_ReturnBuffer API.

See also: MQTTAgentCallbackParams_t.

Definition at line 122 of file aws_mqtt_agent.h.

◆ MQTTAgentCallbackParams_t

typedef struct MQTTAgentCallbackParams MQTTAgentCallbackParams_t

Passed by the library in the callback to inform the user of various events.

If the user has registered a callback to get notified of various events, a pointer to this structure is passed in the callback function.

See also: MQTTAgentEvent_t.

◆ MQTTAgentHandle_t

typedef void* MQTTAgentHandle_t

Opaque handle to represent an MQTT client.

The MQTT library is capable of creating multiple MQTT clients, maximum number of which is controlled by mqttconfigMAX_BROKERS macro. Each client is identified by an opaque handle which is returned by the MQTT_AGENT_Create API call and later used in all the subsequent API calls.

Definition at line 52 of file aws_mqtt_agent.h.

Enumeration Type Documentation

◆ MQTTAgentEvent_t

enum MQTTAgentEvent_t

Various events reported by the library in the callback.

The user can register an optional callback with the MQTT library to get notified of various events including Publish messages received from the broker. This enum identifies the event received in the callback.

Enumerator
eMQTTAgentPublish	A Publish message was received from the broker.
eMQTTAgentDisconnect	The connection to the broker got disconnected.

Definition at line 77 of file aws_mqtt_agent.h.

◆ MQTTAgentReturnCode_t

enum MQTTAgentReturnCode_t

Return codes.

Each API returns a value of this type.

Enumerator
eMQTTAgentSuccess	The operation was successful.
eMQTTAgentFailure	The operation failed.
eMQTTAgentTimeout	The operation timed out.
eMQTTAgentAPICalledFromCallback	The MQTT agent APIs must not be called from MQTT callbacks as callbacks run in the context of MQTT agent task and therefore can result in deadlock. This error code is returned if any MQTT agent API is invoked from any callback.

Definition at line 59 of file aws_mqtt_agent.h.

Function Documentation

◆ lib_initDECLARE_LIB_INIT()

lib_initDECLARE_LIB_INIT ( MQTT_AGENT_Init )

MQTT library Init function.

This function does general initialization and setup. It must be called once and only once before calling any other function.

Returns: pdPASS if everything succeeds, pdFAIL otherwise.

◆ MQTT_AGENT_Connect()

MQTTAgentReturnCode_t MQTT_AGENT_Connect	(	MQTTAgentHandle_t	xMQTTHandle,
		const MQTTAgentConnectParams_t *const	pxConnectParams,
		TickType_t	xTimeoutTicks
	)

Establishes a connection with the MQTT broker.

Note: This function alters the calling task's notification state and value. If xTimeoutTicks is short the calling task's notification state and value may be updated after MQTT_AGENT_Connect() has returned.

Parameters

[in]	xMQTTHandle	The opaque handle as returned from MQTT_AGENT_Create.
[in]	pxConnectParams	Connect parameters.
[in]	xTimeoutTicks	Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS macro to convert milliseconds to ticks.

Returns: eMQTTAgentSuccess if the connect operation succeeds, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_Create()

MQTTAgentReturnCode_t MQTT_AGENT_Create ( MQTTAgentHandle_t *const pxMQTTHandle )

Creates a new MQTT client.

The MQTT library is capable of creating multiple MQTT clients, maximum number of which is controlled by mqttconfigMAX_BROKERS macro. If mqttconfigMAX_BROKERS clients are already in use, this function will fail immediately. Otherwise a new client is setup and the handle to the created client is returned in the pxMQTTHandle parameter which should be used in all the subsequent API calls. Note that the returned handled is only valid if the return value of the API is eMQTTAgentSuccess.

Parameters

[out] pxMQTTHandle Output parameter to return the opaque client handle.

Returns: eMQTTAgentSuccess if a new client is successfully created, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_Delete()

MQTTAgentReturnCode_t MQTT_AGENT_Delete ( MQTTAgentHandle_t xMQTTHandle )

Deletes the already created MQTT client.

This function just frees up the internal resources and does not disconnect. The user must call MQTT_AGENT_Disconnect API to make sure that the client is disconnected before deleting it.

Parameters

[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.

Returns: eMQTTAgentSuccess if the client is successfully deleted, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_Disconnect()

MQTTAgentReturnCode_t MQTT_AGENT_Disconnect	(	MQTTAgentHandle_t	xMQTTHandle,
		TickType_t	xTimeoutTicks
	)

Disconnects the connection with the MQTT broker.

Note: This function alters the calling task's notification state and value. If xTimeoutTicks is short the calling task's notification state and value may be updated after MQTT_AGENT_Disconnect() has returned.

Parameters

[in]	xMQTTHandle	The opaque handle as returned from MQTT_AGENT_Create.
[in]	xTimeoutTicks	Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS macro to convert milliseconds to ticks.

Returns: eMQTTAgentSuccess if the disconnect operation succeeds, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_Publish()

MQTTAgentReturnCode_t MQTT_AGENT_Publish	(	MQTTAgentHandle_t	xMQTTHandle,
		const MQTTAgentPublishParams_t *const	pxPublishParams,
		TickType_t	xTimeoutTicks
	)

Publishes a message to a given topic.

Note: This function alters the calling task's notification state and value. If xTimeoutTicks is short the calling task's notification state and value may be updated after MQTT_AGENT_Publish() has returned.

Parameters

[in]	xMQTTHandle	The opaque handle as returned from MQTT_AGENT_Create.
[in]	pxPublishParams	Publish parameters.
[in]	xTimeoutTicks	Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS macro to convert milliseconds to ticks.

Returns: eMQTTAgentSuccess if the publish operation succeeds, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_ReturnBuffer()

MQTTAgentReturnCode_t MQTT_AGENT_ReturnBuffer	(	MQTTAgentHandle_t	xMQTTHandle,
		MQTTBufferHandle_t	xBufferHandle
	)

Returns the buffer provided in the publish callback.

When a publish message is received from the broker, the buffer containing the message is returned in the user supplied callback (xBuffer in MQTTPublishData_t) and the user can take the ownership by returning pdTRUE from the callback. The user should later return the buffer whenever done by calling the MQTT_AGENT_ReturnBuffer API.

Parameters

[in]	xMQTTHandle	The opaque handle as returned from MQTT_AGENT_Create.
[in]	xBufferHandle	The buffer to return.

Returns: eMQTTAgentSuccess if the return buffer operation succeeds, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_Subscribe()

MQTTAgentReturnCode_t MQTT_AGENT_Subscribe	(	MQTTAgentHandle_t	xMQTTHandle,
		const MQTTAgentSubscribeParams_t *const	pxSubscribeParams,
		TickType_t	xTimeoutTicks
	)

Subscribes to a given topic.

Note: This function alters the calling task's notification state and value. If xTimeoutTicks is short the calling task's notification state and value may be updated after MQTT_AGENT_Subscribe() has returned.

Whenever a publish message is received on a topic, the registered callbacks are invoked in the following order:

If we have an exact matching entry in the subscription manager, the corresponding callback is invoked.
Then the wild card topic filters are checked for match and the corresponding callbacks are invoked for the ones which match the topic.

Note: If a publish message is received on a topic which matches more than one topic filters, the order in which the registered callbacks are invoked is undefined.

Warning

If the user takes the ownership of the MQTT buffer by returning eMQTTTrue from the callback, no further callbacks are invoked. The user should make sure not to take the ownership of the MQTT buffer if they want all the callbacks to get invoked. For example:

Subscriptions: a/b/c, a/b/#, a/b/+
Publish message received on topic: a/b/c –> First the callback corresponding to a/b/c subscription is invoked. Then the callbacks for topic filters a/b/# and a/b/+ are invoked in no particular order. If the user decides to take the ownership of the MQTT buffer in any of the callback by returning eMQTTTrue, no further callbacks are invoked.

Parameters

[in]	xMQTTHandle	The opaque handle as returned from MQTT_AGENT_Create.
[in]	pxSubscribeParams	Subscribe parameters.
[in]	xTimeoutTicks	Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS macro to convert milliseconds to ticks.

Returns: eMQTTAgentSuccess if the subscribe operation succeeds, otherwise an error code explaining the reason of the failure is returned.

◆ MQTT_AGENT_Unsubscribe()

MQTTAgentReturnCode_t MQTT_AGENT_Unsubscribe	(	MQTTAgentHandle_t	xMQTTHandle,
		const MQTTAgentUnsubscribeParams_t *const	pxUnsubscribeParams,
		TickType_t	xTimeoutTicks
	)

Unsubscribes from a given topic.

Note: This function alters the calling task's notification state and value. If xTimeoutTicks is short the calling task's notification state and value may be updated after MQTT_AGENT_Unsubscribe() has returned.

Parameters

[in]	xMQTTHandle	The opaque handle as returned from MQTT_AGENT_Create.
[in]	pxUnsubscribeParams	Unsubscribe parameters.
[in]	xTimeoutTicks	Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS macro to convert milliseconds to ticks.

Returns: eMQTTAgentSuccess if the unsubscribe operation succeeds, otherwise an error code explaining the reason of the failure is returned.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ mqttagentREQUIRE_TLS

◆ mqttagentURL_IS_IP_ADDRESS

◆ mqttagentUSE_AWS_IOT_ALPN_443

Typedef Documentation

◆ MQTTAgentCallback_t

◆ MQTTAgentCallbackParams_t

◆ MQTTAgentHandle_t

Enumeration Type Documentation

◆ MQTTAgentEvent_t

◆ MQTTAgentReturnCode_t

Function Documentation

◆ lib_initDECLARE_LIB_INIT()

◆ MQTT_AGENT_Connect()

◆ MQTT_AGENT_Create()

◆ MQTT_AGENT_Delete()

◆ MQTT_AGENT_Disconnect()

◆ MQTT_AGENT_Publish()

◆ MQTT_AGENT_ReturnBuffer()

◆ MQTT_AGENT_Subscribe()

◆ MQTT_AGENT_Unsubscribe()