David Fletcher / Mbed 2 deprecated cc3100_Test_mqtt_CM3

Update revision to use TI's mqtt and Freertos.

Dependencies:   mbed client server

Fork of cc3100_Test_mqtt_CM3 by David Fletcher

mqtt_V1/include/sl_mqtt_server.h@3:a8c249046181, 2015-09-03 (annotated)

Committer:
dflet
Date:
Thu Sep 03 14:02:37 2015 +0000
Revision:
3:a8c249046181
SPI Mode change 1 to 0

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dflet 3:a8c249046181 1 /*******************************************************************************
dflet 3:a8c249046181 2 Copyright (c) (2014) Texas Instruments Incorporated
dflet 3:a8c249046181 3 All rights reserved not granted herein.
dflet 3:a8c249046181 4
dflet 3:a8c249046181 5 Limited License.
dflet 3:a8c249046181 6
dflet 3:a8c249046181 7 Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive
dflet 3:a8c249046181 8 license under copyrights and patents it now or hereafter owns or controls to make,
dflet 3:a8c249046181 9 have made, use, import, offer to sell and sell ("Utilize") this software subject
dflet 3:a8c249046181 10 to the terms herein. With respect to the foregoing patent license, such license
dflet 3:a8c249046181 11 is granted solely to the extent that any such patent is necessary to Utilize the
dflet 3:a8c249046181 12 software alone. The patent license shall not apply to any combinations which
dflet 3:a8c249046181 13 include this software, other than combinations with devices manufactured by or
dflet 3:a8c249046181 14 for TI (�TI Devices�). No hardware patent is licensed hereunder.
dflet 3:a8c249046181 15
dflet 3:a8c249046181 16 Redistributions must preserve existing copyright notices and reproduce this license
dflet 3:a8c249046181 17 (including the above copyright notice and the disclaimer and (if applicable) source
dflet 3:a8c249046181 18 code license limitations below) in the documentation and/or other materials provided
dflet 3:a8c249046181 19 with the distribution
dflet 3:a8c249046181 20
dflet 3:a8c249046181 21 Redistribution and use in binary form, without modification, are permitted provided
dflet 3:a8c249046181 22 that the following conditions are met:
dflet 3:a8c249046181 23 * No reverse engineering, decompilation, or disassembly of this software is
dflet 3:a8c249046181 24 permitted with respect to any software provided in binary form.
dflet 3:a8c249046181 25 * any redistribution and use are licensed by TI for use only with TI Devices.
dflet 3:a8c249046181 26 * Nothing shall obligate TI to provide you with source code for the software
dflet 3:a8c249046181 27 licensed and provided to you in object code.
dflet 3:a8c249046181 28
dflet 3:a8c249046181 29 If software source code is provided to you, modification and redistribution of the
dflet 3:a8c249046181 30 source code are permitted provided that the following conditions are met;
dflet 3:a8c249046181 31 * any redistribution and use of the source code, including any resulting derivative
dflet 3:a8c249046181 32 works, are licensed by TI for use only with TI Devices.
dflet 3:a8c249046181 33 * any redistribution and use of any object code compiled from the source code and
dflet 3:a8c249046181 34 any resulting derivative works, are licensed by TI for use only with TI Devices.
dflet 3:a8c249046181 35
dflet 3:a8c249046181 36 Neither the name of Texas Instruments Incorporated nor the names of its suppliers
dflet 3:a8c249046181 37 may be used to endorse or promote products derived from this software without
dflet 3:a8c249046181 38 specific prior written permission.
dflet 3:a8c249046181 39
dflet 3:a8c249046181 40 DISCLAIMER.
dflet 3:a8c249046181 41
dflet 3:a8c249046181 42 THIS SOFTWARE IS PROVIDED BY TI AND TI�S LICENSORS "AS IS" AND ANY EXPRESS OR IMPLIED
dflet 3:a8c249046181 43 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
dflet 3:a8c249046181 44 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TI AND TI�S
dflet 3:a8c249046181 45 LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
dflet 3:a8c249046181 46 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
dflet 3:a8c249046181 47 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
dflet 3:a8c249046181 48 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
dflet 3:a8c249046181 49 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
dflet 3:a8c249046181 50 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
dflet 3:a8c249046181 51
dflet 3:a8c249046181 52 ******************************************************************************/
dflet 3:a8c249046181 53
dflet 3:a8c249046181 54 #include <stdio.h>
dflet 3:a8c249046181 55 #include <string.h>
dflet 3:a8c249046181 56 #include <stdbool.h>
dflet 3:a8c249046181 57 #include "cc3100_simplelink.h"
dflet 3:a8c249046181 58
dflet 3:a8c249046181 59 #ifndef __SL_MQTT_SRVR_H__
dflet 3:a8c249046181 60 #define __SL_MQTT_SRVR_H__
dflet 3:a8c249046181 61
dflet 3:a8c249046181 62 #ifdef __cplusplus
dflet 3:a8c249046181 63 extern "C"
dflet 3:a8c249046181 64 {
dflet 3:a8c249046181 65 #endif
dflet 3:a8c249046181 66
dflet 3:a8c249046181 67 namespace mbed_mqtt {
dflet 3:a8c249046181 68
dflet 3:a8c249046181 69 /*!
dflet 3:a8c249046181 70 \mainpage SimpleLink MQTT Server Layer
dflet 3:a8c249046181 71
dflet 3:a8c249046181 72 \section intro_sec Introduction
dflet 3:a8c249046181 73
dflet 3:a8c249046181 74 The SimpleLink MQTT Server Layer provides an easy-to-use API(s) to enable
dflet 3:a8c249046181 75 constrained and deeply embedded microcontroller based products to interact
dflet 3:a8c249046181 76 with cloud or network based clients for telemetry. The users of SL MQTT
dflet 3:a8c249046181 77 server services, while benefiting from the abstraction of the MQTT protocol
dflet 3:a8c249046181 78 would find them suitable for development of MQTT Servers.
dflet 3:a8c249046181 79
dflet 3:a8c249046181 80
dflet 3:a8c249046181 81 \section descrypt_sec Description
dflet 3:a8c249046181 82
dflet 3:a8c249046181 83 The SL MQTT Server Layer, in addition to providing services to the server
dflet 3:a8c249046181 84 application, encompasses an RTOS task to handle the incoming messages from the
dflet 3:a8c249046181 85 various clients conencted to the server.
dflet 3:a8c249046181 86 Such a dedicated context to process the messages from the clients facilitates the
dflet 3:a8c249046181 87 app to receive data (for ex. PUBLISH messages) even when it is
dflet 3:a8c249046181 88 transacting with another client. This is important considering that a server
dflet 3:a8c249046181 89 application has to manage messages from multiple clients connected
dflet 3:a8c249046181 90 to it simulatneously.
dflet 3:a8c249046181 91 The receive task in the SL MQTT Server Layer can not be disabled anytime,
dflet 3:a8c249046181 92 however its system wide priority is configurable and can be set.
dflet 3:a8c249046181 93
dflet 3:a8c249046181 94 Some of the salient features of the SL MQTT Layer are
dflet 3:a8c249046181 95
dflet 3:a8c249046181 96 - Easy-to-use, intuitive and small set of MQTT API
dflet 3:a8c249046181 97 - App can indicate its choice to await ACK for a message transaction
dflet 3:a8c249046181 98
dflet 3:a8c249046181 99 \section config_sec Configurations
dflet 3:a8c249046181 100 The SL implementation enables the application developers to configure the
dflet 3:a8c249046181 101 following parameters using the compile line flags (-D option):
dflet 3:a8c249046181 102 - <b> CFG_SR_MAX_MQP_RX_LEN</b> max length of the RX buffer for the server.
dflet 3:a8c249046181 103 - <b> CFG_SR_MAX_MQP_TX_LEN: </b> the constant buffer length allocated for a TX.\n\n
dflet 3:a8c249046181 104 - <b> CFG_SR_MAX_SUBTOP_LEN: </b> the maximum buffer size to hold a sub-topic.
dflet 3:a8c249046181 105 For e.g., in the topic /x/y/z, the phrase /x, /y and z are sub-topics. \n\n
dflet 3:a8c249046181 106 - <b> CFG_SR_MAX_TOPIC_NODE: </b> the maximum number of topic nodes in server.
dflet 3:a8c249046181 107 For e.g., in the topic /x/y/z, there are three nodes (/x, /y and z). \n\n
dflet 3:a8c249046181 108 - <b> CFG_SR_MAX_CL_ID_SIZE: </b> the maximum length of the client-id string. \n\n
dflet 3:a8c249046181 109 - <b> CFG_SR_MAX_NUM_CLIENT: </b> the maximum number of clients to be managed.
dflet 3:a8c249046181 110 Note this is different from the maximum number of 'contexts'. A large number
dflet 3:a8c249046181 111 of clients can be managed using fewer number of 'contexts' (connections). \n\n
dflet 3:a8c249046181 112
dflet 3:a8c249046181 113 \note An app that has chosen not to await an ACK from the client for a
dflet 3:a8c249046181 114 scheduled transaction can benefit from the availability of control to
dflet 3:a8c249046181 115 pursue other activities to make overall progress in the system. However,
dflet 3:a8c249046181 116 an attempt to schedule another transaction with the client, while the
dflet 3:a8c249046181 117 previous one is still active, will cause the application to block. The
dflet 3:a8c249046181 118 app will unblock, once the previous transaction is completed.
dflet 3:a8c249046181 119
dflet 3:a8c249046181 120 */
dflet 3:a8c249046181 121
dflet 3:a8c249046181 122 /** @defgroup sl_mqtt_srvr_api SL MQTT Server APIs
dflet 3:a8c249046181 123 @{
dflet 3:a8c249046181 124 */
dflet 3:a8c249046181 125
dflet 3:a8c249046181 126 /** @defgroup sl_mqtt_srvr_evt SL MQTT Server Events
dflet 3:a8c249046181 127 @{
dflet 3:a8c249046181 128 */
dflet 3:a8c249046181 129 #define SL_MQTT_SRVR_EVT_PUBACK 0x11 /**< PUBACK has been received from a client */
dflet 3:a8c249046181 130 #define SL_MQTT_SRVR_EVT_NOCONN 0x12 /**< Server has lost network connection with a client */
dflet 3:a8c249046181 131 /** @} */ /* End SL MQTT Server events */
dflet 3:a8c249046181 132
dflet 3:a8c249046181 133
dflet 3:a8c249046181 134 /** Callbacks Routines
dflet 3:a8c249046181 135 The routines are invoked by SL MQTT Server Implementation onto Server application
dflet 3:a8c249046181 136
dflet 3:a8c249046181 137 * \note The user applications implement the callbacks that are registered
dflet 3:a8c249046181 138 with the libraries. While using the MQTT library, invoking the
dflet 3:a8c249046181 139 core library APIs from a callback should be avoided and
dflet 3:a8c249046181 140 can lead to lockup scenarios. It is recommended to signal another
dflet 3:a8c249046181 141 task from the callback routines invoked from the library
dflet 3:a8c249046181 142 and invoke the core library API calls from that task.
dflet 3:a8c249046181 143 */
dflet 3:a8c249046181 144 typedef struct {
dflet 3:a8c249046181 145
dflet 3:a8c249046181 146 /** Connect Request: Callback routine to indicate to server application that a CONNECT
dflet 3:a8c249046181 147 request has been received by the server.
dflet 3:a8c249046181 148
dflet 3:a8c249046181 149 \param[in] clientId_str clientId field in the CONNECT message received.
dflet 3:a8c249046181 150 \param[in] clientId_len length of ClientId
dflet 3:a8c249046181 151 \param[in] username_str Username field in teh CONNECT message received.
dflet 3:a8c249046181 152 \param[in] username_len length of username
dflet 3:a8c249046181 153 \param[in] password_str Password field in the CONNECT message received.
dflet 3:a8c249046181 154 \param[in] password_len length of password
dflet 3:a8c249046181 155 \param[out] usr placeholder to provision app's handle to this connection.
dflet 3:a8c249046181 156 \return 0x0000 or 0x0100 for success; Otherwise 0x02, 0x04 or 0x05
dflet 3:a8c249046181 157 refer to spec for connack codes
dflet 3:a8c249046181 158
dflet 3:a8c249046181 159 */
dflet 3:a8c249046181 160 uint8_t (*sl_ExtLib_MqttConn)(const char *clientId_str, int32_t clientId_len,
dflet 3:a8c249046181 161 const char *username_str, int32_t username_len,
dflet 3:a8c249046181 162 const char *password_str, int32_t password_len,
dflet 3:a8c249046181 163 void **usr);
dflet 3:a8c249046181 164
dflet 3:a8c249046181 165
dflet 3:a8c249046181 166 /** Callback routine to receive a PUBLISH from a client.
dflet 3:a8c249046181 167 The server app must provide this routine for the instances where it
dflet 3:a8c249046181 168 receives PUBLISH messages from clients. The callback is
dflet 3:a8c249046181 169 invoked in the context of the internal SL MQTT server Receive Task.
dflet 3:a8c249046181 170
dflet 3:a8c249046181 171 \param[in] topstr name of topic on which PUBLISH is received by the server. Not NULL terminated.
dflet 3:a8c249046181 172 \param[in] toplen length of the topic name
dflet 3:a8c249046181 173 \param[in] payload refers to payload published by the server.
dflet 3:a8c249046181 174 \param[in] pay_len length of the payload.
dflet 3:a8c249046181 175 \param[in] dup assert to indicate that it is a duplicate message sent by the client
dflet 3:a8c249046181 176 \param[in] qoS quality of service of the received published message.
dflet 3:a8c249046181 177 \param[in] retain asserted to indicate that a retained message has been received
dflet 3:a8c249046181 178 \return none.
dflet 3:a8c249046181 179 */
dflet 3:a8c249046181 180 void (*sl_ExtLib_MqttRecv)(const char *topstr, int32_t toplen,
dflet 3:a8c249046181 181 const void *payload, int32_t pay_len,
dflet 3:a8c249046181 182 bool dup, uint8_t qos,
dflet 3:a8c249046181 183 bool retain);
dflet 3:a8c249046181 184
dflet 3:a8c249046181 185 // Note: Double check whether retain, dup, qos would be required for a server app (with no topic management)
dflet 3:a8c249046181 186
dflet 3:a8c249046181 187 /** DISCONNECT: Callback routine to indicate to the Server Application
dflet 3:a8c249046181 188 that a client has disconnected.
dflet 3:a8c249046181 189
dflet 3:a8c249046181 190 \param[in] usr app's handle to this connection.
dflet 3:a8c249046181 191 \param[in] due2err set to 1, if connection has been closed, without server
dflet 3:a8c249046181 192 receiving a DISCONNECT messsage.
dflet 3:a8c249046181 193 \return none.
dflet 3:a8c249046181 194 */
dflet 3:a8c249046181 195 void (*sl_ExtLib_MqttDisconn)(void *usr, bool due2err);
dflet 3:a8c249046181 196
dflet 3:a8c249046181 197
dflet 3:a8c249046181 198 /** Indication of event either from the server library or implementation generated.
dflet 3:a8c249046181 199 TBD - Reserved for future use.
dflet 3:a8c249046181 200
dflet 3:a8c249046181 201 \param[in] usr app's handle to this connection.
dflet 3:a8c249046181 202 \param[in] evt identifier to the reported event. Refer to @ref sl_mqtt_srvr_evt - TBD
dflet 3:a8c249046181 203 \param[in] buf points to buffer
dflet 3:a8c249046181 204 \param[in] len length of buffer
dflet 3:a8c249046181 205 \return none.
dflet 3:a8c249046181 206 */
dflet 3:a8c249046181 207 void (*sl_ExtLib_MqttEvent)(void *usr, int32_t evt, const void *buf, uint32_t len);
dflet 3:a8c249046181 208
dflet 3:a8c249046181 209 } SlMqttServerCbs_t;
dflet 3:a8c249046181 210
dflet 3:a8c249046181 211 /** Secure Socket Parameters to open a secure connection */
dflet 3:a8c249046181 212 typedef struct {
dflet 3:a8c249046181 213
dflet 3:a8c249046181 214 #define SL_MQTT_SRVR_NETCONN_IP6 0x01 /**< Assert for IPv6 connection, otherwise IPv4 */
dflet 3:a8c249046181 215 #define SL_MQTT_SRVR_NETCONN_URL 0x02 /**< Server address is an URL and not IP address */
dflet 3:a8c249046181 216 #define SL_MQTT_SRVR_NETCONN_SEC 0x04 /**< Connection to server must be secure (TLS) */
dflet 3:a8c249046181 217
dflet 3:a8c249046181 218 uint32_t netconn_flags; /**< Enumerate connection type */
dflet 3:a8c249046181 219 const char *server_addr; /**< Server Address: URL or IP */
dflet 3:a8c249046181 220 uint8_t port_number; /**< Port number of MQTT server */
dflet 3:a8c249046181 221 uint8_t method; /**< Method to tcp secured socket */
dflet 3:a8c249046181 222 uint32_t cipher; /**< Cipher to tcp secured socket */
dflet 3:a8c249046181 223 uint32_t n_files; /**< Number of files for secure transfer */
dflet 3:a8c249046181 224 char * const *secure_files; /*SL needs 4 files*/
dflet 3:a8c249046181 225
dflet 3:a8c249046181 226 } SlMqttServerParams_t;
dflet 3:a8c249046181 227
dflet 3:a8c249046181 228
dflet 3:a8c249046181 229 /** MQTT Server Lib structure which holds Initialization Data */
dflet 3:a8c249046181 230 typedef struct
dflet 3:a8c249046181 231 {
dflet 3:a8c249046181 232 SlMqttServerParams_t server_info; /**< Server information */
dflet 3:a8c249046181 233 uint8_t loopback_port; /**< Loopback port to manage lib internal functioning - Mandatory */
dflet 3:a8c249046181 234 uint32_t rx_tsk_priority; /**< Priority of the receive task in server */
dflet 3:a8c249046181 235 uint32_t resp_time; /**< Reasonable response wait time (seconds) for server */
dflet 3:a8c249046181 236 bool aux_debug_en; /**< Assert to indicate additional debug info */
dflet 3:a8c249046181 237 int32_t (*dbg_print)(const char *pcFormat, ...); /**< Print debug information */
dflet 3:a8c249046181 238 } SlMqttServerCfg_t;
dflet 3:a8c249046181 239
dflet 3:a8c249046181 240 /** Initialize the SL MQTT Server Implementation.
dflet 3:a8c249046181 241 A caller must initialize the MQTT Server implementation prior to using its services.
dflet 3:a8c249046181 242
dflet 3:a8c249046181 243 \param[in] cfg refers to configuration parameters
dflet 3:a8c249046181 244 \param[in] cbs callbacks into server application
dflet 3:a8c249046181 245 \return Success (0) or Failure (-1)
dflet 3:a8c249046181 246 */
dflet 3:a8c249046181 247 int32_t sl_ExtLib_MqttServerInit(const SlMqttServerCfg_t *cfg,
dflet 3:a8c249046181 248 const SlMqttServerCbs_t *cbs);
dflet 3:a8c249046181 249
dflet 3:a8c249046181 250 /** Enroll a topic to receive data
dflet 3:a8c249046181 251 App can enroll a topic of interest and the SL layer will forward to the app any
dflet 3:a8c249046181 252 data subsequently published for the enrolled topic to the server by any of the
dflet 3:a8c249046181 253 connected MQTT clients.
dflet 3:a8c249046181 254
dflet 3:a8c249046181 255 This is analogous or similar to a subsription to a topic by an MQTT client.
dflet 3:a8c249046181 256
dflet 3:a8c249046181 257 \param[in] topic enrollment topic for data to be received. It is NULL terminated.
dflet 3:a8c249046181 258 \return Success(0) or Failure (-1).
dflet 3:a8c249046181 259 */
dflet 3:a8c249046181 260 int32_t sl_ExtLib_MqttTopicEnroll(const char *topic);
dflet 3:a8c249046181 261
dflet 3:a8c249046181 262 static inline int32_t sl_ExtLib_MqttTopicSub(const char *topic)
dflet 3:a8c249046181 263 {
dflet 3:a8c249046181 264 return sl_ExtLib_MqttTopicEnroll(topic);
dflet 3:a8c249046181 265 }
dflet 3:a8c249046181 266
dflet 3:a8c249046181 267 /** DisEnroll a topic.
dflet 3:a8c249046181 268 App can cancel the previous enrollment of a topic and the SL layer will now stop
dflet 3:a8c249046181 269 forwarding data published for that topic to the server by the connected clients.
dflet 3:a8c249046181 270 This is analogous oe similar to an unsubsription by an MQTT client.
dflet 3:a8c249046181 271
dflet 3:a8c249046181 272 \param[in] topic disenrollment topic. It is NULL terminated.
dflet 3:a8c249046181 273 \return Success(0) or Failure(-1).
dflet 3:a8c249046181 274 */
dflet 3:a8c249046181 275 int32_t sl_ExtLib_MqttTopicDisenroll(const char *topic);
dflet 3:a8c249046181 276
dflet 3:a8c249046181 277 static inline int32_t sl_ExtLib_MqttTopicUnsub(const char *topic)
dflet 3:a8c249046181 278 {
dflet 3:a8c249046181 279 return sl_ExtLib_MqttTopicDisenroll(topic);
dflet 3:a8c249046181 280 }
dflet 3:a8c249046181 281
dflet 3:a8c249046181 282 /** PUBLISH a named message to a client.
dflet 3:a8c249046181 283 In addition to the PUBLISH specific parameters, the caller can indicate
dflet 3:a8c249046181 284 whether the routine should block until the time, the message has been
dflet 3:a8c249046181 285 acknowleged by the client. This is applicable only for non-QoS0 messages.
dflet 3:a8c249046181 286
dflet 3:a8c249046181 287 In case, the app has chosen not to await for the ACK from the client,
dflet 3:a8c249046181 288 the SL MQTT Server implementation will notify the app about the received ACK
dflet 3:a8c249046181 289 through the callback routine.
dflet 3:a8c249046181 290
dflet 3:a8c249046181 291 \note Only QoS0 and QoS1 messages are supported.
dflet 3:a8c249046181 292
dflet 3:a8c249046181 293 \param[in] topic topic of the data to be published. It is NULL terminated.
dflet 3:a8c249046181 294 \param[in] data binary data to be published
dflet 3:a8c249046181 295 \param[in] len length of the data
dflet 3:a8c249046181 296 \param[in] qos QoS for the publish message
dflet 3:a8c249046181 297 \param[in] retain Retain bit in the PUBLISH message sent out
dflet 3:a8c249046181 298 \param[in] flags Reserved for future use.
dflet 3:a8c249046181 299 \return Success(0) or Failure(-1).
dflet 3:a8c249046181 300 */
dflet 3:a8c249046181 301 int32_t sl_ExtLib_MqttServerSend(const char *topic, const void *data, int32_t len,
dflet 3:a8c249046181 302 uint8_t qos, bool retain, uint32_t flags);
dflet 3:a8c249046181 303
dflet 3:a8c249046181 304 /** @} */ /* End SL MQTT Server API */
dflet 3:a8c249046181 305
dflet 3:a8c249046181 306 }//namespace mbed_mqtt
dflet 3:a8c249046181 307
dflet 3:a8c249046181 308 #ifdef __cplusplus
dflet 3:a8c249046181 309 }
dflet 3:a8c249046181 310 #endif
dflet 3:a8c249046181 311
dflet 3:a8c249046181 312
dflet 3:a8c249046181 313
dflet 3:a8c249046181 314 #endif // __SL_MQTT_SRVR_H__
dflet 3:a8c249046181 315
dflet 3:a8c249046181 316
dflet 3:a8c249046181 317