David Fletcher / mqtt_V1

TI's mqtt.

Dependencies:   client server

include/sl_mqtt_client.h@0:698866e331b2, 2015-06-06 (annotated)

Committer:
dflet
Date:
Sat Jun 06 13:29:50 2015 +0000
Revision:
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_H__
dflet 0:698866e331b2 60 #define __SL_MQTT_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 Client Layer
dflet 0:698866e331b2 71
dflet 0:698866e331b2 72 * \section intro_sec Introduction
dflet 0:698866e331b2 73
dflet 0:698866e331b2 74 The SimpleLink MQTT Client 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 server for telemetery. The users of SL MQTT
dflet 0:698866e331b2 77 Client services, while benefiting from the abstraction of the MQTT protocol
dflet 0:698866e331b2 78 would find them suitable for varied deployments of MQTT subscribers and / or
dflet 0:698866e331b2 79 publishers.
dflet 0:698866e331b2 80
dflet 0:698866e331b2 81 The following figure outlines the composition of the SL MQTT Client Layer.
dflet 0:698866e331b2 82
dflet 0:698866e331b2 83 * \image html ./sl_mqtt_client_view.png
dflet 0:698866e331b2 84
dflet 0:698866e331b2 85 * \section descrypt_sec Description
dflet 0:698866e331b2 86
dflet 0:698866e331b2 87 The SL MQTT Client Layer, in addition to providing services to the application,
dflet 0:698866e331b2 88 encompasses a RTOS task to handle the incoming messages from the server. Such
dflet 0:698866e331b2 89 a dedicated context to process the messages from the server facilitates the
dflet 0:698866e331b2 90 apps to receive data (i.e. PUBLISH messages) even when they are blocked, whilst
dflet 0:698866e331b2 91 awaiting ACK for a previous transaction with the server. The receive task in
dflet 0:698866e331b2 92 the SL MQTT Layer can not be disabled anytime, however its system wide priority
dflet 0:698866e331b2 93 is configurable and can be set.
dflet 0:698866e331b2 94
dflet 0:698866e331b2 95 Some of the salient features of the SL MQTT Layer are
dflet 0:698866e331b2 96
dflet 0:698866e331b2 97 - Easy-to-use, intuitive and small set of MQTT API
dflet 0:698866e331b2 98 - App can indicate its choice to await ACK for a message transaction
dflet 0:698866e331b2 99 - Supports MQTT 3.1 protocol
dflet 0:698866e331b2 100
dflet 0:698866e331b2 101 * \section config_sec Configuration
dflet 0:698866e331b2 102 The SL implementation enables the application developers to configure the
dflet 0:698866e331b2 103 following parameters using the compile line flags (-D option)
dflet 0:698866e331b2 104 * - <b> CFG_SL_CL_MAX_MQP: </b> the count of TX + RX resources in the buffer pool
dflet 0:698866e331b2 105 for the library to use. \n\n
dflet 0:698866e331b2 106 * - <b> CFG_SL_CL_BUF_LEN: </b> the length of the TX and RX buffers in the pool. \n\n
dflet 0:698866e331b2 107 * - <b> CFG_SL_CL_STACK: </b> Max stack (bytes) for RX Task executed by SL-MQTT. \n\n
dflet 0:698866e331b2 108 * - <b> CFG_CL_MQTT_CTXS: </b> the max number of simultaneous network connections
dflet 0:698866e331b2 109 to one or more servers. \n\n
dflet 0:698866e331b2 110
dflet 0:698866e331b2 111 * \section seq_sec Sequence Diagram
dflet 0:698866e331b2 112 The following sequence diagram outlines one of the possible usecases
dflet 0:698866e331b2 113 (Blocking APIs with QOS1) using the SL MQTT Client Layer
dflet 0:698866e331b2 114 * \image html ./sl_mqtt_client_seq.jpg
dflet 0:698866e331b2 115
dflet 0:698866e331b2 116 * \note An app that has chosen not to await an ACK from the server for an
dflet 0:698866e331b2 117 scheduled transaction can benefit from the availability of control to
dflet 0:698866e331b2 118 pursue other activities to make overall progress in the system. However,
dflet 0:698866e331b2 119 an attempt to schedule another transaction with the server, while the
dflet 0:698866e331b2 120 previous one is still active, will depend on the availability of buffers for transaction.
dflet 0:698866e331b2 121
dflet 0:698866e331b2 122
dflet 0:698866e331b2 123 \subsection seq_subsec Typical Sequences:
dflet 0:698866e331b2 124
dflet 0:698866e331b2 125 - Publishers: INIT --> CONTEXT_CREATE --> CONNECT --> PUBLISH (TX) --> DISCONNECT --> CONTEXT_DELETE --> EXIT
dflet 0:698866e331b2 126 - Subscribers: INIT --> CONTEXT_CREATE --> CONNECT --> SUBSCRIBE --> PUBLISH (RX) --> UNSUBSCRIBE --> DISCONNECT --> CONTEXT_DELETE --> EXIT
dflet 0:698866e331b2 127
dflet 0:698866e331b2 128 */
dflet 0:698866e331b2 129
dflet 0:698866e331b2 130 /** @defgroup sl_mqtt_cl_api SL MQTT Client API
dflet 0:698866e331b2 131 @{
dflet 0:698866e331b2 132 */
dflet 0:698866e331b2 133
dflet 0:698866e331b2 134 /** @defgroup sl_mqtt_cl_evt SL MQTT Client Events
dflet 0:698866e331b2 135 @{
dflet 0:698866e331b2 136 */
dflet 0:698866e331b2 137 #define SL_MQTT_CL_EVT_PUBACK 0x04 /**< PUBACK has been received from the server */
dflet 0:698866e331b2 138 #define SL_MQTT_CL_EVT_PUBCOMP 0x07 /**< PUBCOMP has been received from the server */
dflet 0:698866e331b2 139 #define SL_MQTT_CL_EVT_SUBACK 0x09 /**< SUBACK has been received from the server */
dflet 0:698866e331b2 140 #define SL_MQTT_CL_EVT_UNSUBACK 0x0B /**< UNSUBACK has been received from the server */
dflet 0:698866e331b2 141 /** @} */ /* End Client events */
dflet 0:698866e331b2 142
dflet 0:698866e331b2 143
dflet 0:698866e331b2 144 /* Define server structure which holds , server address and port number.
dflet 0:698866e331b2 145 These values are set by the sl_MqttSet API and retrieved by sl_MqttGet API*/
dflet 0:698866e331b2 146
dflet 0:698866e331b2 147 /** Callbacks Routines
dflet 0:698866e331b2 148 The routines are invoked by SL Implementation onto Client application
dflet 0:698866e331b2 149
dflet 0:698866e331b2 150 * \note The user applications implement the callbacks that are registered
dflet 0:698866e331b2 151 with the libraries. While using the MQTT library, invoking the
dflet 0:698866e331b2 152 core library APIs from a callback should be avoided and
dflet 0:698866e331b2 153 can lead to lockup scenarios. It is recommended to signal another
dflet 0:698866e331b2 154 task from the callback routines invoked from the library
dflet 0:698866e331b2 155 and invoke the core library API calls from that task.
dflet 0:698866e331b2 156 */
dflet 0:698866e331b2 157 typedef struct {
dflet 0:698866e331b2 158
dflet 0:698866e331b2 159 /** Callback routine to receive a PUBLISH from the server.
dflet 0:698866e331b2 160 The client app must provide this routine for the instances where it has
dflet 0:698866e331b2 161 subscribed to certain set of topics from the server. The callback is
dflet 0:698866e331b2 162 invoked in the context of the internal SL Receive Task.
dflet 0:698866e331b2 163
dflet 0:698866e331b2 164 \param[in] app_hndl application handle returned
dflet 0:698866e331b2 165 \param[in] topstr name of topic published by the server. Not NUL terminated.
dflet 0:698866e331b2 166 \param[in] toplen length of the topic name published by the server.
dflet 0:698866e331b2 167 \param[in] payload refers to payload published by the server.
dflet 0:698866e331b2 168 \param[in] pay_len length of the payload.
dflet 0:698866e331b2 169 \param[in] dup assert to indicate that it is re-send by the server
dflet 0:698866e331b2 170 \param[in] qoS quality of service of the published message
dflet 0:698866e331b2 171 \param[in] retain asserted to indicate that a retained message has been published
dflet 0:698866e331b2 172 \return none.
dflet 0:698866e331b2 173 */
dflet 0:698866e331b2 174 void (*sl_ExtLib_MqttRecv)(void *app_hndl, const char *topstr, int32_t toplen,
dflet 0:698866e331b2 175 const void *payload, int32_t pay_len,
dflet 0:698866e331b2 176 bool dup, unsigned char qos,
dflet 0:698866e331b2 177 bool retain);
dflet 0:698866e331b2 178
dflet 0:698866e331b2 179 /** Indication of event either from the server or implementation generated.
dflet 0:698866e331b2 180 These events are notified as part of the processing carried out by the
dflet 0:698866e331b2 181 internal recv task of the SL implementation. The application must populate
dflet 0:698866e331b2 182 the callback to receive events about the progress made by the SL Mqtt layer.
dflet 0:698866e331b2 183
dflet 0:698866e331b2 184 This handler is used by the SL Mqtt Layer to report acknowledgements from the
dflet 0:698866e331b2 185 server, in case, the application has chosen not to block the service invokes
dflet 0:698866e331b2 186 till the arrival of the corresponding ACK.
dflet 0:698866e331b2 187
dflet 0:698866e331b2 188 \param[in] app_hndl application handle returned
dflet 0:698866e331b2 189 \param[in] evt identifier to the reported event. Refer to @ref sl_mqtt_cl_evt
dflet 0:698866e331b2 190 \param[in] buf points to buffer
dflet 0:698866e331b2 191 \param[in] len length of buffer
dflet 0:698866e331b2 192
dflet 0:698866e331b2 193 \note
dflet 0:698866e331b2 194 */
dflet 0:698866e331b2 195 void (*sl_ExtLib_MqttEvent)(void *app_hndl, int32_t evt, const void *buf,
dflet 0:698866e331b2 196 uint32_t len);
dflet 0:698866e331b2 197
dflet 0:698866e331b2 198 /** Notifies the client app about the termination of MQTT connection.
dflet 0:698866e331b2 199 After servicing this callback, the client-app can destroy associated
dflet 0:698866e331b2 200 context if it no longer required
dflet 0:698866e331b2 201
dflet 0:698866e331b2 202 \param[in] app_hndl application handle returned
dflet 0:698866e331b2 203 */
dflet 0:698866e331b2 204 void (*sl_ExtLib_MqttDisconn)(void *app_hndl);
dflet 0:698866e331b2 205
dflet 0:698866e331b2 206
dflet 0:698866e331b2 207 } SlMqttClientCbs_t;
dflet 0:698866e331b2 208
dflet 0:698866e331b2 209 typedef struct {
dflet 0:698866e331b2 210
dflet 0:698866e331b2 211 const char *will_topic; /**< Will Topic */
dflet 0:698866e331b2 212 const char *will_msg; /**< Will message */
dflet 0:698866e331b2 213 char will_qos; /**< Will Qos */
dflet 0:698866e331b2 214 bool retain; /**< Retain Flag */
dflet 0:698866e331b2 215
dflet 0:698866e331b2 216 } SlMqttWill_t;
dflet 0:698866e331b2 217
dflet 0:698866e331b2 218
dflet 0:698866e331b2 219 /** Secure Socket Parameters to open a secure connection */
dflet 0:698866e331b2 220 /*
dflet 0:698866e331b2 221 Note: value of n_files can vary from 1 to 4, with corresponding pointers to
dflet 0:698866e331b2 222 the files in files field. Value of 1(n_files) will assume the corresponding
dflet 0:698866e331b2 223 pointer is for CA File Name. Any other value of n_files expects the files to
dflet 0:698866e331b2 224 be in following order:
dflet 0:698866e331b2 225 1. Private Key File
dflet 0:698866e331b2 226 2. Certificate File Name
dflet 0:698866e331b2 227 3. CA File Name
dflet 0:698866e331b2 228 4. DH Key File Name
dflet 0:698866e331b2 229
dflet 0:698866e331b2 230 example:
dflet 0:698866e331b2 231 If you want to provide only CA File Name, following are the two way of doing it:
dflet 0:698866e331b2 232 for n_files = 1
dflet 0:698866e331b2 233 char *security_file_list[] = {"/cert/testcacert.der"};
dflet 0:698866e331b2 234 for n_files = 4
dflet 0:698866e331b2 235 char *security_file_list[] = {NULL, NULL, "/cert/testcacert.der", NULL};
dflet 0:698866e331b2 236
dflet 0:698866e331b2 237 where secure_files = security_file_list
dflet 0:698866e331b2 238 */
dflet 0:698866e331b2 239 typedef struct {
dflet 0:698866e331b2 240
dflet 0:698866e331b2 241 #define SL_MQTT_NETCONN_IP6 0x04 /**< Assert for IPv6 connection, otherwise IPv4 */
dflet 0:698866e331b2 242 #define SL_MQTT_NETCONN_URL 0x08 /**< Server address is an URL and not IP address */
dflet 0:698866e331b2 243 #define SL_MQTT_NETCONN_SEC 0x10 /**< Connection to server must be secure (TLS) */
dflet 0:698866e331b2 244
dflet 0:698866e331b2 245 uint32_t netconn_flags; /**< Enumerate connection type */
dflet 0:698866e331b2 246 const char *server_addr; /**< Server Address: URL or IP */
dflet 0:698866e331b2 247 uint16_t port_number; /**< Port number of MQTT server */
dflet 0:698866e331b2 248 char method; /**< Method to tcp secured socket */
dflet 0:698866e331b2 249 uint32_t cipher; /**< Cipher to tcp secured socket */
dflet 0:698866e331b2 250 uint32_t n_files; /**< Number of files for secure transfer */
dflet 0:698866e331b2 251 char * const *secure_files; /* SL needs 4 files*/
dflet 0:698866e331b2 252
dflet 0:698866e331b2 253 } SlMqttServer_t;
dflet 0:698866e331b2 254
dflet 0:698866e331b2 255
dflet 0:698866e331b2 256 /** MQTT Lib structure which holds Initialization Data */
dflet 0:698866e331b2 257 typedef struct
dflet 0:698866e331b2 258 {
dflet 0:698866e331b2 259 /**< Loopback port is used to manage lib internal functioning in case of connections to
dflet 0:698866e331b2 260 multiple servers simultaneously is desired. */
dflet 0:698866e331b2 261 uint16_t loopback_port; /**< Loopback port = 0, implies connection to only single server */
dflet 0:698866e331b2 262 /**< Loopback port != 0, implies connection to multiple servers */
dflet 0:698866e331b2 263 uint32_t rx_tsk_priority; /**< Priority of the receive task */
dflet 0:698866e331b2 264 uint32_t resp_time; /**< Reasonable response time (seconds) from server */
dflet 0:698866e331b2 265 bool aux_debug_en; /**< Assert to indicate additional debug info */
dflet 0:698866e331b2 266 int32_t (*dbg_print)(const char *pcFormat, ...); /**< Print debug information */
dflet 0:698866e331b2 267
dflet 0:698866e331b2 268 } SlMqttClientLibCfg_t;
dflet 0:698866e331b2 269
dflet 0:698866e331b2 270
dflet 0:698866e331b2 271 /** MQTT client context configuration structure */
dflet 0:698866e331b2 272 typedef struct
dflet 0:698866e331b2 273 {
dflet 0:698866e331b2 274 SlMqttServer_t server_info; /**< Server information */
dflet 0:698866e331b2 275 bool mqtt_mode31; /**< Operate LIB in MQTT 3.1 mode; default is 3.1.1. false - default( 3.1.1) & true - 3.1) */
dflet 0:698866e331b2 276 bool blocking_send; /**< Select the mode of operation for send APIs (PUB, SUB, UNSUB). false - callback, true - blocking */
dflet 0:698866e331b2 277
dflet 0:698866e331b2 278 } SlMqttClientCtxCfg_t;
dflet 0:698866e331b2 279
dflet 0:698866e331b2 280 /** Initialize the SL MQTT Implementation.
dflet 0:698866e331b2 281 A caller must initialize the MQTT implementation prior to using its services.
dflet 0:698866e331b2 282
dflet 0:698866e331b2 283 \param[in] cfg refers to client lib configuration parameters
dflet 0:698866e331b2 284 \return Success (0) or Failure (-1)
dflet 0:698866e331b2 285 */
dflet 0:698866e331b2 286 int32_t sl_ExtLib_MqttClientInit(const SlMqttClientLibCfg_t *cfg);
dflet 0:698866e331b2 287
dflet 0:698866e331b2 288 /** Exit the SL MQTT Implementation.
dflet 0:698866e331b2 289
dflet 0:698866e331b2 290 \return Success (0) or Failure (-1)
dflet 0:698866e331b2 291 */
dflet 0:698866e331b2 292 int32_t sl_ExtLib_MqttClientExit();
dflet 0:698866e331b2 293
dflet 0:698866e331b2 294 /** Create a new client context to connect to a server.
dflet 0:698866e331b2 295 A context has to be created prior to invoking the client services.
dflet 0:698866e331b2 296
dflet 0:698866e331b2 297 \param[in] ctx_cfg refers to client context configuration parameters
dflet 0:698866e331b2 298 \param[in] msg_cbs refers to callbacks into application
dflet 0:698866e331b2 299 \param[in] app refers to the application callback to be returned on callback
dflet 0:698866e331b2 300 */
dflet 0:698866e331b2 301 void *sl_ExtLib_MqttClientCtxCreate(const SlMqttClientCtxCfg_t *ctx_cfg,
dflet 0:698866e331b2 302 const SlMqttClientCbs_t *msg_cbs,
dflet 0:698866e331b2 303 void *app_hndl);
dflet 0:698866e331b2 304
dflet 0:698866e331b2 305 /** Deletes the specified client context.
dflet 0:698866e331b2 306
dflet 0:698866e331b2 307 \param[in] cli_ctx refers to client context to be deleted
dflet 0:698866e331b2 308 \return Success (0) or Failure (< 0)
dflet 0:698866e331b2 309 */
dflet 0:698866e331b2 310 int32_t sl_ExtLib_MqttClientCtxDelete(void *cli_ctx);
dflet 0:698866e331b2 311
dflet 0:698866e331b2 312 /** @defgroup sl_mqtt_cl_params SL MQTT Oper Paramters
dflet 0:698866e331b2 313 @{
dflet 0:698866e331b2 314 */
dflet 0:698866e331b2 315 #define SL_MQTT_PARAM_CLIENT_ID 0x01 /**< Refers to Client ID */
dflet 0:698866e331b2 316 #define SL_MQTT_PARAM_USER_NAME 0x02 /**< User name of client */
dflet 0:698866e331b2 317 #define SL_MQTT_PARAM_PASS_WORD 0x03 /**< Pass-word of client */
dflet 0:698866e331b2 318 #define SL_MQTT_PARAM_TOPIC_QOS1 0x04 /**< Set a QoS1 SUB topic */
dflet 0:698866e331b2 319 #define SL_MQTT_PARAM_WILL_PARAM 0x05 /**< Set a WILL topic,Will Message, Will QOS,Will Retain */
dflet 0:698866e331b2 320
dflet 0:698866e331b2 321 /** @} */
dflet 0:698866e331b2 322
dflet 0:698866e331b2 323 /** Set parameters in SL MQTT implementation.
dflet 0:698866e331b2 324 The caller must configure these paramters prior to invoking any MQTT
dflet 0:698866e331b2 325 transaction.
dflet 0:698866e331b2 326
dflet 0:698866e331b2 327 \note The implementation does not copy the contents referred. Therefore,
dflet 0:698866e331b2 328 the caller must ensure that contents are persistent in the memory.
dflet 0:698866e331b2 329
dflet 0:698866e331b2 330 \param[in] cli_ctx refers to the handle to the client context
dflet 0:698866e331b2 331 \param[in] param identifies parameter to set. Refer to @ref sl_mqtt_cl_params
dflet 0:698866e331b2 332 \param[in] value refers to the place-holder of value to be set
dflet 0:698866e331b2 333 \param[in] len length of the value of the parameter
dflet 0:698866e331b2 334 \return Success (0) or Failure (-1)
dflet 0:698866e331b2 335 */
dflet 0:698866e331b2 336 int32_t sl_ExtLib_MqttClientSet(void *cli_ctx, int32_t param, const void *value, uint32_t len);
dflet 0:698866e331b2 337
dflet 0:698866e331b2 338 /*\brief None defined at the moment
dflet 0:698866e331b2 339 */
dflet 0:698866e331b2 340 int32_t sl_ExtLib_MqttClientGet(void *cli_ctx, int32_t param, void *value, uint32_t len);
dflet 0:698866e331b2 341
dflet 0:698866e331b2 342
dflet 0:698866e331b2 343 /** CONNECT to the server.
dflet 0:698866e331b2 344 This routine establishes a connection with the server for MQTT transactions.
dflet 0:698866e331b2 345 The caller should specify a time-period with-in which the implementation
dflet 0:698866e331b2 346 should send a message to the server to keep-alive the connection.
dflet 0:698866e331b2 347
dflet 0:698866e331b2 348 \param[in] cli_ctx refers to the handle to the client context
dflet 0:698866e331b2 349 \param[in] clean assert to make a clean start and purge the previous session
dflet 0:698866e331b2 350 \param[in] keep_alive_time the maximum time within which client should send
dflet 0:698866e331b2 351 a message to server. The unit of the interval is in seconds.
dflet 0:698866e331b2 352 \return on success, variable header of CONNACK message in network byte
dflet 0:698866e331b2 353 order. Lowest Byte[Byte0] contains CONNACK Return Code. Byte1 Contains
dflet 0:698866e331b2 354 Session Present Bit.
dflet 0:698866e331b2 355 on failure returns(-1)
dflet 0:698866e331b2 356 */
dflet 0:698866e331b2 357 int32_t sl_ExtLib_MqttClientConnect(void *cli_ctx, bool clean, uint16_t keep_alive_time);
dflet 0:698866e331b2 358
dflet 0:698866e331b2 359 /** DISCONNECT from the server.
dflet 0:698866e331b2 360 The caller must use this service to close the connection with the
dflet 0:698866e331b2 361 server.
dflet 0:698866e331b2 362
dflet 0:698866e331b2 363 \param[in] cli_ctx refers to the handle to the client context
dflet 0:698866e331b2 364
dflet 0:698866e331b2 365 \return Success (0) or Failure (< 0)
dflet 0:698866e331b2 366 */
dflet 0:698866e331b2 367 int32_t sl_ExtLib_MqttClientDisconnect(void *cli_ctx);
dflet 0:698866e331b2 368
dflet 0:698866e331b2 369
dflet 0:698866e331b2 370 /** SUBSCRIBE a set of topics.
dflet 0:698866e331b2 371 To receive data about a set of topics from the server, the app through
dflet 0:698866e331b2 372 this routine must subscribe to those topic names with the server. The
dflet 0:698866e331b2 373 caller can indicate whether the routine should block until a time, the
dflet 0:698866e331b2 374 message has been acknowledged by the server.
dflet 0:698866e331b2 375
dflet 0:698866e331b2 376 In case, the app has chosen not to await for the ACK from the server,
dflet 0:698866e331b2 377 the SL MQTT implementation will notify the app about the subscription
dflet 0:698866e331b2 378 through the callback routine.
dflet 0:698866e331b2 379
dflet 0:698866e331b2 380 \param[in] cli_ctx refers to the handle to the client context
dflet 0:698866e331b2 381 \param[in] topics set of topic names to subscribe. It is an array of
dflet 0:698866e331b2 382 pointers to NUL terminated strings.
dflet 0:698866e331b2 383 \param[in,out] qos array of qos values for each topic in the same order
dflet 0:698866e331b2 384 of the topic array. If configured to await for SUB-ACK from server, the
dflet 0:698866e331b2 385 array will contain qos responses for topics from the server.
dflet 0:698866e331b2 386 \param[in] count number of such topics
dflet 0:698866e331b2 387
dflet 0:698866e331b2 388 \return Success(transaction Message ID) or Failure(< 0)
dflet 0:698866e331b2 389 */
dflet 0:698866e331b2 390 int32_t sl_ExtLib_MqttClientSub(void *cli_ctx, char* const *topics,
dflet 0:698866e331b2 391 uint8_t *qos, int32_t count);
dflet 0:698866e331b2 392
dflet 0:698866e331b2 393
dflet 0:698866e331b2 394 /** UNSUBSCRIBE a set of topics.
dflet 0:698866e331b2 395 The app should use this service to stop receiving data for the named
dflet 0:698866e331b2 396 topics from the server. The caller can indicate whether the routine
dflet 0:698866e331b2 397 should block until a time, the message has been acknowleged by the
dflet 0:698866e331b2 398 server.
dflet 0:698866e331b2 399
dflet 0:698866e331b2 400 In case, the app has chosen not to await for the ACK from the server,
dflet 0:698866e331b2 401 the SL MQTT implementation will notify the app about the subscription
dflet 0:698866e331b2 402 through the callback routine.
dflet 0:698866e331b2 403
dflet 0:698866e331b2 404 \param[in] cli_ctx refers to the handle to the client context
dflet 0:698866e331b2 405 \param[in] topics set of topics to be unsubscribed. It is an array of
dflet 0:698866e331b2 406 pointers to NUL terminated strings.
dflet 0:698866e331b2 407 \param[in] count number of topics to be unsubscribed
dflet 0:698866e331b2 408
dflet 0:698866e331b2 409 \return Success(transaction Message ID) or Failure(< 0)
dflet 0:698866e331b2 410 */
dflet 0:698866e331b2 411 int32_t sl_ExtLib_MqttClientUnsub(void *cli_ctx, char* const *topics, int32_t count);
dflet 0:698866e331b2 412
dflet 0:698866e331b2 413
dflet 0:698866e331b2 414 /** PUBLISH a named message to the server.
dflet 0:698866e331b2 415 In addition to the PUBLISH specific parameters, the caller can indicate
dflet 0:698866e331b2 416 whether the routine should block until the time, the message has been
dflet 0:698866e331b2 417 acknowleged by the server. This is applicable only for non-QoS0 messages.
dflet 0:698866e331b2 418
dflet 0:698866e331b2 419 In case, the app has chosen not to await for the ACK from the server,
dflet 0:698866e331b2 420 the SL MQTT implementation will notify the app about the subscription
dflet 0:698866e331b2 421 through the callback routine.
dflet 0:698866e331b2 422
dflet 0:698866e331b2 423 \param[in] cli_ctx refers to the handle to the client context
dflet 0:698866e331b2 424 \param[in] topic topic of the data to be published. It is NULL terminated.
dflet 0:698866e331b2 425 \param[in] data binary data to be published
dflet 0:698866e331b2 426 \param[in] len length of the data
dflet 0:698866e331b2 427 \param[in] qos QoS for the publish message
dflet 0:698866e331b2 428 \param[in] retain assert if server should retain the message
dflet 0:698866e331b2 429 \param[in] flags Command flag. Refer to @ref sl_mqtt_cl_cmdflags
dflet 0:698866e331b2 430 \return Success(transaction Message ID) or Failure(< 0)
dflet 0:698866e331b2 431 */
dflet 0:698866e331b2 432 int32_t sl_ExtLib_MqttClientSend(void *cli_ctx, const char *topic,
dflet 0:698866e331b2 433 const void *data, int32_t len,
dflet 0:698866e331b2 434 char qos, bool retain);
dflet 0:698866e331b2 435
dflet 0:698866e331b2 436 /** PUBLISH a named message to the server - wrapper function.
dflet 0:698866e331b2 437 */
dflet 0:698866e331b2 438 static inline int32_t sl_ExtLib_MqttClientPub(void *cli_ctx, const char *topic,
dflet 0:698866e331b2 439 const void *data, int32_t len,
dflet 0:698866e331b2 440 char qos, bool retain)
dflet 0:698866e331b2 441 {
dflet 0:698866e331b2 442 return sl_ExtLib_MqttClientSend(cli_ctx, topic, data, len,
dflet 0:698866e331b2 443 qos, retain);
dflet 0:698866e331b2 444 }
dflet 0:698866e331b2 445
dflet 0:698866e331b2 446 /** @} */ /* End Client API */
dflet 0:698866e331b2 447
dflet 0:698866e331b2 448 }//namespace mbed_mqtt
dflet 0:698866e331b2 449
dflet 0:698866e331b2 450 #ifdef __cplusplus
dflet 0:698866e331b2 451 }
dflet 0:698866e331b2 452 #endif
dflet 0:698866e331b2 453
dflet 0:698866e331b2 454
dflet 0:698866e331b2 455
dflet 0:698866e331b2 456 #endif // __SL_MQTT_H__
dflet 0:698866e331b2 457