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