git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/mqtt/include/iot_mqtt_agent.h

   1 /*\r
   2  * Amazon FreeRTOS MQTT V2.0.0\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_mqtt_agent.h\r
  28  * @brief MQTT Agent Interface.\r
  29  */\r
  30 \r
  31 #ifndef _AWS_MQTT_AGENT_H_\r
  32 #define _AWS_MQTT_AGENT_H_\r
  33 \r
  34 /* FreeRTOS includes. */\r
  35 #include "FreeRTOS.h"\r
  36 \r
  37 /* MQTT lib includes. */\r
  38 #include "iot_mqtt_lib.h"\r
  39 \r
  40 /* Library initialization definition include */\r
  41 #include "iot_lib_init.h"\r
  42 \r
  43 /**\r
  44  * @brief Opaque handle to represent an MQTT client.\r
  45  *\r
  46  * The MQTT library is capable of creating multiple MQTT clients, maximum number of which\r
  47  * is controlled by mqttconfigMAX_BROKERS macro. Each client is identified by an opaque\r
  48  * handle which is returned by the MQTT_AGENT_Create API call and later used in all\r
  49  * the subsequent API calls.\r
  50  */\r
  51 typedef void * MQTTAgentHandle_t;\r
  52 \r
  53 /**\r
  54  * @brief Return codes.\r
  55  *\r
  56  * Each API returns a value of this type.\r
  57  */\r
  58 typedef enum\r
  59 {\r
  60     eMQTTAgentSuccess,              /**< The operation was successful. */\r
  61     eMQTTAgentFailure,              /**< The operation failed. */\r
  62     eMQTTAgentTimeout,              /**< The operation timed out. */\r
  63     eMQTTAgentAPICalledFromCallback /**< The MQTT agent APIs must not be called from MQTT callbacks as callbacks run\r
  64                                      *   in the context of MQTT agent task and therefore can result in deadlock. This\r
  65                                      *   error code is returned if any MQTT agent API is invoked from any callback. */\r
  66 } MQTTAgentReturnCode_t;\r
  67 \r
  68 /**\r
  69  * @brief Various events reported by the library in the callback.\r
  70  *\r
  71  * The user can register an optional callback with the MQTT library to\r
  72  * get notified of various events including Publish messages received\r
  73  * from the broker. This enum identifies the event received in the\r
  74  * callback.\r
  75  */\r
  76 typedef enum\r
  77 {\r
  78     eMQTTAgentPublish,   /**< A Publish message was received from the broker. */\r
  79     eMQTTAgentDisconnect /**< The connection to the broker got disconnected. */\r
  80 } MQTTAgentEvent_t;\r
  81 \r
  82 /**\r
  83  * @brief Passed by the library in the callback to inform the user of various events.\r
  84  *\r
  85  * If the user has registered a callback to get notified of various events, a pointer\r
  86  * to this structure is passed in the callback function.\r
  87  * @see MQTTAgentEvent_t.\r
  88  */\r
  89 typedef struct MQTTAgentCallbackParams\r
  90 {\r
  91     MQTTAgentEvent_t xMQTTEvent; /**< Type of the event received. */\r
  92     /* This union is here for future support. */\r
  93     union\r
  94     {\r
  95         MQTTPublishData_t xPublishData; /**< Publish data. Meaningful only in case of eMQTTAgentPublish event. */\r
  96     } u;\r
  97 } MQTTAgentCallbackParams_t;\r
  98 \r
  99 /**\r
 100  * @brief Signature of the callback registered by the user to get notified of various events.\r
 101  *\r
 102  * The user can register an optional callback to get notified of various events.\r
 103  *\r
 104  * @param[in] pvUserData The user data as provided in the connect parameters while connecting.\r
 105  * @param[in] pxCallbackParams The event and related data.\r
 106  *\r
 107  * @return The return value is ignored in all other cases except publish (i.e. eMQTTAgentPublish\r
 108  * event):\r
 109  * 1. If pdTRUE is returned - The ownership of the buffer passed in the callback (xBuffer\r
 110  * in MQTTPublishData_t) lies with the user.\r
 111  * 2. If pdFALSE is returned - The ownership of the buffer passed in the callback (xBuffer\r
 112  * in MQTTPublishData_t) remains with the library and it is recycled as soon as\r
 113  * the callback returns.<br>\r
 114  * The user should take the ownership of the buffer containing the received message from the\r
 115  * broker by returning pdTRUE from the callback if the user wants to use the buffer after\r
 116  * the callback is over. The user should return the buffer whenever done by calling the\r
 117  * MQTT_AGENT_ReturnBuffer API.\r
 118  *\r
 119  * @see MQTTAgentCallbackParams_t.\r
 120  */\r
 121 typedef BaseType_t ( * MQTTAgentCallback_t )( void * pvUserData,\r
 122                                               const MQTTAgentCallbackParams_t * const pxCallbackParams );\r
 123 \r
 124 /**\r
 125  * @brief Flags for the MQTT agent connect params.\r
 126  */\r
 127 #define mqttagentURL_IS_IP_ADDRESS       0x00000001    /**< Set this bit in xFlags if the provided URL is an IP address. */\r
 128 #define mqttagentREQUIRE_TLS             0x00000002    /**< Set this bit in xFlags to use TLS. */\r
 129 #define mqttagentUSE_AWS_IOT_ALPN_443    0x00000004    /**< Set this bit in xFlags to use AWS IoT support for MQTT over TLS port 443. */\r
 130 \r
 131 /**\r
 132  * @brief Parameters passed to the MQTT_AGENT_Connect API.\r
 133  */\r
 134 typedef struct MQTTAgentConnectParams\r
 135 {\r
 136     const char * pcURL;             /**< The URL of the MQTT broker to connect to. */\r
 137     BaseType_t xFlags;              /**< Flags to control the behavior of MQTT connect. */\r
 138     BaseType_t xURLIsIPAddress;     /**< Deprecated. Set the mqttagentURL_IS_IP_ADDRESS bit in xFlags instead. */\r
 139     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
 140     const uint8_t * pucClientId;    /**< Client Identifier of the MQTT client. It should be unique per broker. */\r
 141     uint16_t usClientIdLength;      /**< The length of the client Id. */\r
 142     BaseType_t xSecuredConnection;  /**< Deprecated. Set the mqttagentREQUIRE_TLS bit in xFlags instead. */\r
 143     void * pvUserData;              /**< User data supplied back as it is in the callback. Can be NULL. */\r
 144     MQTTAgentCallback_t pxCallback; /**< Callback used to report various events. In addition to other events, this callback is invoked for the publish\r
 145                                      *   messages received on the topics for which the user has not registered any subscription callback. Can be NULL. */\r
 146     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
 147     uint32_t ulCertificateSize;     /**< Size of certificate used for secure connection. */\r
 148 } MQTTAgentConnectParams_t;\r
 149 \r
 150 /**\r
 151  * @brief Parameters passed to the MQTT_AGENT_Subscribe API.\r
 152  */\r
 153 typedef struct MQTTAgentSubscribeParams\r
 154 {\r
 155     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
 156     uint16_t usTopicLength;                      /**< The length of the topic. */\r
 157     MQTTQoS_t xQoS;                              /**< Requested Quality of Service. */\r
 158     #if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )\r
 159         void * pvPublishCallbackContext;         /**< Passed as it is in the publish callback. Can be NULL. */\r
 160         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
 161                                                   *   topic filter. If a publish message is received on a topic which matches more than one topic filters, the order in which\r
 162                                                   *   the callbacks are invoked is undefined. This can be NULL if the user does not want to register a topic specific callback,\r
 163                                                   *   in which case the generic callback ( if registered during connect ) is invoked. */\r
 164     #endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */\r
 165 } MQTTAgentSubscribeParams_t;\r
 166 \r
 167 /**\r
 168  * @brief Parameters passed to the MQTT_AGENT_Unsubscribe API.\r
 169  */\r
 170 typedef struct MQTTAgentUnsubscribeParams\r
 171 {\r
 172     const uint8_t * pucTopic; /**< The topic to unsubscribe from. */\r
 173     uint16_t usTopicLength;   /**< The length of the topic. */\r
 174 } MQTTAgentUnsubscribeParams_t;\r
 175 \r
 176 /**\r
 177  * @brief Parameters passed to the MQTT_AGENT_Publish API.\r
 178  */\r
 179 typedef struct MQTTAgentPublishParams\r
 180 {\r
 181     const uint8_t * pucTopic; /**< The topic string on which the message should be published. */\r
 182     uint16_t usTopicLength;   /**< The length of the topic. */\r
 183     MQTTQoS_t xQoS;           /**< Quality of Service (qos). */\r
 184     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
 185     uint32_t ulDataLength;    /**< Length of the data. */\r
 186 } MQTTAgentPublishParams_t;\r
 187 \r
 188 /**\r
 189  * @brief MQTT library Init function.\r
 190  *\r
 191  * This function does general initialization and setup. It must be called once\r
 192  * and only once before calling any other function.\r
 193  *\r
 194  * @return pdPASS if everything succeeds, pdFAIL otherwise.\r
 195  */\r
 196 lib_initDECLARE_LIB_INIT( MQTT_AGENT_Init );\r
 197 \r
 198 /**\r
 199  * @brief Creates a new MQTT client.\r
 200  *\r
 201  * The MQTT library is capable of creating multiple MQTT clients, maximum number of which\r
 202  * is controlled by mqttconfigMAX_BROKERS macro. If mqttconfigMAX_BROKERS clients are already\r
 203  * in use, this function will fail immediately. Otherwise a new client is setup and the handle\r
 204  * to the created client is returned in the pxMQTTHandle parameter which should be used in all\r
 205  * the subsequent API calls. Note that the returned handled is only valid if the return value\r
 206  * of the API is eMQTTAgentSuccess.\r
 207  *\r
 208  * @param[out] pxMQTTHandle Output parameter to return the opaque client handle.\r
 209  *\r
 210  * @return eMQTTAgentSuccess if a new client is successfully created, otherwise an error code\r
 211  * explaining the reason of the failure is returned.\r
 212  */\r
 213 MQTTAgentReturnCode_t MQTT_AGENT_Create( MQTTAgentHandle_t * const pxMQTTHandle );\r
 214 \r
 215 /**\r
 216  * @brief Deletes the already created MQTT client.\r
 217  *\r
 218  * This function just frees up the internal resources and does not disconnect. The user must\r
 219  * call MQTT_AGENT_Disconnect API to make sure that the client is disconnected before\r
 220  * deleting it.\r
 221  *\r
 222  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 223  *\r
 224  * @return eMQTTAgentSuccess if the client is successfully deleted, otherwise an\r
 225  * error code explaining the reason of the failure is returned.\r
 226  */\r
 227 MQTTAgentReturnCode_t MQTT_AGENT_Delete( MQTTAgentHandle_t xMQTTHandle );\r
 228 \r
 229 /**\r
 230  * @brief Establishes a connection with the MQTT broker.\r
 231  *\r
 232  * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
 233  * is short the calling task's notification state and value may be updated after MQTT_AGENT_Connect()\r
 234  * has returned.\r
 235  *\r
 236  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 237  * @param[in] pxConnectParams Connect parameters.\r
 238  * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
 239  * macro to convert milliseconds to ticks.\r
 240  *\r
 241  * @return eMQTTAgentSuccess if the connect operation succeeds, otherwise an error code explaining the\r
 242  * reason of the failure is returned.\r
 243  */\r
 244 MQTTAgentReturnCode_t MQTT_AGENT_Connect( MQTTAgentHandle_t xMQTTHandle,\r
 245                                           const MQTTAgentConnectParams_t * const pxConnectParams,\r
 246                                           TickType_t xTimeoutTicks );\r
 247 \r
 248 /**\r
 249  * @brief Disconnects the connection with the MQTT broker.\r
 250  *\r
 251  * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
 252  * is short the calling task's notification state and value may be updated after MQTT_AGENT_Disconnect()\r
 253  * has returned.\r
 254  *\r
 255  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 256  * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
 257  * macro to convert milliseconds to ticks.\r
 258  *\r
 259  * @return eMQTTAgentSuccess if the disconnect operation succeeds, otherwise an error code explaining\r
 260  * the reason of the failure is returned.\r
 261  */\r
 262 MQTTAgentReturnCode_t MQTT_AGENT_Disconnect( MQTTAgentHandle_t xMQTTHandle,\r
 263                                              TickType_t xTimeoutTicks );\r
 264 \r
 265 /**\r
 266  * @brief Subscribes to a given topic.\r
 267  *\r
 268  * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
 269  * is short the calling task's notification state and value may be updated after MQTT_AGENT_Subscribe()\r
 270  * has returned.\r
 271  *\r
 272  * Whenever a publish message is received on a topic, the registered callbacks are invoked\r
 273  * in the following order:\r
 274  * * If we have an exact matching entry in the subscription manager, the corresponding\r
 275  *   callback is invoked.\r
 276  * * Then the wild card topic filters are checked for match and the corresponding callbacks\r
 277  *   are invoked for the ones which match the topic.\r
 278  *\r
 279  * @note If a publish message is received on a topic which matches more than one topic\r
 280  * filters, the order in which the registered callbacks are invoked is undefined.\r
 281  *\r
 282  * @warning If the user takes the ownership of the MQTT buffer by returning eMQTTTrue from the\r
 283  * callback, no further callbacks are invoked. The user should make sure not to take the ownership\r
 284  * of the MQTT buffer if they want all the callbacks to get invoked. For example:\r
 285  * * Subscriptions: a/b/c, a/b/#, a/b/+\r
 286  * * Publish message received on topic: a/b/c --> First the callback corresponding to a/b/c\r
 287  *   subscription is invoked. Then the callbacks for topic filters a/b/# and a/b/+ are invoked\r
 288  *   in no particular order. If the user decides to take the ownership of the MQTT buffer in\r
 289  *   any of the callback by returning eMQTTTrue, no further callbacks are invoked.\r
 290  *\r
 291  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 292  * @param[in] pxSubscribeParams Subscribe parameters.\r
 293  * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
 294  * macro to convert milliseconds to ticks.\r
 295  *\r
 296  * @return eMQTTAgentSuccess if the subscribe operation succeeds, otherwise an error code explaining\r
 297  * the reason of the failure is returned.\r
 298  */\r
 299 MQTTAgentReturnCode_t MQTT_AGENT_Subscribe( MQTTAgentHandle_t xMQTTHandle,\r
 300                                             const MQTTAgentSubscribeParams_t * const pxSubscribeParams,\r
 301                                             TickType_t xTimeoutTicks );\r
 302 \r
 303 /**\r
 304  * @brief Unsubscribes from a given topic.\r
 305  *\r
 306  * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
 307  * is short the calling task's notification state and value may be updated after MQTT_AGENT_Unsubscribe()\r
 308  * has returned.\r
 309  *\r
 310  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 311  * @param[in] pxUnsubscribeParams Unsubscribe parameters.\r
 312  * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
 313  * macro to convert milliseconds to ticks.\r
 314  *\r
 315  * @return eMQTTAgentSuccess if the unsubscribe operation succeeds, otherwise an error code explaining\r
 316  * the reason of the failure is returned.\r
 317  */\r
 318 MQTTAgentReturnCode_t MQTT_AGENT_Unsubscribe( MQTTAgentHandle_t xMQTTHandle,\r
 319                                               const MQTTAgentUnsubscribeParams_t * const pxUnsubscribeParams,\r
 320                                               TickType_t xTimeoutTicks );\r
 321 \r
 322 /**\r
 323  * @brief Publishes a message to a given topic.\r
 324  *\r
 325  * @note This function alters the calling task's notification state and value. If xTimeoutTicks\r
 326  * is short the calling task's notification state and value may be updated after MQTT_AGENT_Publish()\r
 327  * has returned.\r
 328  *\r
 329  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 330  * @param[in] pxPublishParams Publish parameters.\r
 331  * @param[in] xTimeoutTicks Maximum time in ticks after which the operation should fail. Use pdMS_TO_TICKS\r
 332  * macro to convert milliseconds to ticks.\r
 333  *\r
 334  * @return eMQTTAgentSuccess if the publish operation succeeds, otherwise an error code explaining\r
 335  * the reason of the failure is returned.\r
 336  */\r
 337 MQTTAgentReturnCode_t MQTT_AGENT_Publish( MQTTAgentHandle_t xMQTTHandle,\r
 338                                           const MQTTAgentPublishParams_t * const pxPublishParams,\r
 339                                           TickType_t xTimeoutTicks );\r
 340 \r
 341 /**\r
 342  * @brief Returns the buffer provided in the publish callback.\r
 343  *\r
 344  * When a publish message is received from the broker, the buffer containing the message\r
 345  * is returned in the user supplied callback (xBuffer in MQTTPublishData_t) and the user\r
 346  * can take the ownership by returning pdTRUE from the callback. The user should later\r
 347  * return the buffer whenever done by calling the MQTT_AGENT_ReturnBuffer API.\r
 348  *\r
 349  * @param[in] xMQTTHandle The opaque handle as returned from MQTT_AGENT_Create.\r
 350  * @param[in] xBufferHandle The buffer to return.\r
 351  *\r
 352  * @return eMQTTAgentSuccess if the return buffer operation succeeds, otherwise an error\r
 353  * code explaining the reason of the failure is returned.\r
 354  */\r
 355 MQTTAgentReturnCode_t MQTT_AGENT_ReturnBuffer( MQTTAgentHandle_t xMQTTHandle,\r
 356                                                MQTTBufferHandle_t xBufferHandle );\r
 357 \r
 358 #endif /* _AWS_MQTT_AGENT_H_ */\r