David Fletcher / server

Part of TI's mqtt

Dependents:   mqtt_V1 cc3100_Test_mqtt_CM3

server_pkts.h@0:547251f42a60, 2015-06-06 (annotated)

Committer:
dflet
Date:
Sat Jun 06 13:29:08 2015 +0000
Revision:
0:547251f42a60
Part of mqtt_V1

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dflet 0:547251f42a60 1 /******************************************************************************
dflet 0:547251f42a60 2 *
dflet 0:547251f42a60 3 * Copyright (C) 2014 Texas Instruments Incorporated
dflet 0:547251f42a60 4 *
dflet 0:547251f42a60 5 * All rights reserved. Property of Texas Instruments Incorporated.
dflet 0:547251f42a60 6 * Restricted rights to use, duplicate or disclose this code are
dflet 0:547251f42a60 7 * granted through contract.
dflet 0:547251f42a60 8 *
dflet 0:547251f42a60 9 * The program may not be used without the written permission of
dflet 0:547251f42a60 10 * Texas Instruments Incorporated or against the terms and conditions
dflet 0:547251f42a60 11 * stipulated in the agreement under which this program has been supplied,
dflet 0:547251f42a60 12 * and under no circumstances can it be used with non-TI connectivity device.
dflet 0:547251f42a60 13 *
dflet 0:547251f42a60 14 ******************************************************************************/
dflet 0:547251f42a60 15
dflet 0:547251f42a60 16 #ifndef __SERVER_PKTS_H__
dflet 0:547251f42a60 17 #define __SERVER_PKTS_H__
dflet 0:547251f42a60 18
dflet 0:547251f42a60 19 #include "mqtt_common.h"
dflet 0:547251f42a60 20
dflet 0:547251f42a60 21 #ifdef __cplusplus
dflet 0:547251f42a60 22 extern "C"
dflet 0:547251f42a60 23 {
dflet 0:547251f42a60 24 #endif
dflet 0:547251f42a60 25
dflet 0:547251f42a60 26 namespace mbed_mqtt {
dflet 0:547251f42a60 27
dflet 0:547251f42a60 28 /*-----------------------------------------------------------------------------
dflet 0:547251f42a60 29 * Note: Do not create additional dependency of this file on any header other
dflet 0:547251f42a60 30 * than mqtt_common.h. Specifically, server_pkts.[hc] in conjunction with the
dflet 0:547251f42a60 31 * mqtt_common.[hc] files must be facilitated to create a stand-alone library.
dflet 0:547251f42a60 32 *-----------------------------------------------------------------------------
dflet 0:547251f42a60 33 */
dflet 0:547251f42a60 34
dflet 0:547251f42a60 35 /**@file server_pkts.h
dflet 0:547251f42a60 36 The C library provisions the interface / API(s) for the MQTT Server Packet LIB.
dflet 0:547251f42a60 37
dflet 0:547251f42a60 38 This is a light-weight library that enables the services of the MQTT protcol
dflet 0:547251f42a60 39 for user's server application(s) to exchange the MQTT packets with one or
dflet 0:547251f42a60 40 more remote clients. The Server Packet LIB is a simple and easy-to-use
dflet 0:547251f42a60 41 implementation to support both un-packing of the messages received from the
dflet 0:547251f42a60 42 remote clients and formation of packets to be sent to the remote clients.
dflet 0:547251f42a60 43
dflet 0:547251f42a60 44 The library is targeted to conform to MQTT 3.1.1 specification.
dflet 0:547251f42a60 45
dflet 0:547251f42a60 46 The Server Packet LIB is a highly portable software and implies a very limited
dflet 0:547251f42a60 47 set of dependencies on a platform. Importantly, these limited dependencies are
dflet 0:547251f42a60 48 common features used in the embedded and the networking world, and can be
dflet 0:547251f42a60 49 easily adapted to the target platforms. The services of the library are
dflet 0:547251f42a60 50 multi-task safe. Platform specific atomicity constructs are used, through
dflet 0:547251f42a60 51 abstractions, by the library to maintain data coherency and synchronization.
dflet 0:547251f42a60 52 In addition, the library can be configured to support several in-flight
dflet 0:547251f42a60 53 messages.
dflet 0:547251f42a60 54
dflet 0:547251f42a60 55 The Server Packet LIB can support multiple and simultaneous MQTT connections
dflet 0:547251f42a60 56 from clients. However, the responsibility of managing the clients and topics,
dflet 0:547251f42a60 57 authentication and approval for connections and supporting any other needs
dflet 0:547251f42a60 58 that specific to the deployment remains with the user application.
dflet 0:547251f42a60 59
dflet 0:547251f42a60 60 The number of the network connections that the Server Packet LIB can support
dflet 0:547251f42a60 61 is configurable through the compile line option / flag <b> -DCFG_SR_MQTT_CTXS
dflet 0:547251f42a60 62 </b>. In addition, the maximum length of the RX buffer used by the server is
dflet 0:547251f42a60 63 also configurable through the compile line option / flag <b>
dflet 0:547251f42a60 64 -DCFG_SR_MAX_MQP_RX_LEN </b>.
dflet 0:547251f42a60 65
dflet 0:547251f42a60 66 @note Any future extensions & development must follow the following guidelines.
dflet 0:547251f42a60 67 A new API or an extension to the existing API
dflet 0:547251f42a60 68 a) must be rudimentary
dflet 0:547251f42a60 69 b) must not imply a rule or policy (including a state machine)
dflet 0:547251f42a60 70 b) must ensure simple design and implementation
dflet 0:547251f42a60 71 */
dflet 0:547251f42a60 72
dflet 0:547251f42a60 73
dflet 0:547251f42a60 74 /** @defgroup server_pktlib The Server Library API(s)
dflet 0:547251f42a60 75 @{
dflet 0:547251f42a60 76 */
dflet 0:547251f42a60 77
dflet 0:547251f42a60 78 /** @defgroup conn_utf8_help_group Helper Macros for RX CONNECT
dflet 0:547251f42a60 79 @{
dflet 0:547251f42a60 80 */
dflet 0:547251f42a60 81
dflet 0:547251f42a60 82 /** Yields pointer to the UTF8 content */
dflet 0:547251f42a60 83 #define MQ_CONN_UTF8_BUF(utf8) ((utf8)? (utf8)->buffer : NULL)
dflet 0:547251f42a60 84
dflet 0:547251f42a60 85 /** Length or size of the UTF8 content */
dflet 0:547251f42a60 86 #define MQ_CONN_UTF8_LEN(utf8) ((utf8)? (utf8)->length : 0)
dflet 0:547251f42a60 87
dflet 0:547251f42a60 88 #define MQC_UTF8_CLIENTID(utf8_vec) (utf8_vec[0]) /**< Returns Client ID */
dflet 0:547251f42a60 89 #define MQC_UTF8_WILL_TOP(utf8_vec) (utf8_vec[1]) /**< Returns Will Topic */
dflet 0:547251f42a60 90 #define MQC_UTF8_WILL_MSG(utf8_vec) (utf8_vec[2]) /**< Returns Will Data */
dflet 0:547251f42a60 91 #define MQC_UTF8_USERNAME(utf8_vec) (utf8_vec[3]) /**< Returns User Name */
dflet 0:547251f42a60 92 #define MQC_UTF8_PASSWORD(utf8_vec) (utf8_vec[4]) /**< Returns Pass Word */
dflet 0:547251f42a60 93
dflet 0:547251f42a60 94 #define MQC_CLIENTID_BUF(utf8_vec) MQ_CONN_UTF8_BUF(MQC_UTF8_CLIENTID(utf8_vec))
dflet 0:547251f42a60 95 #define MQC_CLIENTID_LEN(utf8_vec) MQ_CONN_UTF8_LEN(MQC_UTF8_CLIENTID(utf8_vec))
dflet 0:547251f42a60 96
dflet 0:547251f42a60 97 #define MQC_WILL_TOP_BUF(utf8_vec) MQ_CONN_UTF8_BUF(MQC_UTF8_WILL_TOP(utf8_vec))
dflet 0:547251f42a60 98 #define MQC_WILL_TOP_LEN(utf8_vec) MQ_CONN_UTF8_LEN(MQC_UTF8_WILL_TOP(utf8_vec))
dflet 0:547251f42a60 99
dflet 0:547251f42a60 100 #define MQC_WILL_MSG_BUF(utf8_vec) MQ_CONN_UTF8_BUF(MQC_UTF8_WILL_MSG(utf8_vec))
dflet 0:547251f42a60 101 #define MQC_WILL_MSG_LEN(utf8_vec) MQ_CONN_UTF8_LEN(MQC_UTF8_WILL_MSG(utf8_vec))
dflet 0:547251f42a60 102
dflet 0:547251f42a60 103 #define MQC_USERNAME_BUF(utf8_vec) MQ_CONN_UTF8_BUF(MQC_UTF8_USERNAME(utf8_vec))
dflet 0:547251f42a60 104 #define MQC_USERNAME_LEN(utf8_vec) MQ_CONN_UTF8_LEN(MQC_UTF8_USERNAME(utf8_vec))
dflet 0:547251f42a60 105
dflet 0:547251f42a60 106 #define MQC_PASSWORD_BUF(utf8_vec) MQ_CONN_UTF8_BUF(MQC_UTF8_PASSWORD(utf8_vec))
dflet 0:547251f42a60 107 #define MQC_PASSWORD_LEN(utf8_vec) MQ_CONN_UTF8_LEN(MQC_UTF8_PASSWORD(utf8_vec))
dflet 0:547251f42a60 108
dflet 0:547251f42a60 109 /** @} */
dflet 0:547251f42a60 110
dflet 0:547251f42a60 111 #ifndef CFG_SR_MAX_MQP_RX_LEN
dflet 0:547251f42a60 112 #define MQP_SERVER_RX_LEN 1024 /**< Max size(B) of RX Buffer for MQTT Server */
dflet 0:547251f42a60 113 #else
dflet 0:547251f42a60 114 #define MQP_SERVER_RX_LEN CFG_SR_MAX_MQP_RX_LEN
dflet 0:547251f42a60 115 #endif
dflet 0:547251f42a60 116
dflet 0:547251f42a60 117 /** Send a Variable Header only message to the client.
dflet 0:547251f42a60 118 Application should this routine to send PUBREL and PUBCOMP messages.
dflet 0:547251f42a60 119
dflet 0:547251f42a60 120 @param[in] ctx_cl handle to the underlying network context in the LIB. This
dflet 0:547251f42a60 121 handle is provided to the application by the LIB in the CONNECT callback.
dflet 0:547251f42a60 122 @param[in] msg_type message type that has to be sent to the client
dflet 0:547251f42a60 123 @param[in] qos QoS with which the message needs to send to server
dflet 0:547251f42a60 124 @param[in] has_vh does this message has data in the variable header?
dflet 0:547251f42a60 125 @param[in] vh_data data <MSB:LSB> to be included in the variable header
dflet 0:547251f42a60 126 @return on success, the number of bytes transferred. Otherwise, errors
dflet 0:547251f42a60 127 defined in @ref lib_err_group
dflet 0:547251f42a60 128 */
dflet 0:547251f42a60 129 int32_t mqtt_vh_msg_send(void *ctx_cl, uint8_t msg_type, enum mqtt_qos qos,
dflet 0:547251f42a60 130 bool has_vh, uint16_t vh_data);
dflet 0:547251f42a60 131
dflet 0:547251f42a60 132 /** mqtt_vh_msg_send() with mutual exclusion (in multi-task application).
dflet 0:547251f42a60 133 This routine ensures that the LIB sends the specified VH MSG onto the network
dflet 0:547251f42a60 134 in a manner that excludes execution of any other control. This API has been
dflet 0:547251f42a60 135 enabled to support the scenarios, where the multi-tasked user application has
dflet 0:547251f42a60 136 chosen to use a mutex object other than the one provisioned in the packet LIB
dflet 0:547251f42a60 137 to streamline / serialize accesses to the services of the packet LIB.
dflet 0:547251f42a60 138
dflet 0:547251f42a60 139 Refer to @ref mqtt_vh_msg_send for details
dflet 0:547251f42a60 140 */
dflet 0:547251f42a60 141 int32_t mqtt_vh_msg_send_locked(void *ctx_cl, uint8_t msg_type, enum mqtt_qos qos,
dflet 0:547251f42a60 142 bool has_vh, uint16_t vh_data);
dflet 0:547251f42a60 143
dflet 0:547251f42a60 144 /** Dispatch application constructed PUBLISH message to the client.
dflet 0:547251f42a60 145 Prior to sending the message to the client, this routine shall update the
dflet 0:547251f42a60 146 fixed-header to account for the duplicate flag that has been indicated by
dflet 0:547251f42a60 147 the caller.
dflet 0:547251f42a60 148
dflet 0:547251f42a60 149 The caller must populate the payload information of topic and data before
dflet 0:547251f42a60 150 invoking this service. In addition, the application must prepare, for the
dflet 0:547251f42a60 151 packet, the fix header leaving aside the duplicate flag - this flag shall
dflet 0:547251f42a60 152 be included in the fix heder by the LIB.
dflet 0:547251f42a60 153
dflet 0:547251f42a60 154 This service facilitates the application to re-use, iteratively, a single
dflet 0:547251f42a60 155 PUBLISH packet for multiple remote clients that have subscribed to the
dflet 0:547251f42a60 156 same topic for which the data is being published. The LIB does not free-up
dflet 0:547251f42a60 157 the MQTT packet after sending the packet to the remote client and the
dflet 0:547251f42a60 158 application is responsible for managing the packet container / memory
dflet 0:547251f42a60 159
dflet 0:547251f42a60 160 @param[in] ctx_cl handle to the underlying network context in the LIB. This
dflet 0:547251f42a60 161 handle is provided to the application by the LIB in the CONNECT callback.
dflet 0:547251f42a60 162 @param[in] mqp app created PUBLISH message alongwith the fixed header
dflet 0:547251f42a60 163 @param[in] dup is this a duplicate message that is being sent to client?
dflet 0:547251f42a60 164 @return on success, the number of bytes transferred. Otherwise, error
dflet 0:547251f42a60 165 defined in @ref lib_err_group
dflet 0:547251f42a60 166 */
dflet 0:547251f42a60 167 int32_t mqtt_server_pub_dispatch(void *ctx_cl, struct mqtt_packet *mqp, bool dup);
dflet 0:547251f42a60 168
dflet 0:547251f42a60 169 /** mqtt_server_pub_dispatch() with mutual exclusion (in multi-task application).
dflet 0:547251f42a60 170 This routine ensures that the LIB sends the specified packet onto the network
dflet 0:547251f42a60 171 in a manner that excludes execution of any other control. This API has been
dflet 0:547251f42a60 172 enabled to support the scenarios, where the multi-tasked user application has
dflet 0:547251f42a60 173 chosen to use a mutex object other than the one provisioned in the packet LIB
dflet 0:547251f42a60 174 to streamline / serialize accesses to the services of the packet LIB.
dflet 0:547251f42a60 175
dflet 0:547251f42a60 176 Refer to @ref mqtt_server_pub_dispatch for other details.
dflet 0:547251f42a60 177 */
dflet 0:547251f42a60 178 int32_t mqtt_server_pub_dispatch_locked(void *ctx_cl, struct mqtt_packet *mqp,
dflet 0:547251f42a60 179 bool dup);
dflet 0:547251f42a60 180
dflet 0:547251f42a60 181 /** Run the server packet LIB for the specified wait time.
dflet 0:547251f42a60 182 This routine yields the control back to the application after the specified
dflet 0:547251f42a60 183 duration of wait time. Such an arrangement enable the application to make
dflet 0:547251f42a60 184 overall progress to meet it intended functionality.
dflet 0:547251f42a60 185
dflet 0:547251f42a60 186 The wait time implies the maximum intermediate duration between the reception
dflet 0:547251f42a60 187 of two successive messages from the server. If no message is received before
dflet 0:547251f42a60 188 the expiry of the wait time, the routine returns. However, the routine would
dflet 0:547251f42a60 189 continue to block, in case, messages are being received within the successive
dflet 0:547251f42a60 190 period of wait time.
dflet 0:547251f42a60 191
dflet 0:547251f42a60 192 @param[in] wait_secs maximum time to wait for a message from the server
dflet 0:547251f42a60 193
dflet 0:547251f42a60 194 @note if the value of MQP_ERR_LIBQUIT is returned, then system must be
dflet 0:547251f42a60 195 restarted.
dflet 0:547251f42a60 196 */
dflet 0:547251f42a60 197 int32_t mqtt_server_run(uint32_t wait_secs);
dflet 0:547251f42a60 198
dflet 0:547251f42a60 199 /** Abstraction for the device specific network services
dflet 0:547251f42a60 200 Network services for communication with the clients
dflet 0:547251f42a60 201
dflet 0:547251f42a60 202 @param[in] net refers to network services supported by the platform
dflet 0:547251f42a60 203 @return on success, 0, otherwise -1
dflet 0:547251f42a60 204
dflet 0:547251f42a60 205 @ref net_ops_group
dflet 0:547251f42a60 206 @note all entries in net must be supported by the platform.
dflet 0:547251f42a60 207 */
dflet 0:547251f42a60 208 int32_t mqtt_server_register_net_svc(const struct device_net_services *net);
dflet 0:547251f42a60 209
dflet 0:547251f42a60 210
dflet 0:547251f42a60 211 /** <b> Working Principle </b> for implementing the call-back services:
dflet 0:547251f42a60 212 Implementation of the call-back services should report in return value, only
dflet 0:547251f42a60 213 about errors found in the RX processing. Specifically, the status of TX as a
dflet 0:547251f42a60 214 follow-up to RX message (represented as a call-back service) need not be
dflet 0:547251f42a60 215 reported to the server packet library.
dflet 0:547251f42a60 216
dflet 0:547251f42a60 217 Error observed in TX (supported by appropriate API(s) / services in the
dflet 0:547251f42a60 218 service packet library) is recorded in the 'context' and shall be dealt in
dflet 0:547251f42a60 219 the next iteration of RX loop.
dflet 0:547251f42a60 220 */
dflet 0:547251f42a60 221 struct mqtt_server_msg_cbs {
dflet 0:547251f42a60 222
dflet 0:547251f42a60 223 /** Indicate the CONNECT Message from the client
dflet 0:547251f42a60 224 This routine provides, to the application, information about the
dflet 0:547251f42a60 225 connection request that a remote client has made. The application
dflet 0:547251f42a60 226 should utilize the credential and other data presented by the LIB
dflet 0:547251f42a60 227 to authenticate, analyze and finally, approve or deny the request.
dflet 0:547251f42a60 228
dflet 0:547251f42a60 229 Application at its discretion can also imply deployment specific
dflet 0:547251f42a60 230 policies to make decision about allowing or refusing the request.
dflet 0:547251f42a60 231
dflet 0:547251f42a60 232 The return value of this routine is a 16bit value that commensurates
dflet 0:547251f42a60 233 with the 'variable header' of the CONNACK message. Specifically, the
dflet 0:547251f42a60 234 LSB of the 16bit return value corresponds to the 8bit 'return code'
dflet 0:547251f42a60 235 parameter in the CONNACK message and the MSB to the 'acknowledge
dflet 0:547251f42a60 236 flags'. The application must set a valid return value.
dflet 0:547251f42a60 237
dflet 0:547251f42a60 238 The LIB uses the return value to compose the CONNACK message to the
dflet 0:547251f42a60 239 remote client. If the LSB of return value is a 'non zero' value,
dflet 0:547251f42a60 240 then the LIB, after sending the CONNACK message to the remote client,
dflet 0:547251f42a60 241 will terminate the network connection.
dflet 0:547251f42a60 242
dflet 0:547251f42a60 243 @param[in] ctx_cl handle to the underlying network context in the LIB
dflet 0:547251f42a60 244 @param[in] conn_flags options received in CONNECT message from server
dflet 0:547251f42a60 245 @param[in] utf8_vec vector / array of pointers to UTF8 information.
dflet 0:547251f42a60 246 The order of UTF8 information is client-id, will topic, will-message,
dflet 0:547251f42a60 247 user-name and pass-word. A NULL in vector element indicates absence
dflet 0:547251f42a60 248 of that particular UTF8 information.
dflet 0:547251f42a60 249 @param[out] usr place holder for application to provide connection
dflet 0:547251f42a60 250 specific handle. In subsequent calls from the implementation this
dflet 0:547251f42a60 251 handle will be passed as a parameter to enable application to refer
dflet 0:547251f42a60 252 to the particular active connection.
dflet 0:547251f42a60 253
dflet 0:547251f42a60 254 @return 16bit value for the variable header of the CONNACK message,
dflet 0:547251f42a60 255 MSB is CONNACK-Flags, LSB is CONNACK-RC
dflet 0:547251f42a60 256 */
dflet 0:547251f42a60 257 uint16_t (*connect_rx)(void *ctx_cl, uint8_t conn_flags,
dflet 0:547251f42a60 258 struct utf8_string * const *utf8_vec, void **usr);
dflet 0:547251f42a60 259
dflet 0:547251f42a60 260 /** Indicate the SUBSCRIBE Message from the client
dflet 0:547251f42a60 261 This routine provides, to the application, information about the
dflet 0:547251f42a60 262 topics that the remote client intends to subscribe to.
dflet 0:547251f42a60 263
dflet 0:547251f42a60 264 On return from this routine, if the application has found a problem
dflet 0:547251f42a60 265 in the processing of message, then the LIB will simply terminate the
dflet 0:547251f42a60 266 associated network connection.
dflet 0:547251f42a60 267
dflet 0:547251f42a60 268 @param[in] usr_cl handle to connection context in the application
dflet 0:547251f42a60 269 @param[in] qos_topics an array of topic along-with its qos
dflet 0:547251f42a60 270 @param[in] n_topics the count / number of elements in the array
dflet 0:547251f42a60 271 @param[in] msg_id the associated message ID provided by the client
dflet 0:547251f42a60 272 @param[in] acks place holder array for the application to provide
dflet 0:547251f42a60 273 finalized qos for each of the subscribed topic. The order of ack
dflet 0:547251f42a60 274 is same as that of qos_topics
dflet 0:547251f42a60 275
dflet 0:547251f42a60 276 @return The application should return false, if it encounters any
dflet 0:547251f42a60 277 problem in the processing of topic. Otherwise, true.
dflet 0:547251f42a60 278
dflet 0:547251f42a60 279 @note The memory space pointed by the 'buffer' field in the elements
dflet 0:547251f42a60 280 of 'qos_topics' array has an additional byte available beyond the
dflet 0:547251f42a60 281 size of memory indicated by the 'length' field. This extra byte can
dflet 0:547251f42a60 282 be used by the application to NUL terminate the buffer. <b> This
dflet 0:547251f42a60 283 quirk is applicable to this routine only. </b>
dflet 0:547251f42a60 284 */
dflet 0:547251f42a60 285 bool (*sub_msg_rx)(void *usr_cl, const struct utf8_strqos *qos_topics,
dflet 0:547251f42a60 286 uint32_t n_topics, uint16_t msg_id, uint8_t *acks);
dflet 0:547251f42a60 287
dflet 0:547251f42a60 288 /** Indicate the UNSUBSCRIBE Message from the client
dflet 0:547251f42a60 289 This routine provides, to the application, information about the
dflet 0:547251f42a60 290 topics that the remote client intends to unsubscribe.
dflet 0:547251f42a60 291
dflet 0:547251f42a60 292 On return from this routine, if the application has found a problem
dflet 0:547251f42a60 293 in the processing of message, then the LIB will simply terminate the
dflet 0:547251f42a60 294 associated network connection.
dflet 0:547251f42a60 295
dflet 0:547251f42a60 296 @param[in] usr_cl handle to connection context in the application
dflet 0:547251f42a60 297 @param[in] topics an array of topic in the message
dflet 0:547251f42a60 298 @param[in] n_topics the count / number of elements in the array
dflet 0:547251f42a60 299 @param[in] msg_id the associated message ID provided by the client
dflet 0:547251f42a60 300
dflet 0:547251f42a60 301 @return The application should return false, if it encounters any
dflet 0:547251f42a60 302 problem in the processing of topic. Otherwise, true.
dflet 0:547251f42a60 303 */
dflet 0:547251f42a60 304 bool (*un_sub_msg)(void *usr_cl, const struct utf8_string *topics,
dflet 0:547251f42a60 305 uint32_t n_topics, uint16_t msg_id);
dflet 0:547251f42a60 306
dflet 0:547251f42a60 307 /** Indicate the PUBLISH Message from the client.
dflet 0:547251f42a60 308 This routine provides, to the application, the binary data along-with
dflet 0:547251f42a60 309 its qualifiers and the topic to which a remote client has published
dflet 0:547251f42a60 310 data.
dflet 0:547251f42a60 311
dflet 0:547251f42a60 312 On return from this routine, if the application has found a problem
dflet 0:547251f42a60 313 in processing of the contents of the PUBLISH message, the LIB will
dflet 0:547251f42a60 314 simply terminate the associated network connection. Otherwise,
dflet 0:547251f42a60 315 depending upon the QoS level of the PUBLISH message, the LIB shall
dflet 0:547251f42a60 316 dispatch the ACK (PUBACK or PUBREC) to the client, thereby,
dflet 0:547251f42a60 317 relieveing the application from this support.
dflet 0:547251f42a60 318
dflet 0:547251f42a60 319 @param[in] usr_cl handle to connection context in the application
dflet 0:547251f42a60 320 @param[in] topic UTF8 Topic Name for which data has been published
dflet 0:547251f42a60 321 @param[in] data_buf the published binary data for the topic
dflet 0:547251f42a60 322 @param[in] data_len the length of the binary data
dflet 0:547251f42a60 323 @param[in] msg_id the associated message ID provided by the client
dflet 0:547251f42a60 324 @param[in] dup has client indicated this as a duplicate message
dflet 0:547251f42a60 325 @param[in] qos quality of service of the message
dflet 0:547251f42a60 326 @param[in] retain should the server retain the data?
dflet 0:547251f42a60 327
dflet 0:547251f42a60 328 @return The application should return false, if it encounters any
dflet 0:547251f42a60 329 problem in the processing of data, topic and related resources.
dflet 0:547251f42a60 330 Otherwise, true.
dflet 0:547251f42a60 331 */
dflet 0:547251f42a60 332 bool (*pub_msg_rx)(void *usr_cl, const struct utf8_string *topic,
dflet 0:547251f42a60 333 const uint8_t *data_buf, uint32_t data_len, uint16_t msg_id,
dflet 0:547251f42a60 334 bool dup, enum mqtt_qos qos, bool retain);
dflet 0:547251f42a60 335
dflet 0:547251f42a60 336 /** Notify the acknowledgement that was received from the remote client.
dflet 0:547251f42a60 337 Following are the messages that are notified by the server LIB.
dflet 0:547251f42a60 338
dflet 0:547251f42a60 339 PUBACK, PUBREC, PUBREL, PUBCOMP
dflet 0:547251f42a60 340
dflet 0:547251f42a60 341 On return from this routine, if the application has found problem
dflet 0:547251f42a60 342 in processing the ACK message, then the LIB will simply terminate
dflet 0:547251f42a60 343 the associated network connection
dflet 0:547251f42a60 344
dflet 0:547251f42a60 345 @param[in] usr_cl handle to connection context in the application
dflet 0:547251f42a60 346 @param[in] msg_type refers to the type of ACK message
dflet 0:547251f42a60 347 @param[in] msg_id the associated message ID provided by the client
dflet 0:547251f42a60 348 @return application should return false if the ACK was not expected
dflet 0:547251f42a60 349 by it or no reference was found for it. Otherwise true.
dflet 0:547251f42a60 350 */
dflet 0:547251f42a60 351 bool (*ack_notify)(void *usr_cl, uint8_t msg_type, uint16_t msg_id);
dflet 0:547251f42a60 352
dflet 0:547251f42a60 353 /** Notify that network connection to client has been closed.
dflet 0:547251f42a60 354 This routine is invoked by the LIB to declare to the application that
dflet 0:547251f42a60 355 the network connection to a particular client has been terminated and
dflet 0:547251f42a60 356 follow-up, if needed, can now commence. If configured, removal of the
dflet 0:547251f42a60 357 client session and / or dispatch of the WILL message, will be typical
dflet 0:547251f42a60 358 aspects, among others, to follow-up. The routine aids the application
dflet 0:547251f42a60 359 by indicating if an error condition had caused the closure.
dflet 0:547251f42a60 360
dflet 0:547251f42a60 361 This routine is invoked by the LIB irrespective of the source entity,
dflet 0:547251f42a60 362 server or client, that has caused the closure of the network.
dflet 0:547251f42a60 363
dflet 0:547251f42a60 364 @param[in] usr_cl handle to connection context in the application
dflet 0:547251f42a60 365 @param[in] due2err has the connection been closed due to an error?
dflet 0:547251f42a60 366 */
dflet 0:547251f42a60 367 void (*on_cl_net_close)(void *usr_cl, bool due2err);
dflet 0:547251f42a60 368
dflet 0:547251f42a60 369 /** Notify that CONNACK has been sent to the specified client.
dflet 0:547251f42a60 370 This routine is invoked by the LIB to enable the application to make
dflet 0:547251f42a60 371 progress and follow-up on the session information for the particular
dflet 0:547251f42a60 372 client. Specifically, this routine facilitates the application to
dflet 0:547251f42a60 373 either delete the session or re-send / sync-up the pending messages
dflet 0:547251f42a60 374 associated with the client. The follow-up action is depenedent upon
dflet 0:547251f42a60 375 the 'clean_session' option in the CONNECT message from the client.
dflet 0:547251f42a60 376 @param[in] usr_cl handle to connection context in the application
dflet 0:547251f42a60 377 @param[in] clean_session was a clean session requested in CONNECT?
dflet 0:547251f42a60 378 */
dflet 0:547251f42a60 379 void (*on_connack_send)(void *usr_cl, bool clean_session);
dflet 0:547251f42a60 380 };
dflet 0:547251f42a60 381
dflet 0:547251f42a60 382 struct mqtt_server_lib_cfg {
dflet 0:547251f42a60 383
dflet 0:547251f42a60 384 /** Port to listen to incoming network connections from the clients */
dflet 0:547251f42a60 385 uint16_t listener_port;
dflet 0:547251f42a60 386
dflet 0:547251f42a60 387 /** If the server application has more than one task and / or supports
dflet 0:547251f42a60 388 at-least one plug-in, then a non-zero value must be provided.
dflet 0:547251f42a60 389 Otherwise, this parameter must be set to zero. This parameter is
dflet 0:547251f42a60 390 used by the implementation to synchronize multiple tasks for the
dflet 0:547251f42a60 391 network connection.
dflet 0:547251f42a60 392 */
dflet 0:547251f42a60 393 uint16_t loopback_port;
dflet 0:547251f42a60 394
dflet 0:547251f42a60 395 /** For a multi-task enviroment, provide a handle to platform mutex */
dflet 0:547251f42a60 396 void *mutex;
dflet 0:547251f42a60 397 void (*mutex_lockin)(void *mutex);
dflet 0:547251f42a60 398 void (*mutex_unlock)(void *mutex);
dflet 0:547251f42a60 399
dflet 0:547251f42a60 400 int32_t (*debug_printf)(const char *format, ...); /**< Debug, mandatory */
dflet 0:547251f42a60 401 bool aux_debug_en; /**< Assert to indicate additional debug info */
dflet 0:547251f42a60 402
dflet 0:547251f42a60 403 };
dflet 0:547251f42a60 404
dflet 0:547251f42a60 405 /** Initialize the MQTT Server Packet library
dflet 0:547251f42a60 406 This routine initializes the packet and network constructs that are required
dflet 0:547251f42a60 407 to manage the multiple network connetions. The server packet LIB must be
dflet 0:547251f42a60 408 initialized prior to invoking of any other routine or service.
dflet 0:547251f42a60 409
dflet 0:547251f42a60 410 @note This routine must be invoked only once in an run of the system.
dflet 0:547251f42a60 411
dflet 0:547251f42a60 412 If there are more than one application (tasks) that utilize the services
dflet 0:547251f42a60 413 of the server packet library, then certain configuration must be set in
dflet 0:547251f42a60 414 the LIB @see struct mqtt_server_lib_cfg
dflet 0:547251f42a60 415
dflet 0:547251f42a60 416 The application should also provision the platform network specific network
dflet 0:547251f42a60 417 services into the packet library @see mqtt_server_register_net_svc.
dflet 0:547251f42a60 418
dflet 0:547251f42a60 419 Once, the server LIB has been intialized successfully, it must be put into
dflet 0:547251f42a60 420 action, to listen to requests for incoming connections, by invoking the API
dflet 0:547251f42a60 421 @ref mqtt_server_run.
dflet 0:547251f42a60 422
dflet 0:547251f42a60 423 @param[in] cfg configuration information for the MQTT server packet library
dflet 0:547251f42a60 424 @param[in] cbs callback routines that LIB will invoke into the application
dflet 0:547251f42a60 425
dflet 0:547251f42a60 426 @return 0 on success otherwise -1.
dflet 0:547251f42a60 427 */
dflet 0:547251f42a60 428 int32_t mqtt_server_lib_init(const struct mqtt_server_lib_cfg *cfg,
dflet 0:547251f42a60 429 const struct mqtt_server_msg_cbs *cbs);
dflet 0:547251f42a60 430
dflet 0:547251f42a60 431 /** @} */ /* End of server_pktlib */
dflet 0:547251f42a60 432
dflet 0:547251f42a60 433 }//namespace mbed_mqtt
dflet 0:547251f42a60 434
dflet 0:547251f42a60 435 #ifdef __cplusplus
dflet 0:547251f42a60 436 }
dflet 0:547251f42a60 437 #endif
dflet 0:547251f42a60 438
dflet 0:547251f42a60 439 #endif
dflet 0:547251f42a60 440