738 lines
35 KiB
C
Executable File
738 lines
35 KiB
C
Executable File
/*
|
|
* Amazon FreeRTOS
|
|
* Copyright (C) 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
* this software and associated documentation files (the "Software"), to deal in
|
|
* the Software without restriction, including without limitation the rights to
|
|
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|
* the Software, and to permit persons to whom the Software is furnished to do so,
|
|
* subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in all
|
|
* copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
*
|
|
* http://aws.amazon.com/freertos
|
|
* http://www.FreeRTOS.org
|
|
*/
|
|
|
|
|
|
/**
|
|
* @file aws_mqtt_lib.h
|
|
* @brief MQTT Core Library interface.
|
|
*/
|
|
|
|
#ifndef _AWS_MQTT_LIB_H_
|
|
#define _AWS_MQTT_LIB_H_
|
|
|
|
/* This ifndef enables the core MQTT library to be used without
|
|
* providing MQTTConfig.h. All the config values in this case are
|
|
* taken from MQTTConfigDefaults.h. */
|
|
#ifndef mqttDO_NOT_USE_CUSTOM_CONFIG
|
|
#include "aws_mqtt_config.h"
|
|
#endif
|
|
#include "aws_mqtt_config_defaults.h"
|
|
|
|
/* MQTT buffer includes. */
|
|
#include "aws_mqtt_buffer.h"
|
|
|
|
/**
|
|
* @defgroup FixedHeaderSize Macros to define MQTT fixed header size.
|
|
*
|
|
* Each MQTT message starts with a fixed header. The first byte contains the
|
|
* message type and related flags. The next 1-4 bytes contain the length of
|
|
* the packet excluding the length of fixed header (namely "Remaining Length").
|
|
* "Remaining Length" field can span up to 4 bytes, so the maximum length of
|
|
* MQTT fixed header can be 5 bytes and minimum length can be 2 bytes.
|
|
*/
|
|
/** @{ */
|
|
#define mqttREMAINING_LENGTH_MAX_BYTES 4 /**< Remaining Length field can span maximum 4 bytes. */
|
|
#define mqttREMAINING_LENGTH_MIN_BYTES 1 /**< Remaining Length field must be of at least 1 byte. */
|
|
#define mqttFIXED_HEADER_MAX_SIZE ( 1 + mqttREMAINING_LENGTH_MAX_BYTES )
|
|
#define mqttFIXED_HEADER_MIN_SIZE ( 1 + mqttREMAINING_LENGTH_MIN_BYTES )
|
|
/** @} */
|
|
|
|
/**
|
|
* @brief Boolean type.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTFalse = 0, /**< Boolean False. */
|
|
eMQTTTrue = 1 /**< Boolean True. */
|
|
} MQTTBool_t;
|
|
|
|
/**
|
|
* @brief Return codes from various APIs.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTSuccess = 0, /**< 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. */
|
|
} MQTTReturnCode_t;
|
|
|
|
/**
|
|
* @brief The next expected byte.
|
|
*
|
|
* This enum helps in keeping track of the next expected byte in
|
|
* order to decode the incoming bytes.
|
|
*/
|
|
typedef enum
|
|
{
|
|
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. */
|
|
} MQTTRxNextByte_t;
|
|
|
|
/**
|
|
* @brief 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.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTRxMessageStore, /**< The message being received is being stored. */
|
|
eMQTTRxMessageDrop /**< The message being received is being dropped. */
|
|
} MQTTRxMessageAction_t;
|
|
|
|
/**
|
|
* @brief 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.
|
|
*/
|
|
typedef enum
|
|
{
|
|
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. */
|
|
} MQTTEventType_t;
|
|
|
|
/**
|
|
* @brief The reason of disconnect.
|
|
*
|
|
* Whenever the client is disconnected, the library sends the reason of
|
|
* disconnect in the user supplied callback.
|
|
*/
|
|
typedef enum
|
|
{
|
|
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. */
|
|
} MQTTDisconnectReason_t;
|
|
|
|
/**
|
|
* @brief Quality of Service (QoS).
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTQoS0 = 0, /**< Quality of Service 0 - Fire and Forget. No ACK. */
|
|
eMQTTQoS1 = 1, /**< Quality of Service 1 - Wait till ACK or Timeout. */
|
|
eMQTTQoS2 = 2 /**< Quality of Service 2 - Not supported. */
|
|
} MQTTQoS_t;
|
|
|
|
/**
|
|
* @brief The connection state.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTNotConnected, /**< Not connected. */
|
|
eMQTTConnectionInProgress, /**< Connect has been sent and waiting for CONNACK. */
|
|
eMQTTConnected /**< Connected. */
|
|
} MQTTConnectionState_t;
|
|
|
|
/**
|
|
* @brief 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.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTConnACKConnectionAccepted = 0, /**< Connection accepted by the broker. */
|
|
eMQTTConnACKUnacceptableProtocolVersion = 1, /**< Broker does not support the requested protocol version. */
|
|
eMQTTConnACKIdentifierRejected = 2, /**< Packet identifier rejected. */
|
|
eMQTTConnACKServerUnavailable = 3, /**< Broker unavailable. */
|
|
eMQTTConnACKBadUsernameOrPassword = 4, /**< Bad username or password. */
|
|
eMQTTConnACKUnauthorized = 5 /**< Unauthorized. */
|
|
} MQTTConnACKReturnCode_t;
|
|
|
|
/**
|
|
* @brief 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.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTSubACKSuccessQos0 = 0, /**< Subscription accepted. Granted QoS0. */
|
|
eMQTTSubACKSuccessQos1 = 1, /**< Subscription accepted. Granted QoS1. */
|
|
eMQTTSubACKSuccessQos2 = 2, /**< Subscription accepted. Granted QoS2. */
|
|
eMQTTSubACKFailure = 128 /**< Subscription rejected. */
|
|
} MQTTSubACKReturnCode_t;
|
|
|
|
/**
|
|
* @brief Represents the type of the topic filter.
|
|
*/
|
|
typedef enum
|
|
{
|
|
eMQTTTopicFilterTypeInvalid = 0, /**< The topic filter is invalid. */
|
|
eMQTTTopicFilterTypeSimple, /**< The topic filter does not contain any wild cards. */
|
|
eMQTTTopicFilterTypeWildCard /**< The topic filter contains wild cards. */
|
|
} MQTTTopicFilterType_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when a CONNACK message is received.
|
|
*/
|
|
typedef struct MQTTConnACKData
|
|
{
|
|
MQTTConnACKReturnCode_t xConnACkReturnCode; /**< CONNACK return code. @see MQTTConnACKReturnCode_t. */
|
|
uint16_t usPacketIdentifier; /**< Packet identifier which the user can use to match the CONNACK with the Connect request. */
|
|
} MQTTConnACKData_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when a SUBACK message is received.
|
|
*/
|
|
typedef struct MQTTSubACKData
|
|
{
|
|
MQTTSubACKReturnCode_t xSubACKReturnCode; /**< SUBACK return code. @see MQTTSubACKReturnCode_t. */
|
|
uint16_t usPacketIdentifier; /**< Packet identifier which the user can use to match the SUBACK with the Subscribe request. */
|
|
} MQTTSubACKData_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when an UNSUBACK message is received.
|
|
*/
|
|
typedef struct MQTTUnSubACKData
|
|
{
|
|
uint16_t usPacketIdentifier; /**< Packet identifier which the user can use to match the UNSUBACK with the Unsubscribe request. */
|
|
} MQTTUnSubACKData_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when a PUBACK message is received.
|
|
*/
|
|
typedef struct MQTTPubACKData
|
|
{
|
|
uint16_t usPacketIdentifier; /**< Packet identifier which the user can use to match the PUBACK with the Publish request. */
|
|
} MQTTPubACKData_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when a publish message from the broker is received.
|
|
*/
|
|
typedef struct MQTTPublishData
|
|
{
|
|
MQTTQoS_t xQos; /**< Quality of Service (QoS). */
|
|
const uint8_t * pucTopic; /**< The topic on which the message is received. */
|
|
uint16_t usTopicLength; /**< Length of the topic. */
|
|
const void * pvData; /**< The received message. */
|
|
uint32_t ulDataLength; /**< Length of the message. */
|
|
MQTTBufferHandle_t xBuffer; /**< The buffer containing the whole MQTT message. Both pcTopic and pvData are pointers to the locations in this buffer. */
|
|
} MQTTPublishData_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when an operation times out.
|
|
*/
|
|
typedef struct MQTTTimeoutData
|
|
{
|
|
uint16_t usPacketIdentifier; /**< Packet identifier which the user can use to identify which operation timed out. */
|
|
} MQTTTimeoutData_t;
|
|
|
|
/**
|
|
* @brief The data sent by the MQTT library in the user supplied callback
|
|
* when the client is disconnected.
|
|
*/
|
|
typedef struct MQTTDisconnectData
|
|
{
|
|
MQTTDisconnectReason_t xDisconnectReason; /**< The reason of disconnect. @see MQTTDisconnectReason_t. */
|
|
} MQTTDisconnectData_t;
|
|
|
|
/**
|
|
* @brief The parameters sent by the MQTT library in the user supplied callback.
|
|
*/
|
|
typedef struct MQTTCallbackParams
|
|
{
|
|
MQTTEventType_t xEventType; /**< The event type. */
|
|
|
|
/* Only one of the following is meaningful
|
|
* based on the value of xEventType. */
|
|
union
|
|
{
|
|
MQTTConnACKData_t xMQTTConnACKData; /**< CONNACK data. */
|
|
MQTTSubACKData_t xMQTTSubACKData; /**< SUBACK data. */
|
|
MQTTUnSubACKData_t xMQTTUnSubACKData; /**< UNSUBACK data. */
|
|
MQTTPubACKData_t xMQTTPubACKData; /**< PUBACK data. */
|
|
MQTTPublishData_t xPublishData; /**< Publish data. */
|
|
MQTTTimeoutData_t xTimeoutData; /**< Timeout data. */
|
|
MQTTDisconnectData_t xDisconnectData; /**< Disconnect data. */
|
|
} u;
|
|
} MQTTEventCallbackParams_t;
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pvCallbackContext The callback context as supplied by the user in Init parameters.
|
|
* @param[in] pxParams The event and related data.
|
|
*
|
|
* @return The return value is ignored in all other cases except publish (i.e. eMQTTPublish
|
|
* event):
|
|
* 1. If eMQTTTrue is returned - the ownership of the buffer passed in the callback (xBuffer
|
|
* in MQTTPublishData_t) lies with the user.
|
|
* 2. 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.<br>
|
|
* 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.
|
|
*/
|
|
typedef MQTTBool_t ( * MQTTEventCallback_t ) ( void * pvCallbackContext,
|
|
const MQTTEventCallbackParams_t * const pxParams );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pvPublishCallbackContext The callback context as supplied by the user in the
|
|
* subscribe parameters.
|
|
* @param[in] pxPublishData The publish data.
|
|
*
|
|
* @return The return value is interpreted as follows:
|
|
* 1. If eMQTTTrue is returned - the ownership of the buffer passed in the callback (xBuffer
|
|
* in MQTTPublishData_t) lies with the user.
|
|
* 2. 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.<br>
|
|
* 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.
|
|
*/
|
|
#ifdef mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT
|
|
|
|
typedef MQTTBool_t ( * MQTTPublishCallback_t ) ( void * pvPublishCallbackContext,
|
|
const MQTTPublishData_t * const pxPublishData );
|
|
|
|
#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pvSendContext The send context as supplied by the user in Init parameters.
|
|
* @param[in] pucData The data to transmit.
|
|
* @param[in] ulDataLength The length of the data.
|
|
*
|
|
* @return The number of bytes actually transmitted.
|
|
*/
|
|
typedef uint32_t ( * MQTTSend_t ) ( void * pvSendContext,
|
|
const uint8_t * const pucData,
|
|
uint32_t ulDataLength );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[out] pxCurrentTickCount The output parameter to receive the current tick count.
|
|
*/
|
|
typedef void ( * MQTTGetTicks_t ) ( uint64_t * pxCurrentTickCount );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[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.
|
|
*
|
|
* @return The pointer to the buffer if one is available, NULL otherwise.
|
|
*/
|
|
typedef uint8_t * ( * MQTTGetFreeBuffer_t ) ( uint32_t * pulBufferLength );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pucBuffer The buffer to return.
|
|
*/
|
|
typedef void ( * MQTTReturnBuffer_t ) ( uint8_t * pucBuffer );
|
|
|
|
/**
|
|
* @brief Represents a subscription entry in the subscription manager.
|
|
*/
|
|
#ifdef mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT
|
|
|
|
typedef struct MQTTSubscription
|
|
{
|
|
uint8_t ucTopicFilter[ mqttconfigSUBSCRIPTION_MANAGER_MAX_TOPIC_LENGTH ]; /**< The topic filter this subscription entry is for. */
|
|
uint16_t usTopicFilterLength; /**< The length of the topic filter. */
|
|
void * pvPublishCallbackContext; /**< The callback context supplied by the user while subscribing. */
|
|
MQTTPublishCallback_t pxPublishCallback; /**< The callback associated with this subscription. */
|
|
MQTTBool_t xInUse; /**< Tracks whether the subscription entry is in-use. */
|
|
MQTTTopicFilterType_t xTopicFilterType; /**< The type of the topic filter. */
|
|
} MQTTSubscription_t;
|
|
|
|
#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
|
|
|
|
/**
|
|
* @brief The subscription manager used to keep track of user subscriptions
|
|
* and topic specific callbacks.
|
|
*/
|
|
#ifdef mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT
|
|
|
|
typedef struct MQTTSubscriptionManager
|
|
{
|
|
MQTTSubscription_t xSubscriptions[ mqttconfigSUBSCRIPTION_MANAGER_MAX_SUBSCRIPTIONS ]; /**< User subscriptions. */
|
|
uint32_t ulInUseSubscriptions; /**< Number of subscription entries currently in use. */
|
|
} MQTTSubscriptionManager_t;
|
|
|
|
#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
|
|
|
|
/**
|
|
* @brief 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.
|
|
*/
|
|
typedef struct MQTTBufferPoolInterface
|
|
{
|
|
MQTTGetFreeBuffer_t pxGetBufferFxn; /**< The function to get a free buffer. @see MQTTGetFreeBuffer_t. */
|
|
MQTTReturnBuffer_t pxReturnBufferFxn; /**< The function to return the buffer. @see MQTTReturnBuffer_t. */
|
|
} MQTTBufferPoolInterface_t;
|
|
|
|
/**
|
|
* @brief Represents the state of the message currently being received.
|
|
*/
|
|
typedef struct MQTTRxMessageState
|
|
{
|
|
MQTTRxNextByte_t xRxNextByte; /**< The next expected byte type. @see MQTTRxNextByte_t. */
|
|
MQTTRxMessageAction_t xRxMessageAction; /**< Whether the current Rx message is being stored or dropped. Valid only after the fixed header has been received i.e. xRxNextByte is eMQTTRxNextByteMessage. @see MQTTRxMessageAction_t. */
|
|
uint8_t ucRemaingingLengthFieldBytes; /**< The number of bytes the "Remaining Length" field spans. Valid only after the fixed header has been received i.e. xRxNextByte is eMQTTRxNextByteMessage. */
|
|
uint32_t ulTotalMessageLength; /**< The total length of the message. Valid only after the fixed header has been received i.e. xRxNextByte is eMQTTRxNextByteMessage. */
|
|
} MQTTRxMessageState_t;
|
|
|
|
/**
|
|
* @brief 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.
|
|
*/
|
|
typedef struct MQTTContext
|
|
{
|
|
Link_t xTxBufferListHead; /**< The list of Tx buffers i.e. buffers containing transmitted messages waiting for ACK. */
|
|
MQTTBufferHandle_t xRxBuffer; /**< The Rx buffer i.e. the buffer used to store the incoming message. */
|
|
MQTTRxMessageState_t xRxMessageState; /**< The state of the message being received currently. */
|
|
uint8_t ucRxFixedHeaderBuffer[ mqttFIXED_HEADER_MAX_SIZE ]; /**< The buffer used to store the fixed header of the incoming message. */
|
|
uint32_t ulRxMessageReceivedLength; /**< The length of the message received so far. */
|
|
void * pvCallbackContext; /**< As supplied by the user in Init parameters. */
|
|
MQTTEventCallback_t pxCallback; /**< Callback supplied by the user to get notified of various events. */
|
|
void * pvSendContext; /**< As supplied by the user in Init parameters. */
|
|
MQTTSend_t pxMQTTSendFxn; /**< Callback supplied by the user to transmit data. */
|
|
MQTTGetTicks_t pxGetTicksFxn; /**< Callback supplied by the user to get current tick count. */
|
|
MQTTBufferPoolInterface_t xBufferPoolInterface; /**< The buffer pool interface supplied by the user. @see MQTTBufferPoolInterface_t. */
|
|
MQTTConnectionState_t xConnectionState; /**< The current connection state. */
|
|
uint64_t xLastSentMessageTimestamp; /**< The timestamp when the last message (or acknowledgment) was sent. */
|
|
uint32_t ulNextPeriodicInvokeTicks; /**< The time interval in ticks after which MQTT_Periodic function must be called. */
|
|
uint32_t ulKeepAliveActualIntervalTicks; /**< The time interval in ticks after which a keep alive message should be sent. */
|
|
uint32_t ulPingRequestTimeoutTicks; /**< The time interval in ticks to wait for PINGRESP after sending PINGREQ. */
|
|
MQTTBool_t xWaitingForPingResp; /**< Whether a keep alive message has been sent and we are waiting for response from the broker. */
|
|
#ifdef mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT
|
|
MQTTSubscriptionManager_t xSubscriptionManager; /**< The subscription manager used to keep track of user subscriptions and topic specific callbacks.*/
|
|
#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
|
|
} MQTTContext_t;
|
|
|
|
/**
|
|
* @brief MQTT Init Parameters.
|
|
*
|
|
* Parameters passed to the MQTT_Init API.
|
|
*/
|
|
typedef struct MQTTInitParams
|
|
{
|
|
void * pvCallbackContext; /**< Passed as it is in the event callback. */
|
|
MQTTEventCallback_t pxCallback; /**< User supplied callback to get notified of various events. Can be NULL. @see MQTTEventCallback_t.*/
|
|
void * pvSendContext; /**< Passed as it is in the send callback. */
|
|
MQTTSend_t pxMQTTSendFxn; /**< User supplied callback to transmit data. Must not be NULL. @see MQTTSend_t. */
|
|
MQTTGetTicks_t pxGetTicksFxn; /**< User supplied callback to get the current tick count. Can be NULL. @see MQTTGetTicks_t. */
|
|
MQTTBufferPoolInterface_t xBufferPoolInterface; /**< User supplied buffer pool interface. @see MQTTBufferPoolInterface_t. */
|
|
} MQTTInitParams_t;
|
|
|
|
/**
|
|
* @brief MQTT Connect Parameters.
|
|
*
|
|
* Parameters passed to the MQTT_Connect API.
|
|
*/
|
|
typedef struct MQTTConnectParams
|
|
{
|
|
uint16_t usKeepAliveIntervlSeconds; /**< The maximum time interval (in seconds) permitted to elapse between two control packets transmitted. */
|
|
uint32_t ulKeepAliveActualIntervalTicks; /**< The time interval in ticks after which a keep alive message should be sent. Note that keep alive messages are sent only if nothing else is sent. */
|
|
uint32_t ulPingRequestTimeoutTicks; /**< The time interval in ticks to wait for PINGRESP after sending PINGREQ. */
|
|
const uint8_t * pucClientId; /**< Client Id identifies the client to the server. Must be unique per broker. */
|
|
uint16_t usClientIdLength; /**< The length of the client Id. */
|
|
const uint8_t * pucUserName; /**< The user name. */
|
|
uint16_t usUserNameLength; /**< The length of the user name. */
|
|
uint16_t usPacketIdentifier; /**< The same identifier is returned in the callback when corresponding CONNACK is received or the operation times out. */
|
|
uint32_t ulTimeoutTicks; /**< The time interval in ticks after which the operation should fail. */
|
|
} MQTTConnectParams_t;
|
|
|
|
/**
|
|
* @brief MQTT Subscribe Parameters.
|
|
*
|
|
* Parameters passed to the MQTT_Subscribe API.
|
|
*/
|
|
typedef struct MQTTSubscribeParams
|
|
{
|
|
const uint8_t * pucTopic; /**< The topic to subscribe to. This can be a topic filter containing wild cards as permitted by the MQTT protocol. */
|
|
uint16_t usTopicLength; /**< The length of the topic. */
|
|
MQTTQoS_t xQos; /**< Requested Quality of Service (QoS). */
|
|
uint16_t usPacketIdentifier; /**< The same identifier is returned in the callback when corresponding SUBACK is received or the operation times out. */
|
|
uint32_t ulTimeoutTicks; /**< The time interval in ticks after which the operation should fail. */
|
|
#ifdef mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT
|
|
void * pvPublishCallbackContext; /**< Passed as it is in the publish callback. */
|
|
MQTTPublishCallback_t pxPublishCallback; /**< Callback function to be called whenever a publish message is received on this topic or on a topic which matches this
|
|
* topic filter. If a publish message is received on a topic which matches more than one topic filters, the order in which
|
|
* the callbacks are invoked is undefined. This can be NULL if the user does not want to register a topic specific callback,
|
|
* in which case the generic callback ( if registered during initialization ) is invoked. */
|
|
#endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */
|
|
} MQTTSubscribeParams_t;
|
|
|
|
/**
|
|
* @brief MQTT Unsubscribe Parameters.
|
|
*
|
|
* Parameters passed to the MQTT_Unsubscribe API.
|
|
*/
|
|
typedef struct MQTTUnsubscribeParams
|
|
{
|
|
const uint8_t * pucTopic; /**< The topic to unsubscribe from. */
|
|
uint16_t usTopicLength; /**< The length of the topic. */
|
|
uint16_t usPacketIdentifier; /**< The same identifier is returned in the callback when corresponding UNSUBACK is received or the operation times out. */
|
|
uint32_t ulTimeoutTicks; /**< The time interval in ticks after which the operation should fail. */
|
|
} MQTTUnsubscribeParams_t;
|
|
|
|
/**
|
|
* @brief MQTT Publish Parameters.
|
|
*
|
|
* Parameters passed to the MQTT_Publish API.
|
|
*/
|
|
typedef struct MQTTPublishParams
|
|
{
|
|
const uint8_t * pucTopic; /**< The topic to which the data should be published. */
|
|
uint16_t usTopicLength; /**< The length of the topic. */
|
|
MQTTQoS_t xQos; /**< Quality of Service. */
|
|
const void * pvData; /**< The data to publish. */
|
|
uint32_t ulDataLength; /**< Length of the data. */
|
|
uint16_t usPacketIdentifier; /**< The same identifier is returned in the callback when corresponding PUBACK is received or the operation times out. */
|
|
uint32_t ulTimeoutTicks; /**< The time interval in ticks after which the operation should fail. */
|
|
} MQTTPublishParams_t;
|
|
|
|
/**
|
|
* @brief Initializes the given MQTT Context.
|
|
*
|
|
* MQTT context must be initialized first using this API before passing it to
|
|
* the subsequent API calls.
|
|
*
|
|
* @param[in] pxMQTTContext The context to initialize.
|
|
* @param[in] pxInitParams Init parameters.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_Init( MQTTContext_t * pxMQTTContext,
|
|
const MQTTInitParams_t * const pxInitParams );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] pxConnectParams Connect parameters.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_Connect( MQTTContext_t * pxMQTTContext,
|
|
const MQTTConnectParams_t * const pxConnectParams );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_Disconnect( MQTTContext_t * pxMQTTContext );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] pxSubscribeParams Subscribe parameters.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_Subscribe( MQTTContext_t * pxMQTTContext,
|
|
const MQTTSubscribeParams_t * const pxSubscribeParams );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] pxUnsubscribeParams Unsubscribe parameters.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_Unsubscribe( MQTTContext_t * pxMQTTContext,
|
|
const MQTTUnsubscribeParams_t * const pxUnsubscribeParams );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] pxPublishParams Publish parameters.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_Publish( MQTTContext_t * pxMQTTContext,
|
|
const MQTTPublishParams_t * const pxPublishParams );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] pucReceivedData Received bytes.
|
|
* @param[in] xReceivedDataLength Number of received bytes.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_ParseReceivedData( MQTTContext_t * pxMQTTContext,
|
|
const uint8_t * pucReceivedData,
|
|
size_t xReceivedDataLength );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] xBufferHandle The buffer to return.
|
|
*
|
|
* @return eMQTTSuccess if everything succeeds, otherwise an error code explaining the reason of failure.
|
|
*/
|
|
MQTTReturnCode_t MQTT_ReturnBuffer( MQTTContext_t * pxMQTTContext,
|
|
MQTTBufferHandle_t xBufferHandle );
|
|
|
|
/**
|
|
* @brief 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.
|
|
*
|
|
* @param[in] pxMQTTContext The initialized MQTT context.
|
|
* @param[in] xCurrentTickCount The current tick count value.
|
|
*
|
|
* @return The time interval in ticks after which this function should be called again.
|
|
*/
|
|
uint32_t MQTT_Periodic( MQTTContext_t * pxMQTTContext,
|
|
uint64_t xCurrentTickCount );
|
|
|
|
#endif /* _AWS_MQTT_LIB_H_ */
|