Part of TI's mqtt
Dependents: mqtt_V1 cc3100_Test_mqtt_CM3
Diff: server_core.h
- Revision:
- 0:547251f42a60
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/server_core.h Sat Jun 06 13:29:08 2015 +0000 @@ -0,0 +1,274 @@ +/****************************************************************************** +* +* Copyright (C) 2014 Texas Instruments Incorporated +* +* All rights reserved. Property of Texas Instruments Incorporated. +* Restricted rights to use, duplicate or disclose this code are +* granted through contract. +* +* The program may not be used without the written permission of +* Texas Instruments Incorporated or against the terms and conditions +* stipulated in the agreement under which this program has been supplied, +* and under no circumstances can it be used with non-TI connectivity device. +* +******************************************************************************/ + + +#ifndef __SERVER_CORE_H__ +#define __SERVER_CORE_H__ + +#include "server_pkts.h" + +#ifdef __cplusplus +extern "C" +{ +#endif + +namespace mbed_mqtt { + +/**@file server_core.h + The MQTT server daemon, a task, provisions the high level abstractions for the + smart applicaltions. This is an intelligent layer that utilizes the services + of the MQTT Server Packet Library and is responsible for the functions of the + topic management, the client management and support of multiple server + applications. + + The light-weight server enables the services of the MQTT protocol for an + application to either extend and / or control the existing functions to suit + the deployment specific scenario. These applications in practice are the + plug-ins / add-ons to the core server functionalities. Specifically, + these applications, among others capabilities, can be used for analyzing and + approving the credentials of the remote clients, acting as a bridge between + a MQTT external client and the server, and a snooper to learn about all the + data transactions to / from the server. + + The server is targeted to conform to MQTT 3.1.1 specification. + + The services of the server are multi-task safe. Platform specific atomicity + constructs are used, through abstractions, by the server to maintain data + coherency and synchronization. + + The server offers the following compile line configurable parameters (-D opt) + - <b> CFG_SR_MAX_MQP_TX_LEN: </b> the constant buffer length allocated for a TX. + \n\n + - <b> CFG_SR_MAX_SUBTOP_LEN: </b> the maximum buffer size to hold a sub-topic. + For e.g., in the topic /x/y/z, the phrase /x, /y and z are sub-topics. + \n\n + - <b> CFG_SR_MAX_TOPIC_NODE: </b> the maximum number of topic nodes in server. + For e.g., in the topic /x/y/z, there are three nodes (/x, /y and z). + \n\n + - <b> CFG_SR_MAX_CL_ID_SIZE: </b> the maximum length of the client-id string. + \n\n + - <b> CFG_SR_MAX_NUM_CLIENT: </b> the maximum number of clients to be managed. + Note this is different from the maximum number of 'contexts'. A large number + of clients can be managed using fewer number of 'contexts' (connections). + \n\n + + @note Any future extensions & development must follow the following guidelines. + A new API or an extension to the existing API + a) must be rudimentary + b) must not imply a rule or policy (including a state machine) + b) must ensure simple design and implementation +*/ + + +/** @defgroup server_daemon The Server Daemon API(s) + @{ +*/ + +struct mqtt_server_app_cbs { + + /** Connection request from remote client - assess credentials. + This routine presents, to the application, the information about the + credentials of the remote client that is trying to establish a MQTT + connection with the server. The application shall utilize these data + in conjunction with its policy to either allow or deny connection to + the server. + + Should the application choose to allow the remote client to establish + a MQTT connection, then it must provide in 'app-user' (place-holder), + a handle that refers to the user of this connection. The server will + provide this handle in follow-up routines to enable the application + to refer to the associated connection in its implementation. + + @param[in] client_id UTF8 based ID of the remote client - is set to + NULL to indicate a zero-length client id. + @param[in] user_name UTF8 based user-name provided by the remote + client. It is set to NULL if the client did not provide an user name + @param[in] pass_word UTF8 based pass-word provided by the remote + client. It is set to NULL if the client did not provide a pass-word + @param[out] app_usr place-holder for application to provide a handle + to the user of this specific connection / client. + + @return 16bit value for the variable header in the CONNACK message. + The MSB in the return value refers to the 8bit parameter of the + acknowledge flags and must be set 0. The LSB in the return value + refers to the 8bit 'return code' parameter in the CONNACK message + and must be set accordingly. + */ + uint16_t (*connect)(const struct utf8_string *client_id, + const struct utf8_string *user_name, + const struct utf8_string *pass_word, + void **app_usr); + + /** Indicate a PUBLISH message from the network. + This routine presents, to the application, the topic and the related + data along with other qualifiers published by one of the clients + associated with this server. The application must enroll with the + server the particular topic for which the data should be notified. + + @param[in] topic UTF8 topic Name for which data has been published + @param[in] data_buf the published binary data for the topic + @param[in] data_len the length of the binary data + @param[in] dup is this a duplicate data from remote client? + @param[in] qos quality of service of the message / data + @param[in] retain should the server retain the data? + + @return none + */ + void (*publish)(const struct utf8_string *topic, + const uint8_t *payload, uint32_t pay_len, + bool dup, uint8_t qos, bool retain); + + /** Notify disconnection to the remote client. + This routine is invoked by the server to declare to the application + to a particular client has been terminated and follow-up, if needed, + can now commence. This routine aids the application by indicating if + an error condition had caused the disconnection. + + @param[in] app_usr handle to refer to the user of the connection in + the application + @param[in] due2err has the connection been closed due to an error? + + @return none + */ + void (*disconn)(const void *app_usr, bool due2err); +}; + +/** Enroll with server to receive data for a topic + This routine registers with the server, the specified topic for which the + application should receive any published data from the network. Whenever, + any of the remote clients that are connected to the server or applications, + this or other, publishes data for the specified topic, the server will + present the published information to this application. + + As part of the enrollment, the application should provide the maxmimum QoS + with which the server should provide the published data. If the topic data + received by the server bears a QoS higher than the one specified by the + application, the server shall lower it to the QoS level preferred by the + application. Otherwise, the QoS of the data shall be presented 'as-is'. In + other words, the application should expect a published data with a lower QoS. + + @param[in] app_hnd handle to the application context in the server. This + handle is provided by server @ref mqtt_server_app_register() + @param[in] topic UTF8 based string for which the application needs to start + getting the published data + @param[in] qos the meximum QoS the application intends to receive data for + this particular topic + + @return 0 on sucess, otherwise a negative value on error. +*/ +int32_t mqtt_server_topic_enroll(const void *app_hnd, + const struct utf8_string *topic, enum mqtt_qos qos); + +/** Cancel previous enrollment to receive data for a topic + This routines terminates the previous registration, if any, made by the + application to receive any publishised data for the specified topic. Once, + the enrollment is removed, the application, there after, will not receive + any data for this topic from the server. + + @param[in] app_hnd handle to the application context in the server. This + handle is provided by server @ref mqtt_server_app_register() + @param[in] topic UTF8 based string for which the application needs to stop + getting the published data + + @return 0 on success, otherwise a negative value on error. +*/ +int32_t mqtt_server_topic_disenroll(const void *app_hnd, + const struct utf8_string *topic); + +/** Send data to network for a topic + This routine offers the binary data along-with associated properties for a + specific topic to the server. The server, based on the subscriptions from the + remote clients and the enrollments made by the local applications for this + topic, will send the binary data and its qualifiers, adjusted for the maximum + subscribed or enrolled QoS, to the remote clients and the local applications. + + @param[in] topic UTF8 topic Name for which data has been published + @param[in] data_buf the published binary data for the topic + @param[in] data_len the length of the binary data + @param[in] qos quality of service of the message / data + @param[in] retain should the server retain the data? + + @return on success, the length of data sent, otherwise -1 on error. +*/ +int32_t mqtt_server_app_pub_send(const struct utf8_string *topic, + const uint8_t *data_buf, uint32_t data_len, + enum mqtt_qos qos, bool retain); + +/** Register an application with the server. + This routine makes known to the server about an application identified by + its name and creates a context / reference for the application in the + server. + + An application intending to utlize the servicse of the MQTT server must be + first registered with the server. + + @param[in] cbs callback routines from the application to be invoked by the + server + @param[in] name refers to the name of the application. The application must + retain the memory used by the 'name' after the function call. The server + does not copy the name into its internal buffers. + + @return a valid handle to context of application in the server, othewise + NULL on error +*/ +void *mqtt_server_app_register(const struct mqtt_server_app_cbs *cbs, + const char *name); + + +/** Configuration for the applications that utilize the MQTT Server Daemon. + At the moment this configuration is not used and has been incorporated + to support forward compatibility (future use) +*/ +struct mqtt_server_app_cfg { + + void *place_holder; /**< Dummy, not used as of now */ +}; + +/** Initialize the MQTT Server (Task / Daemon). + This routine initializes the server implementation and sets it up using + the provided configuration. The server implementation must be initialized + prior to invoking of any other routine or service. + + This routine should be invoked as part of the platform initialization. + + @note This routine must be invoked only once in an run of the system. This + routine internally invokes the @ref mqtt_server_lib_init( ) and therefore, + there is no need to invoke the @ref mqtt_server_lib_init( ) explicitly. + + The server needs to be in a state to listen to incoming MQTT connection + requests. Therefore, the platform sequence after provisioning the buffer + using the API @ref mqtt_server_register_net_svc, must invoke the API @ref + mqtt_server_run, in an infinite loop, to keep the server daemon active. + + @param[in] lib_cfg configuration information for the MQTT server packet + library. + @param[in] app_cfg configuration information for the server applications. + + @return 0 on success, otherwise -1 on error +*/ +int32_t mqtt_server_init(const struct mqtt_server_lib_cfg *lib_cfg, + const struct mqtt_server_app_cfg *app_cfg); + +/** @} */ /* End of server_daemon */ + +}//namespace mbed_mqtt + +#ifdef __cplusplus +} +#endif + +#endif + +