David Fletcher / client

Part of TI's mqtt

Dependents:   mqtt_V1 cc3100_Test_mqtt_CM3

mqtt_client.h@0:087b5655778d, 2015-06-06 (annotated)

Committer:
dflet
Date:
Sat Jun 06 13:28:41 2015 +0000
Revision:
0:087b5655778d
Part of mtqq_V1

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dflet 0:087b5655778d 1
dflet 0:087b5655778d 2 /******************************************************************************
dflet 0:087b5655778d 3 *
dflet 0:087b5655778d 4 * Copyright (C) 2014 Texas Instruments Incorporated
dflet 0:087b5655778d 5 *
dflet 0:087b5655778d 6 * All rights reserved. Property of Texas Instruments Incorporated.
dflet 0:087b5655778d 7 * Restricted rights to use, duplicate or disclose this code are
dflet 0:087b5655778d 8 * granted through contract.
dflet 0:087b5655778d 9 *
dflet 0:087b5655778d 10 * The program may not be used without the written permission of
dflet 0:087b5655778d 11 * Texas Instruments Incorporated or against the terms and conditions
dflet 0:087b5655778d 12 * stipulated in the agreement under which this program has been supplied,
dflet 0:087b5655778d 13 * and under no circumstances can it be used with non-TI connectivity device.
dflet 0:087b5655778d 14 *
dflet 0:087b5655778d 15 ******************************************************************************/
dflet 0:087b5655778d 16
dflet 0:087b5655778d 17 /*
dflet 0:087b5655778d 18 mqtt_client.h
dflet 0:087b5655778d 19
dflet 0:087b5655778d 20 This module enumerates the public interfaces / API of the MQTT Client
dflet 0:087b5655778d 21 Library.
dflet 0:087b5655778d 22 */
dflet 0:087b5655778d 23
dflet 0:087b5655778d 24
dflet 0:087b5655778d 25 #ifndef __MQTT_CLIENT_H__
dflet 0:087b5655778d 26 #define __MQTT_CLIENT_H__
dflet 0:087b5655778d 27
dflet 0:087b5655778d 28 /**@file mqtt_client.h
dflet 0:087b5655778d 29 This C library provisions the interface / API(s) for the MQTT Client.
dflet 0:087b5655778d 30
dflet 0:087b5655778d 31 This is a light-weight library to enable the services of the MQTT protocol
dflet 0:087b5655778d 32 for one or more client applications (that would typically run on a resource
dflet 0:087b5655778d 33 constrained system). The key consideration in the design of small footprint
dflet 0:087b5655778d 34 library has been the abstraction of the low level details of the message
dflet 0:087b5655778d 35 transactions with the server and yet, provide rudimentary API(s), such that,
dflet 0:087b5655778d 36 the capabilities and features of the protocol are availalbe to be utilized
dflet 0:087b5655778d 37 by existing and new applications in an un-restrictive manner.
dflet 0:087b5655778d 38
dflet 0:087b5655778d 39 The library is targeted to conform to MQTT 3.1.1 specification.
dflet 0:087b5655778d 40
dflet 0:087b5655778d 41 The MQTT Client library is a highly portable software and implies a very
dflet 0:087b5655778d 42 limited set of dependencies on a platform. Importantly, these limited
dflet 0:087b5655778d 43 dependencies are the commonly used features used in the embedded and the
dflet 0:087b5655778d 44 networking world, and can be easily adapted to the target platforms.
dflet 0:087b5655778d 45
dflet 0:087b5655778d 46 The services of the library are multi-task safe. Platform specific atomicity
dflet 0:087b5655778d 47 constructs are used, through abstractions, by the library to maintain data
dflet 0:087b5655778d 48 coherency and synchronization. In addition, the library can be configured to
dflet 0:087b5655778d 49 support several in-flight messages.
dflet 0:087b5655778d 50
dflet 0:087b5655778d 51 The client library supports multiple and simultaneous MQTT connections to one
dflet 0:087b5655778d 52 or more servers. In this client LIB, the reference to an individual connection
dflet 0:087b5655778d 53 in conjunction with the associated configuration parameters has been termed as
dflet 0:087b5655778d 54 a 'context'. Therefore, the client library supports multiple 'contexts'. An
dflet 0:087b5655778d 55 application that intends to make use of the client library must set-up or
dflet 0:087b5655778d 56 create a 'context' prior to establishing a connection with the server. The
dflet 0:087b5655778d 57 application can choose to destroy the 'context' after the connection with the
dflet 0:087b5655778d 58 server has been terminated. The client LIB can only support a finite set of
dflet 0:087b5655778d 59 'contexts' and the number can be configured by using a compiler line option /
dflet 0:087b5655778d 60 flag <b> -DCFG_CL_MQTT_CTXS </b>.
dflet 0:087b5655778d 61
dflet 0:087b5655778d 62 Once, the 'context' is set-up, the application can send and receive the MQTT
dflet 0:087b5655778d 63 packets to / from the server. Among several features supported by the client
dflet 0:087b5655778d 64 LIB, the 'context' manages the keep-alive mechanism by automatically sending
dflet 0:087b5655778d 65 PING request to the server, if there has been no other packet send to the
dflet 0:087b5655778d 66 server with the keep-alive duration.
dflet 0:087b5655778d 67
dflet 0:087b5655778d 68 @note Any future extensions & development must follow the following guidelines.
dflet 0:087b5655778d 69 A new API or an extension to the existing API
dflet 0:087b5655778d 70 a) must be rudimentary
dflet 0:087b5655778d 71 b) must not imply a rule or policy (including a state machine)
dflet 0:087b5655778d 72 b) must ensure simple design and implementation
dflet 0:087b5655778d 73
dflet 0:087b5655778d 74 */
dflet 0:087b5655778d 75
dflet 0:087b5655778d 76 #include "mqtt_common.h"
dflet 0:087b5655778d 77
dflet 0:087b5655778d 78 #ifdef __cplusplus
dflet 0:087b5655778d 79 extern "C"
dflet 0:087b5655778d 80 {
dflet 0:087b5655778d 81 #endif
dflet 0:087b5655778d 82
dflet 0:087b5655778d 83 namespace mbed_mqtt {
dflet 0:087b5655778d 84
dflet 0:087b5655778d 85 /*------------------------------------------------------------------------------
dflet 0:087b5655778d 86 * MQTT Client Messaging Routines / Services
dflet 0:087b5655778d 87 *------------------------------------------------------------------------------
dflet 0:087b5655778d 88 */
dflet 0:087b5655778d 89
dflet 0:087b5655778d 90 /** @defgroup client_api The Client Library API(s)
dflet 0:087b5655778d 91 @{
dflet 0:087b5655778d 92 */
dflet 0:087b5655778d 93
dflet 0:087b5655778d 94 #define MQTT_CLIENT_VERSTR "1.0.3" /**< Version of Client LIB */
dflet 0:087b5655778d 95
dflet 0:087b5655778d 96 void createMutex(void);
dflet 0:087b5655778d 97
dflet 0:087b5655778d 98 static int32_t grp_net_setup_create(void);
dflet 0:087b5655778d 99
dflet 0:087b5655778d 100 /** Provides a new MSG Identifier for a packet dispatch to server
dflet 0:087b5655778d 101
dflet 0:087b5655778d 102 @return MSG / PKT Transaction identifier
dflet 0:087b5655778d 103 */
dflet 0:087b5655778d 104 uint16_t mqtt_client_new_msg_id(void);
dflet 0:087b5655778d 105
dflet 0:087b5655778d 106 /** Ascertain whether connection / session with the server is active or not.
dflet 0:087b5655778d 107 Prior to sending out any information any message to server, the application
dflet 0:087b5655778d 108 can use this routine to check the status of the connection. If connection
dflet 0:087b5655778d 109 does not exist, then client should first CONNECT to the broker.
dflet 0:087b5655778d 110
dflet 0:087b5655778d 111 A connection to server could have been closed unsolicitedly either due to
dflet 0:087b5655778d 112 keep alive time-out or due to error in RX / TX transactions.
dflet 0:087b5655778d 113
dflet 0:087b5655778d 114 @note this API does not refer to network layer connection
dflet 0:087b5655778d 115
dflet 0:087b5655778d 116 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 117 @see mqtt_client_ctx_create
dflet 0:087b5655778d 118
dflet 0:087b5655778d 119 @return true if connection is active otherwise false.
dflet 0:087b5655778d 120 */
dflet 0:087b5655778d 121 bool mqtt_client_is_connected(void *ctx);
dflet 0:087b5655778d 122
dflet 0:087b5655778d 123 /** Send the CONNECT message to the server (and don't wait for CONNACK).
dflet 0:087b5655778d 124 This routine accomplishes multiple sequences. As a first step, it tries
dflet 0:087b5655778d 125 to establish a network connection with the server. Then, it populates
dflet 0:087b5655778d 126 an internaly allocated packet buffer with all the previously provided
dflet 0:087b5655778d 127 payload data information, prepares the requisite headers and finally,
dflet 0:087b5655778d 128 dispatches the constructed message to the server.
dflet 0:087b5655778d 129
dflet 0:087b5655778d 130 Prior to invoking this service, the client application should provision the
dflet 0:087b5655778d 131 intended payload contents of the CONNECT message by using the API(s) @ref
dflet 0:087b5655778d 132 mqtt_client_ctx_info_register and @ref mqtt_client_ctx_will_register. And
dflet 0:087b5655778d 133 information about the server of interest must be provided in the client LIB
dflet 0:087b5655778d 134 'context' creation (@ref mqtt_client_ctx_create).
dflet 0:087b5655778d 135
dflet 0:087b5655778d 136 The client application must invoke an appropriate receive routine to know
dflet 0:087b5655778d 137 about the corresponding response CONNACK from the server. The client LIB will
dflet 0:087b5655778d 138 close the network connection to the server, if the server happens to refuse
dflet 0:087b5655778d 139 the CONNECT request.
dflet 0:087b5655778d 140
dflet 0:087b5655778d 141 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 142 @see mqtt_client_ctx_create
dflet 0:087b5655778d 143 @param[in] clean_session asserted to delete references to previous session
dflet 0:087b5655778d 144 at both server and client
dflet 0:087b5655778d 145 @param[in] ka_secs Keep Alive Time
dflet 0:087b5655778d 146 @return number of bytes sent or LIB defined errors (@ref lib_err_group)
dflet 0:087b5655778d 147 */
dflet 0:087b5655778d 148 int32_t mqtt_connect_msg_send(void *ctx, bool clean_session, uint16_t ka_secs);
dflet 0:087b5655778d 149
dflet 0:087b5655778d 150 /** Send a PUBLISH message to the server (don't wait for PUBACK / PUBREC).
dflet 0:087b5655778d 151 This routine creates a PUBLISH message in an internally allocated packet
dflet 0:087b5655778d 152 buffer by embedding the 'topic' and 'data' contents, then prepares the
dflet 0:087b5655778d 153 packet header and finally, dispatches the message to the server.
dflet 0:087b5655778d 154
dflet 0:087b5655778d 155 After the packet has been sent to the server, if the associated QoS of the
dflet 0:087b5655778d 156 dispatched packet is ether level 1 or 2, the client LIB 'context' will then
dflet 0:087b5655778d 157 store the packet until the time, a corresponding PUB-ACK (for QoS1) or
dflet 0:087b5655778d 158 PUB-REC (QoS2) message is received from the server.
dflet 0:087b5655778d 159
dflet 0:087b5655778d 160 If the client LIB 'context' has been configured to assert 'clean session',
dflet 0:087b5655778d 161 then the references to all the stored and unacknowledged PUBLISH messages
dflet 0:087b5655778d 162 are dropped at the time of MQTT disconnection (or network disconnection).
dflet 0:087b5655778d 163 Otherwise, these unacknowledged packets continue to be availalbe for the
dflet 0:087b5655778d 164 next iteration of the MQTT connection. However, if the client application
dflet 0:087b5655778d 165 asserts the 'clean session' parameter in the next iteration of the CONNECT
dflet 0:087b5655778d 166 operation, then references to all the stored PUBLISH messages, if any, are
dflet 0:087b5655778d 167 dropped.
dflet 0:087b5655778d 168
dflet 0:087b5655778d 169 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 170 @see mqtt_client_ctx_create
dflet 0:087b5655778d 171 @param[in] topic UTF8 based Topic Name for which data is being published.
dflet 0:087b5655778d 172 @param[in] data_buf The binary data that is being published for the topic.
dflet 0:087b5655778d 173 @param[in] data_len The length of the binary data.
dflet 0:087b5655778d 174 @param[in] qos quality of service of the message
dflet 0:087b5655778d 175 @param[in] retain should the server retain the message.
dflet 0:087b5655778d 176 @return on success, a transaction message id otherwise, LIB defined errors
dflet 0:087b5655778d 177 (@ref lib_err_group)
dflet 0:087b5655778d 178 */
dflet 0:087b5655778d 179 int32_t mqtt_client_pub_msg_send(void *ctx,
dflet 0:087b5655778d 180 const struct utf8_string *topic,
dflet 0:087b5655778d 181 const uint8_t *data_buf, uint32_t data_len,
dflet 0:087b5655778d 182 enum mqtt_qos qos, bool retain);
dflet 0:087b5655778d 183
dflet 0:087b5655778d 184 /** Dispatch application constructed PUBLISH message to the server.
dflet 0:087b5655778d 185 Prior to sending the message to the server, this routine will prepare a fixed
dflet 0:087b5655778d 186 header to account for the size of the contents and the flags that have been
dflet 0:087b5655778d 187 indicated by the caller.
dflet 0:087b5655778d 188
dflet 0:087b5655778d 189 After the packet has been sent to the server, if the associated QoS of the
dflet 0:087b5655778d 190 dispatched packet is ether level 1 or 2, the client LIB 'context' will then
dflet 0:087b5655778d 191 store the packet until the time, a corresponding PUB-ACK (for QoS1) or
dflet 0:087b5655778d 192 PUB-REC (QoS2) message is received from the server.
dflet 0:087b5655778d 193
dflet 0:087b5655778d 194 If the client LIB 'context' has been configured to assert 'clean session',
dflet 0:087b5655778d 195 then the references to all the stored and unacknowledged PUBLISH messages
dflet 0:087b5655778d 196 are dropped at the time of MQTT disconnection (or network disconnection).
dflet 0:087b5655778d 197 Otherwise, these unacknowledged packets continue to be availalbe for the
dflet 0:087b5655778d 198 next iteration of the MQTT connection. However, if the client application
dflet 0:087b5655778d 199 asserts the 'clean session' parameter in the next iteration of the CONNECT
dflet 0:087b5655778d 200 operation, then references to all the stored PUBLISH messages, if any, are
dflet 0:087b5655778d 201 dropped.
dflet 0:087b5655778d 202
dflet 0:087b5655778d 203 The caller must populate the payload information with topic and data before
dflet 0:087b5655778d 204 invoking this service.
dflet 0:087b5655778d 205
dflet 0:087b5655778d 206 This service facilitates direct writing of topic and (real-time) payload data
dflet 0:087b5655778d 207 into the buffer, thereby, avoiding power consuming and wasteful intermediate
dflet 0:087b5655778d 208 data copies.
dflet 0:087b5655778d 209
dflet 0:087b5655778d 210 In case, the routine returns an error, the caller is responsbile for freeing
dflet 0:087b5655778d 211 up or re-using the packet buffer. For all other cases, the client library
dflet 0:087b5655778d 212 will manage the return of the packet buffer to the pool.
dflet 0:087b5655778d 213
dflet 0:087b5655778d 214 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 215 @see mqtt_client_ctx_create
dflet 0:087b5655778d 216 @param[in] mqp app created PUBLISH message without the fixed header
dflet 0:087b5655778d 217 @param[in] qos QoS with which the message needs to send to server
dflet 0:087b5655778d 218 @param[in] retain Asserted if the message is to be retained by server.
dflet 0:087b5655778d 219 @return on success, the transaction Message ID, otherwise LIB defined errors
dflet 0:087b5655778d 220 (@ref lib_err_group)
dflet 0:087b5655778d 221 */
dflet 0:087b5655778d 222 int32_t mqtt_client_pub_dispatch(void *ctx, struct mqtt_packet *mqp,
dflet 0:087b5655778d 223 enum mqtt_qos qos, bool retain);
dflet 0:087b5655778d 224
dflet 0:087b5655778d 225 /** Send a SUBSCRIBE message to the server (and don't wait for SUBACK).
dflet 0:087b5655778d 226 This routine creates a SUBSCRIBE message in an internally allocated packet
dflet 0:087b5655778d 227 buffer by embedding the 'qos_topics', then prepares the message header and
dflet 0:087b5655778d 228 finally, dispatches the packet to the server.
dflet 0:087b5655778d 229
dflet 0:087b5655778d 230 After the packet has been dispatched to the server, the library will store
dflet 0:087b5655778d 231 the packet until the time, a corresponding SUB-ACK has been received from
dflet 0:087b5655778d 232 the server. This mechanism enables the client LIB 'context' to trace the
dflet 0:087b5655778d 233 sequence of the message-ID and / or resend the SUB packets to the server.
dflet 0:087b5655778d 234
dflet 0:087b5655778d 235 The client LIB 'context', if configured to operate in the MQTT 3.1.1 mode
dflet 0:087b5655778d 236 will drop or remove the un-acknowledged SUB messages at the time of the
dflet 0:087b5655778d 237 termination of the network connection.
dflet 0:087b5655778d 238
dflet 0:087b5655778d 239 In the MQTT 3.1 mode, the client LIB 'context' will remove the unacknowledged
dflet 0:087b5655778d 240 SUB messages at the time of the termination of the network connection, if the
dflet 0:087b5655778d 241 'clean session' has been asserted. In case, the 'clean session' has not been
dflet 0:087b5655778d 242 asserted, the stored SUB messages will continue to be available for the next
dflet 0:087b5655778d 243 iteration of the MQTT connection. However, if the client application asserts
dflet 0:087b5655778d 244 the 'clean session' parameter in the next iteration of the CONNECT operation,
dflet 0:087b5655778d 245 then references to all the stored SUBSCRIBE messages, if any, are dropped.
dflet 0:087b5655778d 246
dflet 0:087b5655778d 247 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 248 @see mqtt_client_ctx_create
dflet 0:087b5655778d 249 @param[in] qos_topics an array of topic along-with its qos
dflet 0:087b5655778d 250 @param[in] count the number of elements in the array
dflet 0:087b5655778d 251 @return on success, the transaction Message ID, otherwise Lib defined errors
dflet 0:087b5655778d 252 (@ref lib_err_group)
dflet 0:087b5655778d 253 */
dflet 0:087b5655778d 254 int32_t mqtt_sub_msg_send(void *ctx, const struct utf8_strqos *qos_topics, uint32_t count);
dflet 0:087b5655778d 255
dflet 0:087b5655778d 256 /** Dispatch application constructed SUSBSCRIBE message to the server.
dflet 0:087b5655778d 257 Prior to sending the message to the server, this routine will prepare a fixed
dflet 0:087b5655778d 258 header to account for the size of the size of the contents.
dflet 0:087b5655778d 259
dflet 0:087b5655778d 260 After the packet has been dispatched to the server, the library will store
dflet 0:087b5655778d 261 the packet until the time, a corresponding SUB-ACK has been received from
dflet 0:087b5655778d 262 the server. This mechanism enables the client LIB 'context' to trace the
dflet 0:087b5655778d 263 sequence of the message-ID and / or resend the SUB packets to the server.
dflet 0:087b5655778d 264
dflet 0:087b5655778d 265 The client LIB 'context', if configured to operate in the MQTT 3.1.1 mode
dflet 0:087b5655778d 266 will drop or remove the un-acknowledged SUB messages at the time of the
dflet 0:087b5655778d 267 termination of the network connection.
dflet 0:087b5655778d 268
dflet 0:087b5655778d 269 In the MQTT 3.1 mode, the client LIB 'context' will remove the unacknowledged
dflet 0:087b5655778d 270 SUB messages at the time of the termination of the network connection, if the
dflet 0:087b5655778d 271 'clean session' has been asserted. In case, the 'clean session' has not been
dflet 0:087b5655778d 272 asserted, the stored SUB messages will continue to be available for the next
dflet 0:087b5655778d 273 iteration of the MQTT connection. However, if the client application asserts
dflet 0:087b5655778d 274 the 'clean session' parameter in the next iteration of the CONNECT operation,
dflet 0:087b5655778d 275 then references to all the stored SUBSCRIBE messages, if any, are dropped.
dflet 0:087b5655778d 276
dflet 0:087b5655778d 277 The caller must populate the payload information of topic along with qos
dflet 0:087b5655778d 278 before invoking this service.
dflet 0:087b5655778d 279
dflet 0:087b5655778d 280 This service facilitates direct writing of topic and (real-time) payload data
dflet 0:087b5655778d 281 into the buffer, thereby, avoiding power consuming and wasteful intermediate
dflet 0:087b5655778d 282 data copies.
dflet 0:087b5655778d 283
dflet 0:087b5655778d 284 In case, the routine returns an error, the caller is responsbile for freeing
dflet 0:087b5655778d 285 up or re-using the packet buffer. For all other cases, the client library
dflet 0:087b5655778d 286 will manage the return of the packet buffer to the pool.
dflet 0:087b5655778d 287
dflet 0:087b5655778d 288 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 289 @see mqtt_client_ctx_create
dflet 0:087b5655778d 290 @param[in] mqp app created SUBSCRIBE message without the fixed header.
dflet 0:087b5655778d 291 @return on success, the transaction Message ID, otherwise Lib defined errors
dflet 0:087b5655778d 292 (@ref lib_err_group)
dflet 0:087b5655778d 293 */
dflet 0:087b5655778d 294 int32_t mqtt_sub_dispatch(void *ctx, struct mqtt_packet *mqp);
dflet 0:087b5655778d 295
dflet 0:087b5655778d 296 /** Send an UNSUBSCRIBE message to the server (and don't wait for UNSUBACK).
dflet 0:087b5655778d 297 This routine creates an UNSUBSCRIBE message in an internally allocated packet
dflet 0:087b5655778d 298 buffer by embedding the 'topics', then prepares the message header and
dflet 0:087b5655778d 299 finally, dispatches the packet to the server.
dflet 0:087b5655778d 300
dflet 0:087b5655778d 301 After the packet has been dispatched to the server, the library will store
dflet 0:087b5655778d 302 the packet until the time, a corresponding UNSUB-ACK has been received from
dflet 0:087b5655778d 303 the server. This mechanism enables the client LIB 'context' to trace the
dflet 0:087b5655778d 304 sequence of the message-ID and / or resend the UNSUB packets to the server.
dflet 0:087b5655778d 305
dflet 0:087b5655778d 306 The client LIB 'context', if configured to operate in the MQTT 3.1.1 mode
dflet 0:087b5655778d 307 will drop or remove the un-acknowledged SUB messages at the time of the
dflet 0:087b5655778d 308 termination of the network connection.
dflet 0:087b5655778d 309
dflet 0:087b5655778d 310 In the MQTT 3.1 mode, the client LIB 'context' will remove the unacknowledged
dflet 0:087b5655778d 311 UNSUB messages at the time of the termination of the network connection, if
dflet 0:087b5655778d 312 the 'clean session' has been asserted. In case, the 'clean session' has not
dflet 0:087b5655778d 313 been asserted, the stored UNSUB messages will continue to be available for
dflet 0:087b5655778d 314 the next iteration of the MQTT connection. However, if the client application
dflet 0:087b5655778d 315 asserts the 'clean session' parameter in the next iteration of the CONNECT
dflet 0:087b5655778d 316 operation, then references to all the stored UNSUBSCRIBE messages, if any,
dflet 0:087b5655778d 317 are dropped.
dflet 0:087b5655778d 318
dflet 0:087b5655778d 319 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 320 @see mqtt_client_ctx_create
dflet 0:087b5655778d 321 @param[in] topics an array of topic to unsubscribe
dflet 0:087b5655778d 322 @param[in] count the number of elements in the array
dflet 0:087b5655778d 323 @return on success, the transaction Message ID, otherwise Lib defined errors
dflet 0:087b5655778d 324 (@ref lib_err_group)
dflet 0:087b5655778d 325 */
dflet 0:087b5655778d 326 int32_t mqtt_unsub_msg_send(void *ctx, const struct utf8_string *topics, uint32_t count);
dflet 0:087b5655778d 327
dflet 0:087b5655778d 328 /** Dispatch application constructed UNSUSBSCRIBE message to the server.
dflet 0:087b5655778d 329 Prior to sending the message to the server, this routine will prepare a fixed
dflet 0:087b5655778d 330 header to account for the size of the size of the contents.
dflet 0:087b5655778d 331
dflet 0:087b5655778d 332 After the packet has been dispatched to the server, the library will store
dflet 0:087b5655778d 333 the packet until the time, a corresponding UNSUB-ACK has been received from
dflet 0:087b5655778d 334 the server. This mechanism enables the client LIB 'context' to trace the
dflet 0:087b5655778d 335 sequence of the message-ID and / or resend the UNSUB packets to the server.
dflet 0:087b5655778d 336
dflet 0:087b5655778d 337 The client LIB 'context', if configured to operate in the MQTT 3.1.1 mode
dflet 0:087b5655778d 338 will drop or remove the un-acknowledged SUB messages at the time of the
dflet 0:087b5655778d 339 termination of the network connection.
dflet 0:087b5655778d 340
dflet 0:087b5655778d 341 In the MQTT 3.1 mode, the client LIB 'context' will remove the unacknowledged
dflet 0:087b5655778d 342 UNSUB messages at the time of the termination of the network connection, if
dflet 0:087b5655778d 343 the 'clean session' has been asserted. In case, the 'clean session' has not
dflet 0:087b5655778d 344 been asserted, the stored UNSUB messages will continue to be available for
dflet 0:087b5655778d 345 the next iteration of the MQTT connection. However, if the client application
dflet 0:087b5655778d 346 asserts the 'clean session' parameter in the next iteration of the CONNECT
dflet 0:087b5655778d 347 operation, then references to all the stored UNSUBSCRIBE messages, if any,
dflet 0:087b5655778d 348 are dropped.
dflet 0:087b5655778d 349
dflet 0:087b5655778d 350 The caller must populate the payload information of topics before invoking
dflet 0:087b5655778d 351 this service.
dflet 0:087b5655778d 352
dflet 0:087b5655778d 353 This service facilitates direct writing of topic and (real-time) payload data
dflet 0:087b5655778d 354 into the buffer, thereby, avoiding power consuming and wasteful intermediate
dflet 0:087b5655778d 355 data copies.
dflet 0:087b5655778d 356
dflet 0:087b5655778d 357 In case, the routine returns an error, the caller is responsbile for freeing
dflet 0:087b5655778d 358 up or re-using the packet buffer. For all other cases, the client library
dflet 0:087b5655778d 359 will manage the return of the packet buffer to the pool.
dflet 0:087b5655778d 360
dflet 0:087b5655778d 361 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 362 @see mqtt_client_ctx_create
dflet 0:087b5655778d 363 @param[in] Packet Buffer that holds UNSUBSCRIBE message without a fixed header
dflet 0:087b5655778d 364 @return on success, the transaction Message ID, otherwise LIB defined errors
dflet 0:087b5655778d 365 (@ref lib_err_group)
dflet 0:087b5655778d 366 */
dflet 0:087b5655778d 367 int32_t mqtt_unsub_dispatch(void *ctx, struct mqtt_packet *mqp);
dflet 0:087b5655778d 368
dflet 0:087b5655778d 369 /** Send a PINGREQ message to the server (and don't wait for PINGRSP).
dflet 0:087b5655778d 370
dflet 0:087b5655778d 371 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 372 @see mqtt_client_ctx_create
dflet 0:087b5655778d 373 @return number of bytes sent or Lib define errors (@ref lib_err_group)
dflet 0:087b5655778d 374 */
dflet 0:087b5655778d 375
dflet 0:087b5655778d 376 int32_t mqtt_pingreq_send(void *ctx);
dflet 0:087b5655778d 377
dflet 0:087b5655778d 378 /** Send a DISCONNECT message to the server.
dflet 0:087b5655778d 379
dflet 0:087b5655778d 380 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 381 @see mqtt_client_ctx_create
dflet 0:087b5655778d 382 @return number of bytes sent or Lib define errors (@ref lib_err_group)
dflet 0:087b5655778d 383 */
dflet 0:087b5655778d 384 int32_t mqtt_disconn_send(void *ctx);
dflet 0:087b5655778d 385
dflet 0:087b5655778d 386
dflet 0:087b5655778d 387 /** Send remaining data or contents of the scheduled message to the server.
dflet 0:087b5655778d 388 This routine tries to send the remaining data in an active transfer of a
dflet 0:087b5655778d 389 message to the server. This service is valid, only if the network layer of
dflet 0:087b5655778d 390 the platform is not able to send out the entire message in one TCP packet
dflet 0:087b5655778d 391 and has to "back-off" or "give up the control" before it can schedule or
dflet 0:087b5655778d 392 dispatch the next packet. In such a scenario, the network layer sends the
dflet 0:087b5655778d 393 first part (segment) of the scheduled message in the mqtt_xxx_send() API and
dflet 0:087b5655778d 394 the subsequent parts or the segments are sent using this routine.
dflet 0:087b5655778d 395
dflet 0:087b5655778d 396 This routine is not applicable to the platforms or the scenarios, where the
dflet 0:087b5655778d 397 implementation of the platform can segment the MQTT message in a manner to
dflet 0:087b5655778d 398 schedule consercutive or back-to-back blocking socket transactions.
dflet 0:087b5655778d 399 Specifically, this API must be used by an application, only if the network
dflet 0:087b5655778d 400 layer can indicate in an asynchronous manner, its readiness to send the next
dflet 0:087b5655778d 401 packet to the server. And the mechanism to indicate readiness of the network
dflet 0:087b5655778d 402 layer for the next send transaction is out of band and out of scope for the
dflet 0:087b5655778d 403 Client LIB and depends on the platform.
dflet 0:087b5655778d 404
dflet 0:087b5655778d 405 A platform that resorts to partial send of a message and has to back-off from
dflet 0:087b5655778d 406 transmission implies the following the considerations on to the application.
dflet 0:087b5655778d 407 (a) The next segment / part of the currently active MQTT packet can be sent
dflet 0:087b5655778d 408 or scheduled only after receiving the indication, to do so, from the network
dflet 0:087b5655778d 409 layer.
dflet 0:087b5655778d 410 (b) The next or new MQTT message (or its first segment) can be scheduled for
dflet 0:087b5655778d 411 transmission only after receiving the indication for completion of handling
dflet 0:087b5655778d 412 of the last segment of currently active message.
dflet 0:087b5655778d 413
dflet 0:087b5655778d 414 @note The application developer should refer to the platform specific network
dflet 0:087b5655778d 415 implementation for details.
dflet 0:087b5655778d 416
dflet 0:087b5655778d 417 The routine returns the number of remaining bytes in the message to be sent.
dflet 0:087b5655778d 418 However, as described earlier, the application is expected to wait for an
dflet 0:087b5655778d 419 indication about the readiness of the network layer prior to sending or
dflet 0:087b5655778d 420 scheduling another segment, if so available, to the server. Now, the new
dflet 0:087b5655778d 421 segment can be a next part of the currently active message or it can be the
dflet 0:087b5655778d 422 first segment of a new message. A return value of zero means that there is
dflet 0:087b5655778d 423 no more data left in the scheduled message to be sent to the server and the
dflet 0:087b5655778d 424 application should wait for an appropriate event to indicate the transmission
dflet 0:087b5655778d 425 of the last segment.
dflet 0:087b5655778d 426
dflet 0:087b5655778d 427 In case of an error, the transfer of the remaining segments or parts of the
dflet 0:087b5655778d 428 scheduled message is aborted. Depending on the configuration of the 'clean
dflet 0:087b5655778d 429 session' in-conjunction with the revision of the MQTT protocol, the active
dflet 0:087b5655778d 430 message would be stored for re-transmission, MQTT connection is established
dflet 0:087b5655778d 431 again. To store a message for re-transmission, at least one segment of the
dflet 0:087b5655778d 432 message must have been successfully sent to the server.
dflet 0:087b5655778d 433
dflet 0:087b5655778d 434 @note This API must be used by the application only if the platform has the
dflet 0:087b5655778d 435 capability to indicate the completion of the sending of an active segment.
dflet 0:087b5655778d 436
dflet 0:087b5655778d 437 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 438 @see mqtt_client_ctx_create
dflet 0:087b5655778d 439 @return the number of bytes remaining to be sent in the message. Otherwise,
dflet 0:087b5655778d 440 LIB defined errors (@ref lib_err_group)
dflet 0:087b5655778d 441 */
dflet 0:087b5655778d 442 int32_t mqtt_client_send_progress(void *ctx);
dflet 0:087b5655778d 443
dflet 0:087b5655778d 444 /** Block on the 'context' to receive a message type with-in specified wait time.
dflet 0:087b5655778d 445 This service is valid only for the configuration, where the application has
dflet 0:087b5655778d 446 not provided the callbacks to the client LIB 'context'. The caller must
dflet 0:087b5655778d 447 provide a packet buffer of adequate size to hold the expected message from
dflet 0:087b5655778d 448 the server.
dflet 0:087b5655778d 449
dflet 0:087b5655778d 450 The wait time implies the maximum intermediate duration between the reception
dflet 0:087b5655778d 451 of two successive messages from the server. If no message is received before
dflet 0:087b5655778d 452 the expiry of the wait time, the routine returns. However, the routine would
dflet 0:087b5655778d 453 continue to block, in case, messages are being received within the successive
dflet 0:087b5655778d 454 period of wait time and these messages are not the one that client is waiting
dflet 0:087b5655778d 455 for.
dflet 0:087b5655778d 456
dflet 0:087b5655778d 457 For platforms that can receive a MQTT message over multiple TCP packets or in
dflet 0:087b5655778d 458 segments, it is neccessary for the application to provide the same packet
dflet 0:087b5655778d 459 packet buffer 'mqp' across all iterations of this routine that returns with a
dflet 0:087b5655778d 460 value of MQP_ERR_TIMEOUT. Such an arrangement enables the implementation to
dflet 0:087b5655778d 461 iteratively build from consecutive multiple RX network packets / segements, a
dflet 0:087b5655778d 462 MQTT message into the packet buffer 'mqp. The application can always choose
dflet 0:087b5655778d 463 to assign a new 'mqp' once, a complete MQTT message has been received.
dflet 0:087b5655778d 464
dflet 0:087b5655778d 465 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 466 @see mqtt_client_ctx_create
dflet 0:087b5655778d 467 @param[in] msg_type message type to receive. A value of 0 would imply that
dflet 0:087b5655778d 468 caller is ready to receive the next message, whatsoever, from the server.
dflet 0:087b5655778d 469 @param[out] mqp packet buffer to hold the message received from the server.
dflet 0:087b5655778d 470 @param[in] wait_secs maximum Time to wait for a message from the server.
dflet 0:087b5655778d 471 @return On success, the number of bytes received for 'msg_type' from server,
dflet 0:087b5655778d 472 otherwise LIB defined error values (@ref lib_err_group)
dflet 0:087b5655778d 473 */
dflet 0:087b5655778d 474 int32_t mqtt_client_ctx_await_msg(void *ctx, uint8_t msg_type, struct mqtt_packet *mqp,
dflet 0:087b5655778d 475 uint32_t wait_secs);
dflet 0:087b5655778d 476
dflet 0:087b5655778d 477 /** Helper function to receive any message from the server.
dflet 0:087b5655778d 478 Refer to mqtt_client_ctx_await_msg for the details.
dflet 0:087b5655778d 479 @see mqtt_client_ctx_await_msg
dflet 0:087b5655778d 480 */
dflet 0:087b5655778d 481 static inline
dflet 0:087b5655778d 482 int32_t mqtt_client_ctx_recv(void *ctx, struct mqtt_packet *mqp, uint32_t wait_secs)
dflet 0:087b5655778d 483 {
dflet 0:087b5655778d 484 /* Receive next and any MQTT Message from the broker */
dflet 0:087b5655778d 485 return mqtt_client_ctx_await_msg(ctx, 0x00, mqp, wait_secs);
dflet 0:087b5655778d 486 }
dflet 0:087b5655778d 487
dflet 0:087b5655778d 488 /** Run the context for the specificed wait time.
dflet 0:087b5655778d 489 This service is valid only for the configuration, where the application has
dflet 0:087b5655778d 490 populated the callbacks that can be invoked by the client LIB 'context'.
dflet 0:087b5655778d 491
dflet 0:087b5655778d 492 This routine yields the control back to the application after the duration
dflet 0:087b5655778d 493 of the wait time. Such an arrangement enable the application to make overall
dflet 0:087b5655778d 494 progress to meet its intended functionality.
dflet 0:087b5655778d 495
dflet 0:087b5655778d 496 The wait time implies the maximum intermediate duration between the reception
dflet 0:087b5655778d 497 of two successive messages from the server. If no message is received before
dflet 0:087b5655778d 498 the expiry of the wait time, the routine returns. However, the routine would
dflet 0:087b5655778d 499 continue to block, in case, messages are being received within the successive
dflet 0:087b5655778d 500 period of the wait time.
dflet 0:087b5655778d 501
dflet 0:087b5655778d 502 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 503 @see mqtt_client_ctx_create
dflet 0:087b5655778d 504 @param[in] wait_secs maximum time to wait for a message from the server
dflet 0:087b5655778d 505
dflet 0:087b5655778d 506 @return MQP_ERR_NOTCONN if MQTT connection is closed by the application,
dflet 0:087b5655778d 507 MQP_ERR_TIMEOUT if there was no MQTT transaction in the interval of wait time
dflet 0:087b5655778d 508 and other values (@ref lib_err_group)
dflet 0:087b5655778d 509 */
dflet 0:087b5655778d 510 int32_t mqtt_client_ctx_run(void *ctx, uint32_t wait_secs);
dflet 0:087b5655778d 511
dflet 0:087b5655778d 512 /** Block to receive any message for the grouped contexts within specified time.
dflet 0:087b5655778d 513 This service is valid only for the set-up, where the applicatiion has not
dflet 0:087b5655778d 514 configured the grouped contexts in the callback mode. The caller must provide
dflet 0:087b5655778d 515 a packet buffer of adequate size to hold the expected message from the server.
dflet 0:087b5655778d 516
dflet 0:087b5655778d 517 The wait time implies the maximum intermediate duration between the reception
dflet 0:087b5655778d 518 of two successive messages from the server. If no message is received before
dflet 0:087b5655778d 519 the expiry of the wait time, the routine returns. However, the routine would
dflet 0:087b5655778d 520 continue to block, in case, messages are being received within the successive
dflet 0:087b5655778d 521 period of wait time.
dflet 0:087b5655778d 522
dflet 0:087b5655778d 523 In this revision of the LIB, the underlying implementation will be provide a
dflet 0:087b5655778d 524 valid value in the 'app' field for the all returned values, including errors,
dflet 0:087b5655778d 525 other than the cases of 'MQP_ERR_TIMEOUT' and 'MQP_ERR_LIBQUIT'. The value in
dflet 0:087b5655778d 526 'app', when valid refers to a previously configured handle to an application
dflet 0:087b5655778d 527 and idenitifies the 'context' for which the routine has been returned.
dflet 0:087b5655778d 528
dflet 0:087b5655778d 529 @param[out] mqp packet buffer to hold the message received from the server.
dflet 0:087b5655778d 530 @param[in] wait_secs Maximum Time to wait for a message from the server.
dflet 0:087b5655778d 531 @param[out] app place holder to indicate application handle for the packet.
dflet 0:087b5655778d 532 @return On success, the number of bytes received for 'msg_type' from server,
dflet 0:087b5655778d 533 otherwise LIB defined error values (@ref lib_err_group)
dflet 0:087b5655778d 534
dflet 0:087b5655778d 535 @note if the value of MQP_ERR_LIBQUIT is returned, then system must be
dflet 0:087b5655778d 536 restarted.
dflet 0:087b5655778d 537 */
dflet 0:087b5655778d 538 int32_t mqtt_client_await_msg(struct mqtt_packet *mqp, uint32_t wait_secs, void **app);
dflet 0:087b5655778d 539
dflet 0:087b5655778d 540 /** Run the LIB for the specified wait time.
dflet 0:087b5655778d 541 This service is valid only for the set-up of grouped contexts, where the
dflet 0:087b5655778d 542 application has populated the callbacks that can be invoked by the LIB.
dflet 0:087b5655778d 543
dflet 0:087b5655778d 544 This routine yields the control back to the application after the specified
dflet 0:087b5655778d 545 duration of wait time. Such an arrangement enable the application to
dflet 0:087b5655778d 546 make overall progress to meet it intended functionality.
dflet 0:087b5655778d 547
dflet 0:087b5655778d 548 The wait time implies the maximum intermediate duration between the reception
dflet 0:087b5655778d 549 of two successive messages from the server. If no message is received before
dflet 0:087b5655778d 550 the expiry of the wait time, the routine returns. However, the routine would
dflet 0:087b5655778d 551 continue to block, in case, messages are being received within the successive
dflet 0:087b5655778d 552 period of wait time.
dflet 0:087b5655778d 553
dflet 0:087b5655778d 554 @param[in] wait_secs maximum time to wait for a message from the server
dflet 0:087b5655778d 555
dflet 0:087b5655778d 556 @return on connection close by client app, number of bytes received for the
dflet 0:087b5655778d 557 last msg from broker, otherwise LIB defined error values.
dflet 0:087b5655778d 558
dflet 0:087b5655778d 559 @note if the value of MQP_ERR_LIBQUIT is returned, then system must be
dflet 0:087b5655778d 560 restarted.
dflet 0:087b5655778d 561 */
dflet 0:087b5655778d 562 int32_t mqtt_client_run(uint32_t wait_secs);
dflet 0:087b5655778d 563
dflet 0:087b5655778d 564 /*------------------------------------------------------------------------------
dflet 0:087b5655778d 565 * MQTT Client Library: Packet Buffer Pool and its management
dflet 0:087b5655778d 566 *------------------------------------------------------------------------------
dflet 0:087b5655778d 567 */
dflet 0:087b5655778d 568
dflet 0:087b5655778d 569 /** Allocates a free MQTT Packet Buffer.
dflet 0:087b5655778d 570 The pool that will be used by the library to allocate a free MQP buffer
dflet 0:087b5655778d 571 must be configured (i.e. registered) a-priori by the app.
dflet 0:087b5655778d 572
dflet 0:087b5655778d 573 The parameter 'offset' is used to specify the number of bytes that are
dflet 0:087b5655778d 574 reserved for the header in the buffer
dflet 0:087b5655778d 575
dflet 0:087b5655778d 576 @param[in] msg_type Message Type for which MQP buffer is being assigned.
dflet 0:087b5655778d 577 @param[in] offset Number of bytes to be reserved for MQTT headers.
dflet 0:087b5655778d 578 @return A NULL on error, otherwise a reference to a valid packet holder.
dflet 0:087b5655778d 579
dflet 0:087b5655778d 580 @see mqtt_client_register_buffers
dflet 0:087b5655778d 581 */
dflet 0:087b5655778d 582 struct mqtt_packet *mqp_client_alloc(uint8_t msg_type, uint8_t offset);
dflet 0:087b5655778d 583
dflet 0:087b5655778d 584 /** Helper function to allocate a MQTT Packet Buffer for a message to be
dflet 0:087b5655778d 585 dispatched to server.
dflet 0:087b5655778d 586
dflet 0:087b5655778d 587 @see to mqp_client_alloc( ) for details.
dflet 0:087b5655778d 588 */
dflet 0:087b5655778d 589 static inline struct mqtt_packet *mqp_client_send_alloc(uint8_t msg_type)
dflet 0:087b5655778d 590 {
dflet 0:087b5655778d 591 return mqp_client_alloc(msg_type, MAX_FH_LEN);
dflet 0:087b5655778d 592 }
dflet 0:087b5655778d 593
dflet 0:087b5655778d 594 /** Helper function to allocate a MQTT Packet Buffer for a message to be
dflet 0:087b5655778d 595 received from the server.
dflet 0:087b5655778d 596
dflet 0:087b5655778d 597 @see to mqp_client_alloc( ) for details.
dflet 0:087b5655778d 598 */
dflet 0:087b5655778d 599 static inline struct mqtt_packet *mqp_client_recv_alloc(uint8_t msg_type)
dflet 0:087b5655778d 600 {
dflet 0:087b5655778d 601 return mqp_client_alloc(msg_type, 0);
dflet 0:087b5655778d 602 }
dflet 0:087b5655778d 603
dflet 0:087b5655778d 604 /** Create a pool of MQTT Packet Buffers for the client library.
dflet 0:087b5655778d 605 This routine creates a pool of free MQTT Packet Buffers by attaching a buffer
dflet 0:087b5655778d 606 (buf) to a packet holder (mqp). The count of mqp elements and buf elements in
dflet 0:087b5655778d 607 the routine are same. And the size of the buffer in constant across all the
dflet 0:087b5655778d 608 elements.
dflet 0:087b5655778d 609
dflet 0:087b5655778d 610 The MQTT Packet Buffer pool should support (a) certain number of in-flight and
dflet 0:087b5655778d 611 stored packets that await ACK(s) from the server (b) certain number of packets
dflet 0:087b5655778d 612 from server whose processing would be deferred by the client app (to another
dflet 0:087b5655778d 613 context) (c) a packet to create a CONNECT message to re-establish transaction
dflet 0:087b5655778d 614 with the server.
dflet 0:087b5655778d 615
dflet 0:087b5655778d 616 A meaningful size of the pool is very much application specific and depends
dflet 0:087b5655778d 617 on the target functionality. For example, an application that intends to have
dflet 0:087b5655778d 618 only one in-flight message to the server would need atmost three MQP buffers
dflet 0:087b5655778d 619 (1 for TX (for Qos1 or 2 store), 1 for RX and 1 for CONNECT message). If the
dflet 0:087b5655778d 620 application sends only QoS0 messages to the server, then the number of MQP
dflet 0:087b5655778d 621 buffers would reduce to two (i.e. 1 Tx to support CONNECT / PUB out and 1 RX)
dflet 0:087b5655778d 622
dflet 0:087b5655778d 623 @param[in] num_mqp Number or count of elements in mqp_vec and buf_vec.
dflet 0:087b5655778d 624 @param[in] mqp_vec An array of MQTT Packet Holder without a buffer.
dflet 0:087b5655778d 625 @param[in] buf_len The size or length of the buffer element in the 'buf_vec'
dflet 0:087b5655778d 626 @param[in] buf_vec An array of buffers.
dflet 0:087b5655778d 627 @retun 0 on success otherwise -1 on error.
dflet 0:087b5655778d 628
dflet 0:087b5655778d 629 @note The parameters mqp_vec and buf_vec should be peristent entities.
dflet 0:087b5655778d 630
dflet 0:087b5655778d 631 @see mqtt_client_await_msg
dflet 0:087b5655778d 632 @see mqtt_client_run
dflet 0:087b5655778d 633 */
dflet 0:087b5655778d 634 int32_t mqtt_client_buffers_register(uint32_t num_mqp, struct mqtt_packet *mqp_vec,
dflet 0:087b5655778d 635 uint32_t buf_len, uint8_t *buf_vec);
dflet 0:087b5655778d 636
dflet 0:087b5655778d 637 /*------------------------------------------------------------------------------
dflet 0:087b5655778d 638 * MQTT Client Library: Register application, platform information and services.
dflet 0:087b5655778d 639 *------------------------------------------------------------------------------
dflet 0:087b5655778d 640 */
dflet 0:087b5655778d 641
dflet 0:087b5655778d 642 /** Register application info and its credentials with the client library.
dflet 0:087b5655778d 643 This routine registers information for all the specificed parameters,
dflet 0:087b5655778d 644 therefore, an upate to single element would imply re-specification of
dflet 0:087b5655778d 645 the other paramters, as well.
dflet 0:087b5655778d 646
dflet 0:087b5655778d 647 @note Contents embedded in the parameters is not copied by the routine,
dflet 0:087b5655778d 648 and instead a reference to the listed constructs is retained. Therefore,
dflet 0:087b5655778d 649 the app must enable the parameter contents for persistency.
dflet 0:087b5655778d 650
dflet 0:087b5655778d 651 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 652 @see mqtt_client_ctx_create
dflet 0:087b5655778d 653 @param[in] client_id MQTT UTF8 identifier of the client. If set to NULL,
dflet 0:087b5655778d 654 then the client will be treated as zero length entity.
dflet 0:087b5655778d 655 @param[in] user_name MQTT UTF8 user name for the client. If not used,
dflet 0:087b5655778d 656 set it to NULL. If used, then it can't be of zero length.
dflet 0:087b5655778d 657 @param[in] pass_word MQTT UTF8 pass word for the client. If not used, set
dflet 0:087b5655778d 658 it to NULL, If used, then it can't be of zero length.
dflet 0:087b5655778d 659 @return 0 on success otherwise -1
dflet 0:087b5655778d 660
dflet 0:087b5655778d 661 User name without a pass word is a valid configuration. A pass word won't
dflet 0:087b5655778d 662 be processed if it is not associated with a valid user name.
dflet 0:087b5655778d 663 */
dflet 0:087b5655778d 664 int32_t mqtt_client_ctx_info_register(void *ctx,
dflet 0:087b5655778d 665 const struct utf8_string *client_id,
dflet 0:087b5655778d 666 const struct utf8_string *user_name,
dflet 0:087b5655778d 667 const struct utf8_string *pass_word);
dflet 0:087b5655778d 668
dflet 0:087b5655778d 669 /** Register WILL information of the client application.
dflet 0:087b5655778d 670 This routine registers information for all the specificed parameters,
dflet 0:087b5655778d 671 therefore, an update to single element would imply re-specification
dflet 0:087b5655778d 672 of the other paramters, as well.
dflet 0:087b5655778d 673
dflet 0:087b5655778d 674 @note Contents embedded in the parameters is not copied by the routine,
dflet 0:087b5655778d 675 and instead a reference to the listed constructs is retained. Therefore,
dflet 0:087b5655778d 676 the app must enable the parameter contents for persistency.
dflet 0:087b5655778d 677
dflet 0:087b5655778d 678 @param[in] ctx handle to the underlying network context in the LIB
dflet 0:087b5655778d 679 @see mqtt_client_ctx_create
dflet 0:087b5655778d 680 @param[in] will_top UTF8 WILL Topic on which WILL message is to be published.
dflet 0:087b5655778d 681 @param[in] will_msg UTF8 WILL message.
dflet 0:087b5655778d 682 @param[in] will_qos QOS for the WILL message
dflet 0:087b5655778d 683 @param[in] retain asserted to indicate that published WILL must be retained
dflet 0:087b5655778d 684 @return 0 on success otherwise -1.
dflet 0:087b5655778d 685
dflet 0:087b5655778d 686 Both will_top and will_msg should be either present or should be NULL.
dflet 0:087b5655778d 687 will_qos and retain are relevant only for a valid Topic and Message combo.
dflet 0:087b5655778d 688 */
dflet 0:087b5655778d 689 int32_t mqtt_client_ctx_will_register(void *ctx,
dflet 0:087b5655778d 690 const struct utf8_string *will_top,
dflet 0:087b5655778d 691 const struct utf8_string *will_msg,
dflet 0:087b5655778d 692 enum mqtt_qos will_qos, bool retain);
dflet 0:087b5655778d 693
dflet 0:087b5655778d 694 /** Abstraction for the device specific network services.
dflet 0:087b5655778d 695 Network services for communication with the server
dflet 0:087b5655778d 696
dflet 0:087b5655778d 697 @param[in] net refers to network services supported by the platform
dflet 0:087b5655778d 698 @return on success, 0, otherwise -1
dflet 0:087b5655778d 699
dflet 0:087b5655778d 700 @ref net_ops_group
dflet 0:087b5655778d 701 @note all entries in net must be supported by the platform.
dflet 0:087b5655778d 702 */
dflet 0:087b5655778d 703 int32_t mqtt_client_net_svc_register(const struct device_net_services *net);
dflet 0:087b5655778d 704
dflet 0:087b5655778d 705 /** Helper functions & macros to derive 16 bit CONNACK Return Code from broker.
dflet 0:087b5655778d 706 */
dflet 0:087b5655778d 707 #define VHB_CONNACK_RC(vh_buf) (vh_buf[1]) /**< CONNACK VH:: Return Code */
dflet 0:087b5655778d 708 #define MQP_CONNACK_RC(mqp) (mqp->buffer[3])/**< CONNACK MQP:: Return Code */
dflet 0:087b5655778d 709
dflet 0:087b5655778d 710 #define VHB_CONNACK_SP(vh_buf) (vh_buf[0] & 0x1)/**< CONNACK VH:: Session Bit */
dflet 0:087b5655778d 711 #define MQP_CONNACK_SP(mqp) (mqp->buffer[2] & 0x1) /**< CONNACK MQP:: \
dflet 0:087b5655778d 712 Session Bit */
dflet 0:087b5655778d 713
dflet 0:087b5655778d 714 #define VHB_CONNACK_VH16(vh_buf)((vh_buf[0] << 8) | vh_buf[1])
dflet 0:087b5655778d 715 #define MQP_CONNACK_VH16(mqp) ((mqp->buffer[2] << 8) | mqp->buffer[3])
dflet 0:087b5655778d 716
dflet 0:087b5655778d 717 /** Callbacks to be invoked by MQTT Client library onto Client application */
dflet 0:087b5655778d 718 struct mqtt_client_ctx_cbs {
dflet 0:087b5655778d 719
dflet 0:087b5655778d 720 /** Provides a PUBLISH message from server to the client application.
dflet 0:087b5655778d 721 The application can utilize the associated set of helper macros to
dflet 0:087b5655778d 722 get references to the topic and the data information contained in
dflet 0:087b5655778d 723 the message. @ref rxpub_help_group
dflet 0:087b5655778d 724
dflet 0:087b5655778d 725 Depending upon the QoS level of the message, the MQTT client library
dflet 0:087b5655778d 726 shall dispatch the correponding acknowlegement (PUBACK or PUBREC) to
dflet 0:087b5655778d 727 the server, thereby, relieving application of this support.
dflet 0:087b5655778d 728
dflet 0:087b5655778d 729 If the application completes the processing of the packet within the
dflet 0:087b5655778d 730 implementation of this callback routine, then a value of 'true' must
dflet 0:087b5655778d 731 be returned to the client LIB 'context'. The library, in this case,
dflet 0:087b5655778d 732 does not handover the packet to application and instead, frees it up
dflet 0:087b5655778d 733 on return from this routine.
dflet 0:087b5655778d 734
dflet 0:087b5655778d 735 If the application intends to defer the processing of the PUBLISH
dflet 0:087b5655778d 736 message to a different execution task, then it must takeover the
dflet 0:087b5655778d 737 owernship of the packet by returning a value of 'false' to the client
dflet 0:087b5655778d 738 LIB 'context. In this arrangement, the client LIB 'context' hands
dflet 0:087b5655778d 739 over the packet to the application. The responsibility of storing,
dflet 0:087b5655778d 740 managing and eventually freeing up the packet back to the pool, now,
dflet 0:087b5655778d 741 lies with the app.
dflet 0:087b5655778d 742
dflet 0:087b5655778d 743 @param[in] app application to which this PUBLISH message is targeted
dflet 0:087b5655778d 744 @see mqtt_client_ctx_create
dflet 0:087b5655778d 745 @param[in] dup asserted to indicate a DUPLICATE PUBLISH
dflet 0:087b5655778d 746 @param[in] qos quality of Service of the PUBLISH message
dflet 0:087b5655778d 747 @param[in] retain Asserted to indicate message at new subscription
dflet 0:087b5655778d 748 @param[in] mqp Packet Buffer that holds the PUBLISH message
dflet 0:087b5655778d 749
dflet 0:087b5655778d 750 @return true to indicate that processing of the packet has been
dflet 0:087b5655778d 751 completed and it can freed-up and returned back to the pool by
dflet 0:087b5655778d 752 the library. Otherwise, false.
dflet 0:087b5655778d 753 */
dflet 0:087b5655778d 754 bool (*publish_rx)(void *app,
dflet 0:087b5655778d 755 bool dup, enum mqtt_qos qos, bool retain,
dflet 0:087b5655778d 756 struct mqtt_packet *mqp);
dflet 0:087b5655778d 757
dflet 0:087b5655778d 758 /** Notifies the client application about an ACK or a response from the
dflet 0:087b5655778d 759 server. Following are the messages that are notified by the client
dflet 0:087b5655778d 760 LIB to the application.
dflet 0:087b5655778d 761
dflet 0:087b5655778d 762 CONNACK, PINGRSP, PUBACK, PUBCOMP, SUBACK, UNSUBACK
dflet 0:087b5655778d 763
dflet 0:087b5655778d 764 @param[in] app application to which this ACK message is targeted
dflet 0:087b5655778d 765 @see mqtt_client_ctx_create
dflet 0:087b5655778d 766 @param[in] msg_type Type of the MQTT messsage
dflet 0:087b5655778d 767 @param[in] msg_id transaction identity of the message
dflet 0:087b5655778d 768 @param[in] buf refers to contents of message and depends on msg_type
dflet 0:087b5655778d 769 @param[in] len length of the buf
dflet 0:087b5655778d 770 @return none
dflet 0:087b5655778d 771
dflet 0:087b5655778d 772 @note The size of the buf parameter i.e len is non-zero for the
dflet 0:087b5655778d 773 SUBACK and CONNACK messages. For SUBACK the buf carries an array of
dflet 0:087b5655778d 774 QOS responses provided by the server. For CONNACK, the buf carries
dflet 0:087b5655778d 775 variable header contents. Helper macro VHB_CONNACK_RC( ) and
dflet 0:087b5655778d 776 VHB_CONNACK_SP( ) can be used to access contents provided by the
dflet 0:087b5655778d 777 server. For all other messages, the value of len parameter is zero.
dflet 0:087b5655778d 778
dflet 0:087b5655778d 779 @note The parameter msg_id is not relevant for the messages CONNACK
dflet 0:087b5655778d 780 and PINGRSP and is set to zero.
dflet 0:087b5655778d 781 */
dflet 0:087b5655778d 782 void (*ack_notify)(void *app, uint8_t msg_type, uint16_t msg_id, uint8_t *buf, uint32_t len);
dflet 0:087b5655778d 783
dflet 0:087b5655778d 784 /** Notifies the client application about the termination of connection
dflet 0:087b5655778d 785 with the server. After servicing this callback, the application can
dflet 0:087b5655778d 786 destroy associated context if it no longer required
dflet 0:087b5655778d 787
dflet 0:087b5655778d 788 @param[in] app application whose connection got terminated
dflet 0:087b5655778d 789 @see mqtt_client_ctx_create
dflet 0:087b5655778d 790 @param[in] cause reason that created disconnection
dflet 0:087b5655778d 791 (@ref lib_err_group)
dflet 0:087b5655778d 792 */
dflet 0:087b5655778d 793 void (*disconn_cb)(void *app, int32_t cause);
dflet 0:087b5655778d 794 };
dflet 0:087b5655778d 795
dflet 0:087b5655778d 796 struct mqtt_client_ctx_cfg {
dflet 0:087b5655778d 797
dflet 0:087b5655778d 798 /** @defgroup mqtt_ctx_cfg_opt_grp Options for application to config CTX
dflet 0:087b5655778d 799 @{
dflet 0:087b5655778d 800 */
dflet 0:087b5655778d 801 #define MQTT_CFG_PROTOCOL_V31 0x0001 /**< Assert for ver3.1, default is 3.1.1 */
dflet 0:087b5655778d 802 #define MQTT_CFG_APP_HAS_RTSK 0x0002 /**< Assert if APP has dedicated RX Task */
dflet 0:087b5655778d 803 #define MQTT_CFG_MK_GROUP_CTX 0x0004 /**< Assert if task manages > 1 contexts */
dflet 0:087b5655778d 804 /** @} */
dflet 0:087b5655778d 805
dflet 0:087b5655778d 806 uint16_t config_opts; /**< Context config Opt, @ref mqtt_ctx_cfg_opt_grp */
dflet 0:087b5655778d 807
dflet 0:087b5655778d 808 /** @defgroup mqtt_netconn_opt_grp Options for App to configure network
dflet 0:087b5655778d 809 @{
dflet 0:087b5655778d 810 */
dflet 0:087b5655778d 811 #define MQTT_NETCONN_OPT_IP6 DEV_NETCONN_OPT_IP6 /**<@ref dev_netconn_opt_grp */
dflet 0:087b5655778d 812 #define MQTT_NETCONN_OPT_URL DEV_NETCONN_OPT_URL /**<@ref dev_netconn_opt_grp */
dflet 0:087b5655778d 813 #define MQTT_NETCONN_OPT_SEC DEV_NETCONN_OPT_SEC /**<@ref dev_netconn_opt_grp */
dflet 0:087b5655778d 814 /** @} */
dflet 0:087b5655778d 815
dflet 0:087b5655778d 816 uint32_t nwconn_opts; /**< Network Options, @ref mqtt_netconn_opt_grp */
dflet 0:087b5655778d 817
dflet 0:087b5655778d 818 char *server_addr; /**< Reference to '\0' terminated address string */
dflet 0:087b5655778d 819 uint16_t port_number; /**< Network Listening Port number of the server */
dflet 0:087b5655778d 820 struct secure_conn *nw_security; /**< Refer to @ref mqtt_netsec_grp */
dflet 0:087b5655778d 821 };
dflet 0:087b5655778d 822
dflet 0:087b5655778d 823 /** Create a Network Connection Context.
dflet 0:087b5655778d 824 This routine sets-up the parameters that are required to operate and manage
dflet 0:087b5655778d 825 the network connection with a MQTT server / broker. As part of the creation
dflet 0:087b5655778d 826 of a context, the implementation also records the handle, if provided, by
dflet 0:087b5655778d 827 the application. In addition, the invoker of the routine must facilitate a
dflet 0:087b5655778d 828 place holder to enable the client LIB to provision the reference to the
dflet 0:087b5655778d 829 'context', so created.
dflet 0:087b5655778d 830
dflet 0:087b5655778d 831 Specifically, this routine associates or ties-up, in an one-to-one manner,
dflet 0:087b5655778d 832 the caller provided handle 'app' and the client LIB provisioned handle 'ctx'.
dflet 0:087b5655778d 833 The parameter 'app' is returned by the client LIB in certain other routines
dflet 0:087b5655778d 834 to indicate the underlying 'context' with which network transaction or event
dflet 0:087b5655778d 835 is associated. Similarly, the caller must specify the context handle 'ctx'
dflet 0:087b5655778d 836 for which the services are being invoked.
dflet 0:087b5655778d 837
dflet 0:087b5655778d 838 A user or a task prior to utilizing the services of the library to schedule
dflet 0:087b5655778d 839 MQTT transactions must create a 'context'. A client LIB 'context' can be
dflet 0:087b5655778d 840 operated in two modes: (a) sync-wait or explicit receive mode and (b) the
dflet 0:087b5655778d 841 callback mode. Provisioning or absence of the callback parameter in this
dflet 0:087b5655778d 842 routine defines the mode of operation of the 'context'.
dflet 0:087b5655778d 843
dflet 0:087b5655778d 844 Explicit receive mode is analogous to the paradigm of the socket programming
dflet 0:087b5655778d 845 in which an application utilize the recv() function call. It is anticipated
dflet 0:087b5655778d 846 that applications which would make use of limited set of MQTT messages may
dflet 0:087b5655778d 847 find this mode of operation useful. Applications which intend to operate the
dflet 0:087b5655778d 848 'context' in this mode must not provision any callbacks.
dflet 0:087b5655778d 849
dflet 0:087b5655778d 850 On the other hand, certain applications, may prefer an asynchronous mode of
dflet 0:087b5655778d 851 operation and would want the client LIB 'context' to raise callbacks into
dflet 0:087b5655778d 852 the application, as and when, packets arrive from the server. And such
dflet 0:087b5655778d 853 applications must provide the callback routines.
dflet 0:087b5655778d 854
dflet 0:087b5655778d 855 @param[in] ctx_cfg configuration information for the Network Context.
dflet 0:087b5655778d 856 @param[in] ctx_cbs callback routines. Must be set to NULL, if the application
dflet 0:087b5655778d 857 intends to operate the context in the sync-wait / explicit receive mode.
dflet 0:087b5655778d 858 @param[in] app handle to application. Returned by LIB in other routines
dflet 0:087b5655778d 859 to refer to the underlying context.
dflet 0:087b5655778d 860 @param[out] ctx reference to the context created and is provisioned by the
dflet 0:087b5655778d 861 implementation. (Valid only if routine returns a success)
dflet 0:087b5655778d 862
dflet 0:087b5655778d 863 @return 0 on success otherwise -1.
dflet 0:087b5655778d 864 */
dflet 0:087b5655778d 865 int32_t mqtt_client_ctx_create(const struct mqtt_client_ctx_cfg *ctx_cfg,
dflet 0:087b5655778d 866 const struct mqtt_client_ctx_cbs *ctx_cbs,
dflet 0:087b5655778d 867 void *app, void **ctx);
dflet 0:087b5655778d 868
dflet 0:087b5655778d 869 /** Delete a Network Connection Context.
dflet 0:087b5655778d 870 This routines destroys the previously created network 'context' and releases
dflet 0:087b5655778d 871 resources that would be assigned for maintaining the information about the
dflet 0:087b5655778d 872 'context'.
dflet 0:087b5655778d 873
dflet 0:087b5655778d 874 A user or a task prior to deleting the 'context' must ensure that there is no
dflet 0:087b5655778d 875 active MQTT connection on this context.
dflet 0:087b5655778d 876
dflet 0:087b5655778d 877 @param[in] ctx handle to network context to be deleted. The context must
dflet 0:087b5655778d 878 have been previously created.
dflet 0:087b5655778d 879
dflet 0:087b5655778d 880 @return 0 on success otherwise -1
dflet 0:087b5655778d 881 */
dflet 0:087b5655778d 882
dflet 0:087b5655778d 883 int32_t mqtt_client_ctx_delete(void *ctx);
dflet 0:087b5655778d 884
dflet 0:087b5655778d 885 /** Contruct / Data to initialize MQTT Client Library */
dflet 0:087b5655778d 886 struct mqtt_client_lib_cfg {
dflet 0:087b5655778d 887
dflet 0:087b5655778d 888 /** If an application has more than one contexts (i.e. grouped contexts)
dflet 0:087b5655778d 889 to manage in a single task, then a non-zero value must be provided.
dflet 0:087b5655778d 890 Otherwise, this parameter must be set to zero.
dflet 0:087b5655778d 891 */
dflet 0:087b5655778d 892 uint16_t loopback_port;
dflet 0:087b5655778d 893 bool grp_uses_cbfn; /**< Assert if grouped contexts use call-backs */
dflet 0:087b5655778d 894
dflet 0:087b5655778d 895 /** For a multi-task environment, provide a handle to platform mutex */
dflet 0:087b5655778d 896 void *mutex;
dflet 0:087b5655778d 897 void (*mutex_lockin)(void *mutex); /**< Take platform mutex function */
dflet 0:087b5655778d 898 void (*mutex_unlock)(void *mutex); /**< Give platform mutex function */
dflet 0:087b5655778d 899
dflet 0:087b5655778d 900 int32_t (*debug_printf)(const char *format, ...); /**< Debug, mandatory */
dflet 0:087b5655778d 901 bool aux_debug_en; /**< Assert to indicate additional debug info */
dflet 0:087b5655778d 902 };
dflet 0:087b5655778d 903
dflet 0:087b5655778d 904 /** Initialize the MQTT client library.
dflet 0:087b5655778d 905 This routine initializes all the common constructs that are required to
dflet 0:087b5655778d 906 manage the multiple network connetions. The client LIB must be initialized
dflet 0:087b5655778d 907 prior to invoking of any other routine or service.
dflet 0:087b5655778d 908
dflet 0:087b5655778d 909 @note This routine must be invoked only once in an run of the system.
dflet 0:087b5655778d 910
dflet 0:087b5655778d 911 Depending upon the deployment needs, this routine can be invoked either as
dflet 0:087b5655778d 912 part of the platform initialization sequence or as part of the application.
dflet 0:087b5655778d 913 Deployments that have more than one application utilizing the services of
dflet 0:087b5655778d 914 the client LIB should try to invoke the routine from the initialization
dflet 0:087b5655778d 915 sequence of the platform.
dflet 0:087b5655778d 916
dflet 0:087b5655778d 917 In addition, if an application has to manage more than one network
dflet 0:087b5655778d 918 connections (i.e. in other words, if the application has to handle
dflet 0:087b5655778d 919 a group of connections), then certain configuration must be set in
dflet 0:087b5655778d 920 the LIB @see struct mqtt_client_lib_cfg
dflet 0:087b5655778d 921
dflet 0:087b5655778d 922 @note There must be only one group of network connetions in the system.
dflet 0:087b5655778d 923
dflet 0:087b5655778d 924 @param[in] cfg Configuration information for the MQTT client Library.
dflet 0:087b5655778d 925
dflet 0:087b5655778d 926 @return 0 on success otherwise -1.
dflet 0:087b5655778d 927 */
dflet 0:087b5655778d 928
dflet 0:087b5655778d 929 int32_t mqtt_client_lib_init(const struct mqtt_client_lib_cfg *cfg);
dflet 0:087b5655778d 930
dflet 0:087b5655778d 931 /** Exit the MQTT client library.
dflet 0:087b5655778d 932 @return 0 on success otherwise -1.
dflet 0:087b5655778d 933 */
dflet 0:087b5655778d 934 int32_t mqtt_client_lib_exit(void);
dflet 0:087b5655778d 935
dflet 0:087b5655778d 936 /** @} */ /* End group client_api */
dflet 0:087b5655778d 937
dflet 0:087b5655778d 938 }//namespace mbed_mqtt
dflet 0:087b5655778d 939
dflet 0:087b5655778d 940 #ifdef __cplusplus
dflet 0:087b5655778d 941 }
dflet 0:087b5655778d 942 #endif
dflet 0:087b5655778d 943
dflet 0:087b5655778d 944 #endif
dflet 0:087b5655778d 945