+++ /dev/null
-/*\r
- * Amazon FreeRTOS MQTT V2.0.0\r
- * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
- *\r
- * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
- * this software and associated documentation files (the "Software"), to deal in\r
- * the Software without restriction, including without limitation the rights to\r
- * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
- * the Software, and to permit persons to whom the Software is furnished to do so,\r
- * subject to the following conditions:\r
- *\r
- * The above copyright notice and this permission notice shall be included in all\r
- * copies or substantial portions of the Software.\r
- *\r
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
- * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
- * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
- * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
- * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
- *\r
- * http://aws.amazon.com/freertos\r
- * http://www.FreeRTOS.org\r
- */\r
-\r
-/**\r
- * @file iot_mqtt_agent.h\r
- * @brief MQTT Agent Interface.\r
- */\r
-\r
-#ifndef _AWS_MQTT_AGENT_H_\r
-#define _AWS_MQTT_AGENT_H_\r
-\r
-/* FreeRTOS includes. */\r
-#include "FreeRTOS.h"\r
-\r
-/* MQTT lib includes. */\r
-#include "iot_mqtt_lib.h"\r
-\r
-/* Library initialization definition include */\r
-#include "iot_lib_init.h"\r
-\r
-/**\r
- * @brief Opaque handle to represent an MQTT client.\r
- *\r
- * The MQTT library is capable of creating multiple MQTT clients, maximum number of which\r
- * is controlled by mqttconfigMAX_BROKERS macro. Each client is identified by an opaque\r
- * handle which is returned by the MQTT_AGENT_Create API call and later used in all\r
- * the subsequent API calls.\r
- */\r
-typedef void * MQTTAgentHandle_t;\r
-\r
-/**\r
- * @brief Return codes.\r
- *\r
- * Each API returns a value of this type.\r
- */\r
-typedef enum\r
-{\r
- eMQTTAgentSuccess, /**< The operation was successful. */\r
- eMQTTAgentFailure, /**< The operation failed. */\r
- eMQTTAgentTimeout, /**< The operation timed out. */\r
- eMQTTAgentAPICalledFromCallback /**< The MQTT agent APIs must not be called from MQTT callbacks as callbacks run\r
- * in the context of MQTT agent task and therefore can result in deadlock. This\r
- * error code is returned if any MQTT agent API is invoked from any callback. */\r
-} MQTTAgentReturnCode_t;\r
-\r
-/**\r
- * @brief Various events reported by the library in the callback.\r
- *\r
- * The user can register an optional callback with the MQTT library to\r
- * get notified of various events including Publish messages received\r
- * from the broker. This enum identifies the event received in the\r
- * callback.\r
- */\r
-typedef enum\r
-{\r
- eMQTTAgentPublish, /**< A Publish message was received from the broker. */\r
- eMQTTAgentDisconnect /**< The connection to the broker got disconnected. */\r
-} MQTTAgentEvent_t;\r
-\r
-/**\r
- * @brief Passed by the library in the callback to inform the user of various events.\r
- *\r
- * If the user has registered a callback to get notified of various events, a pointer\r
- * to this structure is passed in the callback function.\r
- * @see MQTTAgentEvent_t.\r
- */\r
-typedef struct MQTTAgentCallbackParams\r
-{\r
- MQTTAgentEvent_t xMQTTEvent; /**< Type of the event received. */\r
- /* This union is here for future support. */\r
- union\r
- {\r
- MQTTPublishData_t xPublishData; /**< Publish data. Meaningful only in case of eMQTTAgentPublish event. */\r
- } u;\r
-} MQTTAgentCallbackParams_t;\r
-\r
-/**\r
- * @brief Signature of the callback registered by the user to get notified of various events.\r
- *\r
- * The user can register an optional callback to get notified of various events.\r
- *\r
- * @param[in] pvUserData The user data as provided in the connect parameters while connecting.\r
- * @param[in] pxCallbackParams The event and related data.\r
- *\r
- * @return The return value is ignored in all other cases except publish (i.e. eMQTTAgentPublish\r
- * event):\r
- * 1. If pdTRUE is returned - The ownership of the buffer passed in the callback (xBuffer\r
- * in MQTTPublishData_t) lies with the user.\r
- * 2. If pdFALSE is returned - The ownership of the buffer passed in the callback (xBuffer\r
- * in MQTTPublishData_t) remains with the library and it is recycled as soon as\r
- * the callback returns.<br>\r
- * The user should take the ownership of the buffer containing the received message from the\r
- * broker by returning pdTRUE from the callback if the user wants to use the buffer after\r
- * the callback is over. The user should return the buffer whenever done by calling the\r
- * MQTT_AGENT_ReturnBuffer API.\r
- *\r
- * @see MQTTAgentCallbackParams_t.\r
- */\r
-typedef BaseType_t ( * MQTTAgentCallback_t )( void * pvUserData,\r
- const MQTTAgentCallbackParams_t * const pxCallbackParams );\r
-\r
-/**\r
- * @brief Flags for the MQTT agent connect params.\r
- */\r
-#define mqttagentURL_IS_IP_ADDRESS 0x00000001 /**< Set this bit in xFlags if the provided URL is an IP address. */\r
-#define mqttagentREQUIRE_TLS 0x00000002 /**< Set this bit in xFlags to use TLS. */\r
-#define mqttagentUSE_AWS_IOT_ALPN_443 0x00000004 /**< Set this bit in xFlags to use AWS IoT support for MQTT over TLS port 443. */\r
-\r
-/**\r
- * @brief Parameters passed to the MQTT_AGENT_Connect API.\r
- */\r
-typedef struct MQTTAgentConnectParams\r
-{\r
- const char * pcURL; /**< The URL of the MQTT broker to connect to. */\r
- BaseType_t xFlags; /**< Flags to control the behavior of MQTT connect. */\r
- BaseType_t xURLIsIPAddress; /**< Deprecated. Set the mqttagentURL_IS_IP_ADDRESS bit in xFlags instead. */\r
- uint16_t usPort; /**< Port number at which MQTT broker is listening. This field is ignored if the mqttagentUSE_AWS_IOT_ALPN_443 flag is set. */\r
- const uint8_t * pucClientId; /**< Client Identifier of the MQTT client. It should be unique per broker. */\r
- uint16_t usClientIdLength; /**< The length of the client Id. */\r
- BaseType_t xSecuredConnection; /**< Deprecated. Set the mqttagentREQUIRE_TLS bit in xFlags instead. */\r
- void * pvUserData; /**< User data supplied back as it is in the callback. Can be NULL. */\r
- MQTTAgentCallback_t pxCallback; /**< Callback used to report various events. In addition to other events, this callback is invoked for the publish\r
- * messages received on the topics for which the user has not registered any subscription callback. Can be NULL. */\r
- char * pcCertificate; /**< Certificate used for secure connection. Can be NULL. If it is NULL, the one specified in the aws_credential_keys.h is used. */\r
- uint32_t ulCertificateSize; /**< Size of certificate used for secure connection. */\r
-} MQTTAgentConnectParams_t;\r
-\r
-/**\r
- * @brief Parameters passed to the MQTT_AGENT_Subscribe API.\r
- */\r
-typedef struct MQTTAgentSubscribeParams\r
-{\r
- const uint8_t * pucTopic; /**< The topic to subscribe to. This can be a topic filter containing wild cards as permitted by the MQTT protocol. */\r
- uint16_t usTopicLength; /**< The length of the topic. */\r
- MQTTQoS_t xQoS; /**< Requested Quality of Service. */\r
- #if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )\r
- void * pvPublishCallbackContext; /**< Passed as it is in the publish callback. Can be NULL. */\r
- MQTTPublishCallback_t pxPublishCallback; /**< Callback function to be called whenever a publish message is received on this topic or on a topic which matches this\r
- * topic filter. If a publish message is received on a topic which matches more than one topic filters, the order in which\r
- * the callbacks are invoked is undefined. This can be NULL if the user does not want to register a topic specific callback,\r
- * in which case the generic callback ( if registered during connect ) is invoked. */\r
- #endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */\r
-} MQTTAgentSubscribeParams_t;\r
-\r
-/**\r
- * @brief Parameters passed to the MQTT_AGENT_Unsubscribe API.\r
- */\r
-typedef struct MQTTAgentUnsubscribeParams\r
-{\r
- const uint8_t * pucTopic; /**< The topic to unsubscribe from. */\r
- uint16_t usTopicLength; /**< The length of the topic. */\r
-} MQTTAgentUnsubscribeParams_t;\r
-\r
-/**\r
- * @brief Parameters passed to the MQTT_AGENT_Publish API.\r
- */\r
-typedef struct MQTTAgentPublishParams\r
-{\r
- const uint8_t * pucTopic; /**< The topic string on which the message should be published. */\r
- uint16_t usTopicLength; /**< The length of the topic. */\r
- MQTTQoS_t xQoS; /**< Quality of Service (qos). */\r
- const void * pvData; /**< The data to publish. This data is copied into the MQTT buffers and therefore the user can free the buffer after the MQTT_AGENT_Publish call returns. */\r
- uint32_t ulDataLength; /**< Length of the data. */\r
-} MQTTAgentPublishParams_t;\r
-\r
-/**\r
- * @brief MQTT library Init function.\r
- *\r
- * This function does general initialization and setup. It must be called once\r
- * and only once before calling any other function.\r
- *\r
- * @return pdPASS if everything succeeds, pdFAIL otherwise.\r
- */\r
-lib_initDECLARE_LIB_INIT( MQTT_AGENT_Init );\r
-\r
-/**\r
- * @brief Creates a new MQTT client.\r
- *\r
- * The MQTT library is capable of creating multiple MQTT clients, maximum number of which\r
- * is controlled by mqttconfigMAX_BROKERS macro. If mqttconfigMAX_BROKERS clients are already\r
- * in use, this function will fail immediately. Otherwise a new client is setup and the handle\r
- * to the created client is returned in the pxMQTTHandle parameter which should be used in all\r
- * the subsequent API calls. Note that the returned handled is only valid if the return value\r
- * of the API is eMQTTAgentSuccess.\r
- *\r
- * @param[out] pxMQTTHandle Output parameter to return the opaque client handle.\r
- *\r
- * @return eMQTTAgentSuccess if a new client is successfully created, otherwise an error code\r
- * explaining the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Create( MQTTAgentHandle_t * const pxMQTTHandle );\r
-\r
-/**\r
- * @brief Deletes the already created MQTT client.\r
- *\r
- * This function just frees up the internal resources and does not disconnect. The user must\r
- * call MQTT_AGENT_Disconnect API to make sure that the client is disconnected before\r
- * deleting it.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- *\r
- * @return eMQTTAgentSuccess if the client is successfully deleted, otherwise an\r
- * error code explaining the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Delete( MQTTAgentHandle_t xMQTTHandle );\r
-\r
-/**\r
- * @brief Establishes a connection with the MQTT broker.\r
- *\r
- * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
- * is short the calling task's notification state and value may be updated after MQTT_AGENT_Connect()\r
- * has returned.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- * @param[in] pxConnectParams Connect parameters.\r
- * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
- * macro to convert milliseconds to ticks.\r
- *\r
- * @return eMQTTAgentSuccess if the connect operation succeeds, otherwise an error code explaining the\r
- * reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Connect( MQTTAgentHandle_t xMQTTHandle,\r
- const MQTTAgentConnectParams_t * const pxConnectParams,\r
- TickType_t xTimeoutTicks );\r
-\r
-/**\r
- * @brief Disconnects the connection with the MQTT broker.\r
- *\r
- * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
- * is short the calling task's notification state and value may be updated after MQTT_AGENT_Disconnect()\r
- * has returned.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
- * macro to convert milliseconds to ticks.\r
- *\r
- * @return eMQTTAgentSuccess if the disconnect operation succeeds, otherwise an error code explaining\r
- * the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Disconnect( MQTTAgentHandle_t xMQTTHandle,\r
- TickType_t xTimeoutTicks );\r
-\r
-/**\r
- * @brief Subscribes to a given topic.\r
- *\r
- * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
- * is short the calling task's notification state and value may be updated after MQTT_AGENT_Subscribe()\r
- * has returned.\r
- *\r
- * Whenever a publish message is received on a topic, the registered callbacks are invoked\r
- * in the following order:\r
- * * If we have an exact matching entry in the subscription manager, the corresponding\r
- * callback is invoked.\r
- * * Then the wild card topic filters are checked for match and the corresponding callbacks\r
- * are invoked for the ones which match the topic.\r
- *\r
- * @note If a publish message is received on a topic which matches more than one topic\r
- * filters, the order in which the registered callbacks are invoked is undefined.\r
- *\r
- * @warning If the user takes the ownership of the MQTT buffer by returning eMQTTTrue from the\r
- * callback, no further callbacks are invoked. The user should make sure not to take the ownership\r
- * of the MQTT buffer if they want all the callbacks to get invoked. For example:\r
- * * Subscriptions: a/b/c, a/b/#, a/b/+\r
- * * Publish message received on topic: a/b/c --> First the callback corresponding to a/b/c\r
- * subscription is invoked. Then the callbacks for topic filters a/b/# and a/b/+ are invoked\r
- * in no particular order. If the user decides to take the ownership of the MQTT buffer in\r
- * any of the callback by returning eMQTTTrue, no further callbacks are invoked.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- * @param[in] pxSubscribeParams Subscribe parameters.\r
- * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
- * macro to convert milliseconds to ticks.\r
- *\r
- * @return eMQTTAgentSuccess if the subscribe operation succeeds, otherwise an error code explaining\r
- * the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Subscribe( MQTTAgentHandle_t xMQTTHandle,\r
- const MQTTAgentSubscribeParams_t * const pxSubscribeParams,\r
- TickType_t xTimeoutTicks );\r
-\r
-/**\r
- * @brief Unsubscribes from a given topic.\r
- *\r
- * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
- * is short the calling task's notification state and value may be updated after MQTT_AGENT_Unsubscribe()\r
- * has returned.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- * @param[in] pxUnsubscribeParams Unsubscribe parameters.\r
- * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
- * macro to convert milliseconds to ticks.\r
- *\r
- * @return eMQTTAgentSuccess if the unsubscribe operation succeeds, otherwise an error code explaining\r
- * the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Unsubscribe( MQTTAgentHandle_t xMQTTHandle,\r
- const MQTTAgentUnsubscribeParams_t * const pxUnsubscribeParams,\r
- TickType_t xTimeoutTicks );\r
-\r
-/**\r
- * @brief Publishes a message to a given topic.\r
- *\r
- * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
- * is short the calling task's notification state and value may be updated after MQTT_AGENT_Publish()\r
- * has returned.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- * @param[in] pxPublishParams Publish parameters.\r
- * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
- * macro to convert milliseconds to ticks.\r
- *\r
- * @return eMQTTAgentSuccess if the publish operation succeeds, otherwise an error code explaining\r
- * the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_Publish( MQTTAgentHandle_t xMQTTHandle,\r
- const MQTTAgentPublishParams_t * const pxPublishParams,\r
- TickType_t xTimeoutTicks );\r
-\r
-/**\r
- * @brief Returns the buffer provided in the publish callback.\r
- *\r
- * When a publish message is received from the broker, the buffer containing the message\r
- * is returned in the user supplied callback (xBuffer in MQTTPublishData_t) and the user\r
- * can take the ownership by returning pdTRUE from the callback. The user should later\r
- * return the buffer whenever done by calling the MQTT_AGENT_ReturnBuffer API.\r
- *\r
- * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
- * @param[in] xBufferHandle The buffer to return.\r
- *\r
- * @return eMQTTAgentSuccess if the return buffer operation succeeds, otherwise an error\r
- * code explaining the reason of the failure is returned.\r
- */\r
-MQTTAgentReturnCode_t MQTT_AGENT_ReturnBuffer( MQTTAgentHandle_t xMQTTHandle,\r
- MQTTBufferHandle_t xBufferHandle );\r
-\r
-#endif /* _AWS_MQTT_AGENT_H_ */\r
projects / freertos / blobdiff