David Fletcher / server

Part of TI's mqtt

Dependents:   mqtt_V1 cc3100_Test_mqtt_CM3

server_core.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
dflet 0:547251f42a60 17 #ifndef __SERVER_CORE_H__
dflet 0:547251f42a60 18 #define __SERVER_CORE_H__
dflet 0:547251f42a60 19
dflet 0:547251f42a60 20 #include "server_pkts.h"
dflet 0:547251f42a60 21
dflet 0:547251f42a60 22 #ifdef __cplusplus
dflet 0:547251f42a60 23 extern "C"
dflet 0:547251f42a60 24 {
dflet 0:547251f42a60 25 #endif
dflet 0:547251f42a60 26
dflet 0:547251f42a60 27 namespace mbed_mqtt {
dflet 0:547251f42a60 28
dflet 0:547251f42a60 29 /**@file server_core.h
dflet 0:547251f42a60 30 The MQTT server daemon, a task, provisions the high level abstractions for the
dflet 0:547251f42a60 31 smart applicaltions. This is an intelligent layer that utilizes the services
dflet 0:547251f42a60 32 of the MQTT Server Packet Library and is responsible for the functions of the
dflet 0:547251f42a60 33 topic management, the client management and support of multiple server
dflet 0:547251f42a60 34 applications.
dflet 0:547251f42a60 35
dflet 0:547251f42a60 36 The light-weight server enables the services of the MQTT protocol for an
dflet 0:547251f42a60 37 application to either extend and / or control the existing functions to suit
dflet 0:547251f42a60 38 the deployment specific scenario. These applications in practice are the
dflet 0:547251f42a60 39 plug-ins / add-ons to the core server functionalities. Specifically,
dflet 0:547251f42a60 40 these applications, among others capabilities, can be used for analyzing and
dflet 0:547251f42a60 41 approving the credentials of the remote clients, acting as a bridge between
dflet 0:547251f42a60 42 a MQTT external client and the server, and a snooper to learn about all the
dflet 0:547251f42a60 43 data transactions to / from the server.
dflet 0:547251f42a60 44
dflet 0:547251f42a60 45 The server is targeted to conform to MQTT 3.1.1 specification.
dflet 0:547251f42a60 46
dflet 0:547251f42a60 47 The services of the server are multi-task safe. Platform specific atomicity
dflet 0:547251f42a60 48 constructs are used, through abstractions, by the server to maintain data
dflet 0:547251f42a60 49 coherency and synchronization.
dflet 0:547251f42a60 50
dflet 0:547251f42a60 51 The server offers the following compile line configurable parameters (-D opt)
dflet 0:547251f42a60 52 - <b> CFG_SR_MAX_MQP_TX_LEN: </b> the constant buffer length allocated for a TX.
dflet 0:547251f42a60 53 \n\n
dflet 0:547251f42a60 54 - <b> CFG_SR_MAX_SUBTOP_LEN: </b> the maximum buffer size to hold a sub-topic.
dflet 0:547251f42a60 55 For e.g., in the topic /x/y/z, the phrase /x, /y and z are sub-topics.
dflet 0:547251f42a60 56 \n\n
dflet 0:547251f42a60 57 - <b> CFG_SR_MAX_TOPIC_NODE: </b> the maximum number of topic nodes in server.
dflet 0:547251f42a60 58 For e.g., in the topic /x/y/z, there are three nodes (/x, /y and z).
dflet 0:547251f42a60 59 \n\n
dflet 0:547251f42a60 60 - <b> CFG_SR_MAX_CL_ID_SIZE: </b> the maximum length of the client-id string.
dflet 0:547251f42a60 61 \n\n
dflet 0:547251f42a60 62 - <b> CFG_SR_MAX_NUM_CLIENT: </b> the maximum number of clients to be managed.
dflet 0:547251f42a60 63 Note this is different from the maximum number of 'contexts'. A large number
dflet 0:547251f42a60 64 of clients can be managed using fewer number of 'contexts' (connections).
dflet 0:547251f42a60 65 \n\n
dflet 0:547251f42a60 66
dflet 0:547251f42a60 67 @note Any future extensions & development must follow the following guidelines.
dflet 0:547251f42a60 68 A new API or an extension to the existing API
dflet 0:547251f42a60 69 a) must be rudimentary
dflet 0:547251f42a60 70 b) must not imply a rule or policy (including a state machine)
dflet 0:547251f42a60 71 b) must ensure simple design and implementation
dflet 0:547251f42a60 72 */
dflet 0:547251f42a60 73
dflet 0:547251f42a60 74
dflet 0:547251f42a60 75 /** @defgroup server_daemon The Server Daemon API(s)
dflet 0:547251f42a60 76 @{
dflet 0:547251f42a60 77 */
dflet 0:547251f42a60 78
dflet 0:547251f42a60 79 struct mqtt_server_app_cbs {
dflet 0:547251f42a60 80
dflet 0:547251f42a60 81 /** Connection request from remote client - assess credentials.
dflet 0:547251f42a60 82 This routine presents, to the application, the information about the
dflet 0:547251f42a60 83 credentials of the remote client that is trying to establish a MQTT
dflet 0:547251f42a60 84 connection with the server. The application shall utilize these data
dflet 0:547251f42a60 85 in conjunction with its policy to either allow or deny connection to
dflet 0:547251f42a60 86 the server.
dflet 0:547251f42a60 87
dflet 0:547251f42a60 88 Should the application choose to allow the remote client to establish
dflet 0:547251f42a60 89 a MQTT connection, then it must provide in 'app-user' (place-holder),
dflet 0:547251f42a60 90 a handle that refers to the user of this connection. The server will
dflet 0:547251f42a60 91 provide this handle in follow-up routines to enable the application
dflet 0:547251f42a60 92 to refer to the associated connection in its implementation.
dflet 0:547251f42a60 93
dflet 0:547251f42a60 94 @param[in] client_id UTF8 based ID of the remote client - is set to
dflet 0:547251f42a60 95 NULL to indicate a zero-length client id.
dflet 0:547251f42a60 96 @param[in] user_name UTF8 based user-name provided by the remote
dflet 0:547251f42a60 97 client. It is set to NULL if the client did not provide an user name
dflet 0:547251f42a60 98 @param[in] pass_word UTF8 based pass-word provided by the remote
dflet 0:547251f42a60 99 client. It is set to NULL if the client did not provide a pass-word
dflet 0:547251f42a60 100 @param[out] app_usr place-holder for application to provide a handle
dflet 0:547251f42a60 101 to the user of this specific connection / client.
dflet 0:547251f42a60 102
dflet 0:547251f42a60 103 @return 16bit value for the variable header in the CONNACK message.
dflet 0:547251f42a60 104 The MSB in the return value refers to the 8bit parameter of the
dflet 0:547251f42a60 105 acknowledge flags and must be set 0. The LSB in the return value
dflet 0:547251f42a60 106 refers to the 8bit 'return code' parameter in the CONNACK message
dflet 0:547251f42a60 107 and must be set accordingly.
dflet 0:547251f42a60 108 */
dflet 0:547251f42a60 109 uint16_t (*connect)(const struct utf8_string *client_id,
dflet 0:547251f42a60 110 const struct utf8_string *user_name,
dflet 0:547251f42a60 111 const struct utf8_string *pass_word,
dflet 0:547251f42a60 112 void **app_usr);
dflet 0:547251f42a60 113
dflet 0:547251f42a60 114 /** Indicate a PUBLISH message from the network.
dflet 0:547251f42a60 115 This routine presents, to the application, the topic and the related
dflet 0:547251f42a60 116 data along with other qualifiers published by one of the clients
dflet 0:547251f42a60 117 associated with this server. The application must enroll with the
dflet 0:547251f42a60 118 server the particular topic for which the data should be notified.
dflet 0:547251f42a60 119
dflet 0:547251f42a60 120 @param[in] topic UTF8 topic Name for which data has been published
dflet 0:547251f42a60 121 @param[in] data_buf the published binary data for the topic
dflet 0:547251f42a60 122 @param[in] data_len the length of the binary data
dflet 0:547251f42a60 123 @param[in] dup is this a duplicate data from remote client?
dflet 0:547251f42a60 124 @param[in] qos quality of service of the message / data
dflet 0:547251f42a60 125 @param[in] retain should the server retain the data?
dflet 0:547251f42a60 126
dflet 0:547251f42a60 127 @return none
dflet 0:547251f42a60 128 */
dflet 0:547251f42a60 129 void (*publish)(const struct utf8_string *topic,
dflet 0:547251f42a60 130 const uint8_t *payload, uint32_t pay_len,
dflet 0:547251f42a60 131 bool dup, uint8_t qos, bool retain);
dflet 0:547251f42a60 132
dflet 0:547251f42a60 133 /** Notify disconnection to the remote client.
dflet 0:547251f42a60 134 This routine is invoked by the server to declare to the application
dflet 0:547251f42a60 135 to a particular client has been terminated and follow-up, if needed,
dflet 0:547251f42a60 136 can now commence. This routine aids the application by indicating if
dflet 0:547251f42a60 137 an error condition had caused the disconnection.
dflet 0:547251f42a60 138
dflet 0:547251f42a60 139 @param[in] app_usr handle to refer to the user of the connection in
dflet 0:547251f42a60 140 the application
dflet 0:547251f42a60 141 @param[in] due2err has the connection been closed due to an error?
dflet 0:547251f42a60 142
dflet 0:547251f42a60 143 @return none
dflet 0:547251f42a60 144 */
dflet 0:547251f42a60 145 void (*disconn)(const void *app_usr, bool due2err);
dflet 0:547251f42a60 146 };
dflet 0:547251f42a60 147
dflet 0:547251f42a60 148 /** Enroll with server to receive data for a topic
dflet 0:547251f42a60 149 This routine registers with the server, the specified topic for which the
dflet 0:547251f42a60 150 application should receive any published data from the network. Whenever,
dflet 0:547251f42a60 151 any of the remote clients that are connected to the server or applications,
dflet 0:547251f42a60 152 this or other, publishes data for the specified topic, the server will
dflet 0:547251f42a60 153 present the published information to this application.
dflet 0:547251f42a60 154
dflet 0:547251f42a60 155 As part of the enrollment, the application should provide the maxmimum QoS
dflet 0:547251f42a60 156 with which the server should provide the published data. If the topic data
dflet 0:547251f42a60 157 received by the server bears a QoS higher than the one specified by the
dflet 0:547251f42a60 158 application, the server shall lower it to the QoS level preferred by the
dflet 0:547251f42a60 159 application. Otherwise, the QoS of the data shall be presented 'as-is'. In
dflet 0:547251f42a60 160 other words, the application should expect a published data with a lower QoS.
dflet 0:547251f42a60 161
dflet 0:547251f42a60 162 @param[in] app_hnd handle to the application context in the server. This
dflet 0:547251f42a60 163 handle is provided by server @ref mqtt_server_app_register()
dflet 0:547251f42a60 164 @param[in] topic UTF8 based string for which the application needs to start
dflet 0:547251f42a60 165 getting the published data
dflet 0:547251f42a60 166 @param[in] qos the meximum QoS the application intends to receive data for
dflet 0:547251f42a60 167 this particular topic
dflet 0:547251f42a60 168
dflet 0:547251f42a60 169 @return 0 on sucess, otherwise a negative value on error.
dflet 0:547251f42a60 170 */
dflet 0:547251f42a60 171 int32_t mqtt_server_topic_enroll(const void *app_hnd,
dflet 0:547251f42a60 172 const struct utf8_string *topic, enum mqtt_qos qos);
dflet 0:547251f42a60 173
dflet 0:547251f42a60 174 /** Cancel previous enrollment to receive data for a topic
dflet 0:547251f42a60 175 This routines terminates the previous registration, if any, made by the
dflet 0:547251f42a60 176 application to receive any publishised data for the specified topic. Once,
dflet 0:547251f42a60 177 the enrollment is removed, the application, there after, will not receive
dflet 0:547251f42a60 178 any data for this topic from the server.
dflet 0:547251f42a60 179
dflet 0:547251f42a60 180 @param[in] app_hnd handle to the application context in the server. This
dflet 0:547251f42a60 181 handle is provided by server @ref mqtt_server_app_register()
dflet 0:547251f42a60 182 @param[in] topic UTF8 based string for which the application needs to stop
dflet 0:547251f42a60 183 getting the published data
dflet 0:547251f42a60 184
dflet 0:547251f42a60 185 @return 0 on success, otherwise a negative value on error.
dflet 0:547251f42a60 186 */
dflet 0:547251f42a60 187 int32_t mqtt_server_topic_disenroll(const void *app_hnd,
dflet 0:547251f42a60 188 const struct utf8_string *topic);
dflet 0:547251f42a60 189
dflet 0:547251f42a60 190 /** Send data to network for a topic
dflet 0:547251f42a60 191 This routine offers the binary data along-with associated properties for a
dflet 0:547251f42a60 192 specific topic to the server. The server, based on the subscriptions from the
dflet 0:547251f42a60 193 remote clients and the enrollments made by the local applications for this
dflet 0:547251f42a60 194 topic, will send the binary data and its qualifiers, adjusted for the maximum
dflet 0:547251f42a60 195 subscribed or enrolled QoS, to the remote clients and the local applications.
dflet 0:547251f42a60 196
dflet 0:547251f42a60 197 @param[in] topic UTF8 topic Name for which data has been published
dflet 0:547251f42a60 198 @param[in] data_buf the published binary data for the topic
dflet 0:547251f42a60 199 @param[in] data_len the length of the binary data
dflet 0:547251f42a60 200 @param[in] qos quality of service of the message / data
dflet 0:547251f42a60 201 @param[in] retain should the server retain the data?
dflet 0:547251f42a60 202
dflet 0:547251f42a60 203 @return on success, the length of data sent, otherwise -1 on error.
dflet 0:547251f42a60 204 */
dflet 0:547251f42a60 205 int32_t mqtt_server_app_pub_send(const struct utf8_string *topic,
dflet 0:547251f42a60 206 const uint8_t *data_buf, uint32_t data_len,
dflet 0:547251f42a60 207 enum mqtt_qos qos, bool retain);
dflet 0:547251f42a60 208
dflet 0:547251f42a60 209 /** Register an application with the server.
dflet 0:547251f42a60 210 This routine makes known to the server about an application identified by
dflet 0:547251f42a60 211 its name and creates a context / reference for the application in the
dflet 0:547251f42a60 212 server.
dflet 0:547251f42a60 213
dflet 0:547251f42a60 214 An application intending to utlize the servicse of the MQTT server must be
dflet 0:547251f42a60 215 first registered with the server.
dflet 0:547251f42a60 216
dflet 0:547251f42a60 217 @param[in] cbs callback routines from the application to be invoked by the
dflet 0:547251f42a60 218 server
dflet 0:547251f42a60 219 @param[in] name refers to the name of the application. The application must
dflet 0:547251f42a60 220 retain the memory used by the 'name' after the function call. The server
dflet 0:547251f42a60 221 does not copy the name into its internal buffers.
dflet 0:547251f42a60 222
dflet 0:547251f42a60 223 @return a valid handle to context of application in the server, othewise
dflet 0:547251f42a60 224 NULL on error
dflet 0:547251f42a60 225 */
dflet 0:547251f42a60 226 void *mqtt_server_app_register(const struct mqtt_server_app_cbs *cbs,
dflet 0:547251f42a60 227 const char *name);
dflet 0:547251f42a60 228
dflet 0:547251f42a60 229
dflet 0:547251f42a60 230 /** Configuration for the applications that utilize the MQTT Server Daemon.
dflet 0:547251f42a60 231 At the moment this configuration is not used and has been incorporated
dflet 0:547251f42a60 232 to support forward compatibility (future use)
dflet 0:547251f42a60 233 */
dflet 0:547251f42a60 234 struct mqtt_server_app_cfg {
dflet 0:547251f42a60 235
dflet 0:547251f42a60 236 void *place_holder; /**< Dummy, not used as of now */
dflet 0:547251f42a60 237 };
dflet 0:547251f42a60 238
dflet 0:547251f42a60 239 /** Initialize the MQTT Server (Task / Daemon).
dflet 0:547251f42a60 240 This routine initializes the server implementation and sets it up using
dflet 0:547251f42a60 241 the provided configuration. The server implementation must be initialized
dflet 0:547251f42a60 242 prior to invoking of any other routine or service.
dflet 0:547251f42a60 243
dflet 0:547251f42a60 244 This routine should be invoked as part of the platform initialization.
dflet 0:547251f42a60 245
dflet 0:547251f42a60 246 @note This routine must be invoked only once in an run of the system. This
dflet 0:547251f42a60 247 routine internally invokes the @ref mqtt_server_lib_init( ) and therefore,
dflet 0:547251f42a60 248 there is no need to invoke the @ref mqtt_server_lib_init( ) explicitly.
dflet 0:547251f42a60 249
dflet 0:547251f42a60 250 The server needs to be in a state to listen to incoming MQTT connection
dflet 0:547251f42a60 251 requests. Therefore, the platform sequence after provisioning the buffer
dflet 0:547251f42a60 252 using the API @ref mqtt_server_register_net_svc, must invoke the API @ref
dflet 0:547251f42a60 253 mqtt_server_run, in an infinite loop, to keep the server daemon active.
dflet 0:547251f42a60 254
dflet 0:547251f42a60 255 @param[in] lib_cfg configuration information for the MQTT server packet
dflet 0:547251f42a60 256 library.
dflet 0:547251f42a60 257 @param[in] app_cfg configuration information for the server applications.
dflet 0:547251f42a60 258
dflet 0:547251f42a60 259 @return 0 on success, otherwise -1 on error
dflet 0:547251f42a60 260 */
dflet 0:547251f42a60 261 int32_t mqtt_server_init(const struct mqtt_server_lib_cfg *lib_cfg,
dflet 0:547251f42a60 262 const struct mqtt_server_app_cfg *app_cfg);
dflet 0:547251f42a60 263
dflet 0:547251f42a60 264 /** @} */ /* End of server_daemon */
dflet 0:547251f42a60 265
dflet 0:547251f42a60 266 }//namespace mbed_mqtt
dflet 0:547251f42a60 267
dflet 0:547251f42a60 268 #ifdef __cplusplus
dflet 0:547251f42a60 269 }
dflet 0:547251f42a60 270 #endif
dflet 0:547251f42a60 271
dflet 0:547251f42a60 272 #endif
dflet 0:547251f42a60 273
dflet 0:547251f42a60 274