git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/mqtt/include/iot_mqtt_lib.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_lib.h\r
  28  * @brief MQTT Core Library interface.\r
  29  */\r
  30 \r
  31 #ifndef _AWS_MQTT_LIB_H_\r
  32 #define _AWS_MQTT_LIB_H_\r
  33 \r
  34 /* This ifndef enables the core MQTT library to be used without\r
  35  * providing MQTTConfig.h. All the config values in this case are\r
  36  * taken from MQTTConfigDefaults.h. */\r
  37 #ifndef mqttDO_NOT_USE_CUSTOM_CONFIG\r
  38     #include "aws_mqtt_config.h"\r
  39 #endif\r
  40 #include "iot_mqtt_config_defaults.h"\r
  41 \r
  42 #include "iot_doubly_linked_list.h"\r
  43 \r
  44  /**\r
  45   * @brief Opaque handle to represent an MQTT buffer.\r
  46   */\r
  47 typedef void * MQTTBufferHandle_t;\r
  48 \r
  49 /**\r
  50  * @brief Boolean type.\r
  51  */\r
  52 typedef enum\r
  53 {\r
  54     eMQTTFalse = 0, /**< Boolean False. */\r
  55     eMQTTTrue = 1   /**< Boolean True. */\r
  56 } MQTTBool_t;\r
  57 \r
  58 /**\r
  59  * @brief Quality of Service (qos).\r
  60  */\r
  61 typedef enum\r
  62 {\r
  63     eMQTTQoS0 = 0, /**< Quality of Service 0 - Fire and Forget. No ACK. */\r
  64     eMQTTQoS1 = 1, /**< Quality of Service 1 - Wait till ACK or Timeout. */\r
  65     eMQTTQoS2 = 2  /**< Quality of Service 2 - Not supported. */\r
  66 } MQTTQoS_t;\r
  67 \r
  68 /**\r
  69  * @brief The data sent by the MQTT library in the user supplied callback\r
  70  * when a publish message from the broker is received.\r
  71  */\r
  72 typedef struct MQTTPublishData\r
  73 {\r
  74     MQTTQoS_t xQos;             /**< Quality of Service (qos). */\r
  75     const uint8_t * pucTopic;   /**< The topic on which the message is received. */\r
  76     uint16_t usTopicLength;     /**< Length of the topic. */\r
  77     const void * pvData;        /**< The received message. */\r
  78     uint32_t ulDataLength;      /**< Length of the message. */\r
  79     MQTTBufferHandle_t xBuffer; /**< The buffer containing the whole MQTT message. Both pcTopic and pvData are pointers to the locations in this buffer. */\r
  80 } MQTTPublishData_t;\r
  81 \r
  82 /**\r
  83  * @brief Signature of the user supplied topic specific publish callback which gets called\r
  84  * whenever a publish message is received on the topic this callback is registered for.\r
  85  *\r
  86  * The user can choose to register this optional topic specific callback while subscribing to\r
  87  * a topic. Whenever a publish message is received on the topic, this callback is invoked. If\r
  88  * the user chooses not to enable subscription management or chooses not to register a topic\r
  89  * specific callback, the generic callback supplied during Init is invoked.\r
  90  *\r
  91  * @param[in] pvPublishCallbackContext The callback context as supplied by the user in the\r
  92  * subscribe parameters.\r
  93  * @param[in] pxPublishData The publish data.\r
  94  *\r
  95  * @return The return value is interpreted as follows:\r
  96  * 1. If eMQTTTrue is returned - the ownership of the buffer passed in the callback (xBuffer\r
  97  * in MQTTPublishData_t) lies with the user.\r
  98  * 2. If eMQTTFalse is returned - the ownership of the buffer passed in the callback (xBuffer\r
  99  * in MQTTPublishData_t) remains with the library and it is recycled as soon as the callback\r
 100  * returns.<br>\r
 101  * The user should take the ownership of the buffer containing the received message from the\r
 102  * broker by returning eMQTTTrue from the callback if the user wants to use the buffer after\r
 103  * the callback is over. The user should return the buffer whenever done by calling the\r
 104  * MQTT_ReturnBuffer API.\r
 105  */\r
 106 #if ( mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT == 1 )\r
 107 \r
 108     typedef MQTTBool_t ( * MQTTPublishCallback_t )( void * pvPublishCallbackContext,\r
 109                                                     const MQTTPublishData_t * const pxPublishData );\r
 110 \r
 111 #endif /* mqttconfigENABLE_SUBSCRIPTION_MANAGEMENT */\r
 112 \r
 113 #endif /* _AWS_MQTT_LIB_H_ */\r