MQTT Core Library interface. More...

#include "aws_mqtt_config.h"
#include "aws_mqtt_config_defaults.h"
#include "aws_mqtt_buffer.h"

Data Structures
struct	MQTTConnACKData
	The data sent by the MQTT library in the user supplied callback when a CONNACK message is received. More...

struct	MQTTSubACKData
	The data sent by the MQTT library in the user supplied callback when a SUBACK message is received. More...

struct	MQTTUnSubACKData
	The data sent by the MQTT library in the user supplied callback when an UNSUBACK message is received. More...

struct	MQTTPubACKData
	The data sent by the MQTT library in the user supplied callback when a PUBACK message is received. More...

struct	MQTTPublishData
	The data sent by the MQTT library in the user supplied callback when a publish message from the broker is received. More...

struct	MQTTTimeoutData
	The data sent by the MQTT library in the user supplied callback when an operation times out. More...

struct	MQTTDisconnectData
	The data sent by the MQTT library in the user supplied callback when the client is disconnected. More...

struct	MQTTCallbackParams
	The parameters sent by the MQTT library in the user supplied callback. More...

struct	MQTTBufferPoolInterface
	Represents a subscription entry in the subscription manager. More...

struct	MQTTRxMessageState
	Represents the state of the message currently being received. More...

struct	MQTTContext
	Represents one connection to an MQTT broker. More...

struct	MQTTInitParams
	MQTT Init Parameters. More...

struct	MQTTConnectParams
	MQTT Connect Parameters. More...

struct	MQTTSubscribeParams
	MQTT Subscribe Parameters. More...

struct	MQTTUnsubscribeParams
	MQTT Unsubscribe Parameters. More...

struct	MQTTPublishParams
	MQTT Publish Parameters. More...

Macros
#define	mqttREMAINING_LENGTH_MAX_BYTES 4

#define	mqttREMAINING_LENGTH_MIN_BYTES 1

#define	mqttFIXED_HEADER_MAX_SIZE ( 1 + mqttREMAINING_LENGTH_MAX_BYTES )

#define	mqttFIXED_HEADER_MIN_SIZE ( 1 + mqttREMAINING_LENGTH_MIN_BYTES )

Typedefs
typedef struct MQTTConnACKData	MQTTConnACKData_t
	The data sent by the MQTT library in the user supplied callback when a CONNACK message is received.

typedef struct MQTTSubACKData	MQTTSubACKData_t
	The data sent by the MQTT library in the user supplied callback when a SUBACK message is received.

typedef struct MQTTUnSubACKData	MQTTUnSubACKData_t
	The data sent by the MQTT library in the user supplied callback when an UNSUBACK message is received.

typedef struct MQTTPubACKData	MQTTPubACKData_t
	The data sent by the MQTT library in the user supplied callback when a PUBACK message is received.

typedef struct MQTTPublishData	MQTTPublishData_t
	The data sent by the MQTT library in the user supplied callback when a publish message from the broker is received.

typedef struct MQTTTimeoutData	MQTTTimeoutData_t
	The data sent by the MQTT library in the user supplied callback when an operation times out.

typedef struct MQTTDisconnectData	MQTTDisconnectData_t
	The data sent by the MQTT library in the user supplied callback when the client is disconnected.

typedef struct MQTTCallbackParams	MQTTEventCallbackParams_t
	The parameters sent by the MQTT library in the user supplied callback.

typedef MQTTBool_t(*	MQTTEventCallback_t) (void pvCallbackContext, const MQTTEventCallbackParams_t const pxParams)
	Signature of the user supplied callback to get notified of various events. More...

typedef uint32_t(*	MQTTSend_t) (void pvSendContext, const uint8_t const pucData, uint32_t ulDataLength)
	Signature of the user supplied topic specific publish callback which gets called whenever a publish message is received on the topic this callback is registered for. More...

typedef void(*	MQTTGetTicks_t) (uint64_t *pxCurrentTickCount)
	Signature of the callback to get the current tick count. More...

typedef uint8_t (	MQTTGetFreeBuffer_t) (uint32_t *pulBufferLength)
	Signature of the callback supplied by the user as part of MQTTBufferPoolInterface_t to get a free buffer. More...

typedef void(*	MQTTReturnBuffer_t) (uint8_t *pucBuffer)
	Signature of the callback supplied by the user as part of MQTTBufferPoolInterface_t to return the buffer obtained using MQTTGetFreeBuffer_t. More...

typedef struct MQTTBufferPoolInterface	MQTTBufferPoolInterface_t
	Represents a subscription entry in the subscription manager. More...

typedef struct MQTTRxMessageState	MQTTRxMessageState_t
	Represents the state of the message currently being received.

typedef struct MQTTContext	MQTTContext_t
	Represents one connection to an MQTT broker. More...

typedef struct MQTTInitParams	MQTTInitParams_t
	MQTT Init Parameters. More...

typedef struct MQTTConnectParams	MQTTConnectParams_t
	MQTT Connect Parameters. More...

typedef struct MQTTSubscribeParams	MQTTSubscribeParams_t
	MQTT Subscribe Parameters. More...

typedef struct MQTTUnsubscribeParams	MQTTUnsubscribeParams_t
	MQTT Unsubscribe Parameters. More...

typedef struct MQTTPublishParams	MQTTPublishParams_t
	MQTT Publish Parameters. More...

Enumerations
enum	MQTTBool_t { eMQTTFalse = 0, eMQTTTrue = 1 }
	Boolean type. More...

enum	MQTTReturnCode_t { eMQTTSuccess = 0, eMQTTFailure, eMQTTClientAlreadyConnected, eMQTTClientConnectionInProgress, eMQTTClientNotConnected, eMQTTNoFreeBuffer, eMQTTSendFailed, eMQTTMalformedPacketReceived, eMQTTSubscriptionManagerFull }
	Return codes from various APIs. More...

enum	MQTTRxNextByte_t { eMQTTRxNextBytePacketType, eMQTTRxNextBytePacketLength, eMQTTRxNextByteMessage }
	The next expected byte. More...

enum	MQTTRxMessageAction_t { eMQTTRxMessageStore, eMQTTRxMessageDrop }
	The action taken on the message being received. More...

enum	MQTTEventType_t { eMQTTPublish, eMQTTConnACK, eMQTTUnexpectedConnACK, eMQTTPubACK, eMQTTUnexpectedPubACK, eMQTTSubACK, eMQTTUnexpectedSubACK, eMQTTUnSubACK, eMQTTUnexpectedUnSubACK, eMQTTClientDisconnected, eMQTTPacketDropped, eMQTTTimeout, eMQTTPingTimeout }
	Various events reported by the library in the user supplied callback. More...

enum	MQTTDisconnectReason_t { eMQTTDisconnectReasonMalformedPacket, eMQTTDisconnectReasonBrokerRefusedConnection, eMQTTDisconnectReasonUserRequest, eMQTTDisconnectReasonConnectTimeout }
	The reason of disconnect. More...

enum	MQTTQoS_t { eMQTTQoS0 = 0, eMQTTQoS1 = 1, eMQTTQoS2 = 2 }
	Quality of Service (QoS). More...

enum	MQTTConnectionState_t { eMQTTNotConnected, eMQTTConnectionInProgress, eMQTTConnected }
	The connection state. More...

enum	MQTTConnACKReturnCode_t { eMQTTConnACKConnectionAccepted = 0, eMQTTConnACKUnacceptableProtocolVersion = 1, eMQTTConnACKIdentifierRejected = 2, eMQTTConnACKServerUnavailable = 3, eMQTTConnACKBadUsernameOrPassword = 4, eMQTTConnACKUnauthorized = 5 }
	Return codes sent by the broker in the CONNACK message. More...

enum	MQTTSubACKReturnCode_t { eMQTTSubACKSuccessQos0 = 0, eMQTTSubACKSuccessQos1 = 1, eMQTTSubACKSuccessQos2 = 2, eMQTTSubACKFailure = 128 }
	Return codes sent by the broker in the SUBACK message. More...

enum	MQTTTopicFilterType_t { eMQTTTopicFilterTypeInvalid = 0, eMQTTTopicFilterTypeSimple, eMQTTTopicFilterTypeWildCard }
	Represents the type of the topic filter. More...

Functions
MQTTReturnCode_t	MQTT_Init (MQTTContext_t pxMQTTContext, const MQTTInitParams_t const pxInitParams)
	Initializes the given MQTT Context. More...

MQTTReturnCode_t	MQTT_Connect (MQTTContext_t pxMQTTContext, const MQTTConnectParams_t const pxConnectParams)
	Initiates the Connect operation. More...

MQTTReturnCode_t	MQTT_Disconnect (MQTTContext_t *pxMQTTContext)
	Disconnects the connection to the broker. More...

MQTTReturnCode_t	MQTT_Subscribe (MQTTContext_t pxMQTTContext, const MQTTSubscribeParams_t const pxSubscribeParams)
	Initiates the Subscribe operation. More...

MQTTReturnCode_t	MQTT_Unsubscribe (MQTTContext_t pxMQTTContext, const MQTTUnsubscribeParams_t const pxUnsubscribeParams)
	Initiates the Unsubscribe operation. More...

MQTTReturnCode_t	MQTT_Publish (MQTTContext_t pxMQTTContext, const MQTTPublishParams_t const pxPublishParams)
	Initiates the Publish operation. More...

MQTTReturnCode_t	MQTT_ParseReceivedData (MQTTContext_t pxMQTTContext, const uint8_t pucReceivedData, size_t xReceivedDataLength)
	Decodes the incoming messages. More...

MQTTReturnCode_t	MQTT_ReturnBuffer (MQTTContext_t *pxMQTTContext, MQTTBufferHandle_t xBufferHandle)
	Returns the buffer provided in the publish callback. More...

uint32_t	MQTT_Periodic (MQTTContext_t *pxMQTTContext, uint64_t xCurrentTickCount)
	Manages timeout and keep alive messages. More...

Detailed Description

MQTT Core Library interface.

Definition in file aws_mqtt_lib.h.

Typedef Documentation

◆ MQTTBufferPoolInterface_t

typedef struct MQTTBufferPoolInterface MQTTBufferPoolInterface_t

Represents a subscription entry in the subscription manager.

The subscription manager used to keep track of user subscriptions and topic specific callbacks. The buffer pool interface supplied by the user.

The library uses this interface to get a buffer from the pool of free buffers and return it back to the pool whenever done.

◆ MQTTConnectParams_t

typedef struct MQTTConnectParams MQTTConnectParams_t

MQTT Connect Parameters.

Parameters passed to the MQTT_Connect API.

◆ MQTTContext_t

typedef struct MQTTContext MQTTContext_t

Represents one connection to an MQTT broker.

A context should be initialized using MQTT_Init before it can be used in the subsequent function calls.

◆ MQTTEventCallback_t

typedef MQTTBool_t( * MQTTEventCallback_t) (void *pvCallbackContext, const MQTTEventCallbackParams_t *const pxParams)

Signature of the user supplied callback to get notified of various events.

The user registers this optional callback to get notified of the various events including publish messages received from the broker.

Parameters

[in]	pvCallbackContext	The callback context as supplied by the user in Init parameters.
[in]	pxParams	The event and related data.

Returns

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

If eMQTTTrue is returned - the ownership of the buffer passed in the callback (xBuffer in MQTTPublishData_t) lies with the user.
If eMQTTFalse 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 eMQTTTrue 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_ReturnBuffer API.

Definition at line 322 of file aws_mqtt_lib.h.

◆ MQTTGetFreeBuffer_t

typedef uint8_t*( * MQTTGetFreeBuffer_t) (uint32_t *pulBufferLength)

Signature of the callback supplied by the user as part of MQTTBufferPoolInterface_t to get a free buffer.

The user must register this callback so that the library can obtain a buffer whenever needed. It is okay for the callback to return a buffer larger than the requested length and pulBufferLength must always be updated to the actual length of the returned buffer.

Parameters

[in,out] pulBufferLength The library sets it to the desired length of the buffer. It must be updated to the actual length of the returned buffer.

Returns: The pointer to the buffer if one is available, NULL otherwise.

Definition at line 399 of file aws_mqtt_lib.h.

◆ MQTTGetTicks_t

typedef void( * MQTTGetTicks_t) (uint64_t *pxCurrentTickCount)

Signature of the callback to get the current tick count.

This callback is optional but registering this callback provides more accurate timeout processing. If the user chooses not to register this callback, each timeout processing starts from the moment of next invocation of MQTT_Periodic.

Parameters

[out] pxCurrentTickCount The output parameter to receive the current tick count.

Definition at line 381 of file aws_mqtt_lib.h.

◆ MQTTInitParams_t

typedef struct MQTTInitParams MQTTInitParams_t

MQTT Init Parameters.

Parameters passed to the MQTT_Init API.

◆ MQTTPublishParams_t

typedef struct MQTTPublishParams MQTTPublishParams_t

MQTT Publish Parameters.

Parameters passed to the MQTT_Publish API.

◆ MQTTReturnBuffer_t

typedef void( * MQTTReturnBuffer_t) (uint8_t *pucBuffer)

Signature of the callback supplied by the user as part of MQTTBufferPoolInterface_t to return the buffer obtained using MQTTGetFreeBuffer_t.

The user must register this callback so that the library can return the buffer whenever done.

Parameters

[in] pucBuffer The buffer to return.

Definition at line 411 of file aws_mqtt_lib.h.

◆ MQTTSend_t

typedef uint32_t( * MQTTSend_t) (void *pvSendContext, const uint8_t *const pucData, uint32_t ulDataLength)

Signature of the user supplied topic specific publish callback which gets called whenever a publish message is received on the topic this callback is registered for.

The user can choose to register this optional topic specific callback while subscribing to a topic. Whenever a publish message is received on the topic, this callback is invoked. If the user chooses not to enable subscription management or chooses not to register a topic specific callback, the generic callback supplied during Init is invoked.

Parameters

[in]	pvPublishCallbackContext	The callback context as supplied by the user in the subscribe parameters.
[in]	pxPublishData	The publish data.

Returns

The return value is interpreted as follows:

If eMQTTTrue is returned - the ownership of the buffer passed in the callback (xBuffer in MQTTPublishData_t) lies with the user.
If eMQTTFalse 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 eMQTTTrue 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_ReturnBuffer API. Signature of the user supplied callback to transmit data.

The user must register this callback so that the library can transmit the data including keep alive messages when it has to.

Parameters

[in]	pvSendContext	The send context as supplied by the user in Init parameters.
[in]	pucData	The data to transmit.
[in]	ulDataLength	The length of the data.

Returns: The number of bytes actually transmitted.

Definition at line 368 of file aws_mqtt_lib.h.

◆ MQTTSubscribeParams_t

typedef struct MQTTSubscribeParams MQTTSubscribeParams_t

MQTT Subscribe Parameters.

Parameters passed to the MQTT_Subscribe API.

◆ MQTTUnsubscribeParams_t

typedef struct MQTTUnsubscribeParams MQTTUnsubscribeParams_t

MQTT Unsubscribe Parameters.

Parameters passed to the MQTT_Unsubscribe API.

Enumeration Type Documentation

◆ MQTTBool_t

enum MQTTBool_t

Boolean type.

Enumerator
eMQTTFalse	Boolean False.
eMQTTTrue	Boolean True.

Definition at line 65 of file aws_mqtt_lib.h.

◆ MQTTConnACKReturnCode_t

enum MQTTConnACKReturnCode_t

Return codes sent by the broker in the CONNACK message.

The values in the following enum exactly correspond to the ones received in the CONNACK packet and must not be changed.

Enumerator
eMQTTConnACKConnectionAccepted	Connection accepted by the broker.
eMQTTConnACKUnacceptableProtocolVersion	Broker does not support the requested protocol version.
eMQTTConnACKIdentifierRejected	Packet identifier rejected.
eMQTTConnACKServerUnavailable	Broker unavailable.
eMQTTConnACKBadUsernameOrPassword	Bad username or password.
eMQTTConnACKUnauthorized	Unauthorized.

Definition at line 176 of file aws_mqtt_lib.h.

◆ MQTTConnectionState_t

enum MQTTConnectionState_t

The connection state.

Enumerator
eMQTTNotConnected	Not connected.
eMQTTConnectionInProgress	Connect has been sent and waiting for CONNACK.
eMQTTConnected	Connected.

Definition at line 163 of file aws_mqtt_lib.h.

◆ MQTTDisconnectReason_t

enum MQTTDisconnectReason_t

The reason of disconnect.

Whenever the client is disconnected, the library sends the reason of disconnect in the user supplied callback.

Enumerator
eMQTTDisconnectReasonMalformedPacket	The client was disconnected because a malformed packet was received.
eMQTTDisconnectReasonBrokerRefusedConnection	The client was disconnected because broker refused the connection request.
eMQTTDisconnectReasonUserRequest	The client was disconnected on user request.
eMQTTDisconnectReasonConnectTimeout	The client was disconnected because an expected CONNACK was not received.

Definition at line 142 of file aws_mqtt_lib.h.

◆ MQTTEventType_t

enum MQTTEventType_t

Various events reported by the library in the user supplied callback.

The user can register an optional callback with the library to get notified of various events. One of the callback parameter is of type MQTTEventType_t and specifies the event.

Enumerator
eMQTTPublish	Publish message received from the broker.
eMQTTConnACK	CONNACK received.
eMQTTUnexpectedConnACK	Unexpected CONNACK received.
eMQTTPubACK	PUBACK received.
eMQTTUnexpectedPubACK	Unexpected PUBACK received.
eMQTTSubACK	SUBACK received.
eMQTTUnexpectedSubACK	Unexpected SUBACK received.
eMQTTUnSubACK	UNSUBACK received.
eMQTTUnexpectedUnSubACK	Unexpected UNSUBACK received.
eMQTTClientDisconnected	Client has been disconnected. The user must re-connect before carrying out any other operation.
eMQTTPacketDropped	A packet was dropped because a large enough buffer was not available to store it.
eMQTTTimeout	Timeout detected - An expected ACK was not received within the specified time.
eMQTTPingTimeout	A PINGRESP was not received within the expected time.

Definition at line 119 of file aws_mqtt_lib.h.

◆ MQTTQoS_t

enum MQTTQoS_t

Quality of Service (QoS).

Enumerator
eMQTTQoS0	Quality of Service 0 - Fire and Forget. No ACK.
eMQTTQoS1	Quality of Service 1 - Wait till ACK or Timeout.
eMQTTQoS2	Quality of Service 2 - Not supported.

Definition at line 153 of file aws_mqtt_lib.h.

◆ MQTTReturnCode_t

enum MQTTReturnCode_t

Return codes from various APIs.

Enumerator
eMQTTSuccess	The operation was successful.
eMQTTFailure	The operation failed.
eMQTTClientAlreadyConnected	Connection attempt while the client is already connected.
eMQTTClientConnectionInProgress	Connection attempt while connection is already in progress.
eMQTTClientNotConnected	Client is not connected.
eMQTTNoFreeBuffer	No free buffer is available for the operation.
eMQTTSendFailed	The registered send callback failed to transmit data.
eMQTTMalformedPacketReceived	A malformed packet was received. Client has been disconnected. The user must re-connect before carrying out any other operation.
eMQTTSubscriptionManagerFull	No space left in subscription manager to store any more subscriptions.

Definition at line 74 of file aws_mqtt_lib.h.

◆ MQTTRxMessageAction_t

enum MQTTRxMessageAction_t

The action taken on the message being received.

If a large enough buffer is available to store the message, it is stored, otherwise it is dropped.

Enumerator
eMQTTRxMessageStore	The message being received is being stored.
eMQTTRxMessageDrop	The message being received is being dropped.

Definition at line 106 of file aws_mqtt_lib.h.

◆ MQTTRxNextByte_t

enum MQTTRxNextByte_t

The next expected byte.

This enum helps in keeping track of the next expected byte in order to decode the incoming bytes.

Enumerator
eMQTTRxNextBytePacketType	Next received byte will be the first byte of fixed header containing packet type and related flags.
eMQTTRxNextBytePacketLength	Next received bytes will contain the encoded "Remaining Length".
eMQTTRxNextByteMessage	The fixed header has been received, now receiving the rest of the message.

Definition at line 93 of file aws_mqtt_lib.h.

◆ MQTTSubACKReturnCode_t

enum MQTTSubACKReturnCode_t

Return codes sent by the broker in the SUBACK message.

The values in the following enum exactly correspond to the ones received in the SUBACK packet and must not be changed.

Enumerator
eMQTTSubACKSuccessQos0	Subscription accepted. Granted QoS0.
eMQTTSubACKSuccessQos1	Subscription accepted. Granted QoS1.
eMQTTSubACKSuccessQos2	Subscription accepted. Granted QoS2.
eMQTTSubACKFailure	Subscription rejected.

Definition at line 192 of file aws_mqtt_lib.h.

◆ MQTTTopicFilterType_t

enum MQTTTopicFilterType_t

Represents the type of the topic filter.

Enumerator
eMQTTTopicFilterTypeInvalid	The topic filter is invalid.
eMQTTTopicFilterTypeSimple	The topic filter does not contain any wild cards.
eMQTTTopicFilterTypeWildCard	The topic filter contains wild cards.

Definition at line 203 of file aws_mqtt_lib.h.

Function Documentation

◆ MQTT_Connect()

MQTTReturnCode_t MQTT_Connect	(	MQTTContext_t *	pxMQTTContext,
		const MQTTConnectParams_t *const	pxConnectParams
	)

Initiates the Connect operation.

Prepares and transmits an MQTT connect message and puts the packet on the waiting ACK list which is removed when the corresponding CONNACK is received or the operation times out.

Parameters

[in]	pxMQTTContext	The initialized MQTT context.
[in]	pxConnectParams	Connect parameters.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_Disconnect()

MQTTReturnCode_t MQTT_Disconnect ( MQTTContext_t * pxMQTTContext )

Disconnects the connection to the broker.

Prepares and transmits an MQTT disconnect message and resets the internal state. It invokes the user supplied callback to inform about the disconnect and passes all the user supplied buffers in the callback. The user can choose to take the ownership of all the buffers by returning eMQTTTrue from the callback.

Parameters

[in] pxMQTTContext The initialized MQTT context.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_Init()

MQTTReturnCode_t MQTT_Init	(	MQTTContext_t *	pxMQTTContext,
		const MQTTInitParams_t *const	pxInitParams
	)

Initializes the given MQTT Context.

MQTT context must be initialized first using this API before passing it to the subsequent API calls.

Parameters

[in]	pxMQTTContext	The context to initialize.
[in]	pxInitParams	Init parameters.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_ParseReceivedData()

MQTTReturnCode_t MQTT_ParseReceivedData	(	MQTTContext_t *	pxMQTTContext,
		const uint8_t *	pucReceivedData,
		size_t	xReceivedDataLength
	)

Decodes the incoming messages.

User provides the incoming bytes by calling this API which are buffered until a complete MQTT message has been received after which the user supplied callback is invoked to inform about the received message.

Parameters

[in]	pxMQTTContext	The initialized MQTT context.
[in]	pucReceivedData	Received bytes.
[in]	xReceivedDataLength	Number of received bytes.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_Periodic()

uint32_t MQTT_Periodic	(	MQTTContext_t *	pxMQTTContext,
		uint64_t	xCurrentTickCount
	)

Manages timeout and keep alive messages.

Iterates the pending ACK list and checks if any of them has expired in which case the user supplied callback is invoked to inform about the timeout. Also, checks if sufficient time has passed since the last transmitted a packet and transmits a keep alive (PINGREQ) message accordingly.

Parameters

[in]	pxMQTTContext	The initialized MQTT context.
[in]	xCurrentTickCount	The current tick count value.

Returns: The time interval in ticks after which this function should be called again.

◆ MQTT_Publish()

MQTTReturnCode_t MQTT_Publish	(	MQTTContext_t *	pxMQTTContext,
		const MQTTPublishParams_t *const	pxPublishParams
	)

Initiates the Publish operation.

Prepares and transmits an MQTT publish message. In non QoS0 case, puts the packet on the waiting ACK list which is removed when the corresponding PUBACK is received or the operation times out.

Parameters

[in]	pxMQTTContext	The initialized MQTT context.
[in]	pxPublishParams	Publish parameters.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_ReturnBuffer()

MQTTReturnCode_t MQTT_ReturnBuffer	(	MQTTContext_t *	pxMQTTContext,
		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 eMQTTTrue from the callback. The user should later return the buffer whenever done by calling the MQTT_ReturnBuffer API.

Parameters

[in]	pxMQTTContext	The initialized MQTT context.
[in]	xBufferHandle	The buffer to return.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_Subscribe()

MQTTReturnCode_t MQTT_Subscribe	(	MQTTContext_t *	pxMQTTContext,
		const MQTTSubscribeParams_t *const	pxSubscribeParams
	)

Initiates the Subscribe operation.

Prepares and transmits an MQTT subscribe message and puts the packet on the waiting ACK list which is removed when the corresponding SUBACK is received or the operation times out.

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]	pxMQTTContext	The initialized MQTT context.
[in]	pxSubscribeParams	Subscribe parameters.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

◆ MQTT_Unsubscribe()

MQTTReturnCode_t MQTT_Unsubscribe	(	MQTTContext_t *	pxMQTTContext,
		const MQTTUnsubscribeParams_t *const	pxUnsubscribeParams
	)

Initiates the Unsubscribe operation.

Prepares and transmits an MQTT unsubscribe message and puts the packet on the waiting ACK list which is removed when the corresponding UNSUBACK is received or the operation times out.

Parameters

[in]	pxMQTTContext	The initialized MQTT context.
[in]	pxUnsubscribeParams	Unsubscribe parameters.

Returns: eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MQTTBufferPoolInterface_t

◆ MQTTConnectParams_t

◆ MQTTContext_t

◆ MQTTEventCallback_t

◆ MQTTGetFreeBuffer_t

◆ MQTTGetTicks_t

◆ MQTTInitParams_t

◆ MQTTPublishParams_t

◆ MQTTReturnBuffer_t

◆ MQTTSend_t

◆ MQTTSubscribeParams_t

◆ MQTTUnsubscribeParams_t

Enumeration Type Documentation

◆ MQTTBool_t

◆ MQTTConnACKReturnCode_t

◆ MQTTConnectionState_t

◆ MQTTDisconnectReason_t

◆ MQTTEventType_t

◆ MQTTQoS_t

◆ MQTTReturnCode_t

◆ MQTTRxMessageAction_t

◆ MQTTRxNextByte_t

◆ MQTTSubACKReturnCode_t

◆ MQTTTopicFilterType_t

Function Documentation

◆ MQTT_Connect()

◆ MQTT_Disconnect()

◆ MQTT_Init()

◆ MQTT_ParseReceivedData()

◆ MQTT_Periodic()

◆ MQTT_Publish()

◆ MQTT_ReturnBuffer()

◆ MQTT_Subscribe()

◆ MQTT_Unsubscribe()