David Fletcher / mqtt_V1

TI's mqtt.

Dependencies:   client server

include/sl_mqtt_server.h@1:673880ad39ad, 2015-06-06 (annotated)

Committer:
dflet
Date:
Sat Jun 06 13:37:53 2015 +0000
Revision:
1:673880ad39ad
Parent:
0:698866e331b2 
TI's mqtt

Who changed what in which revision?

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