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?
User | Revision | Line number | New 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 |