server_core.h

00001 /******************************************************************************
00002 *
00003 *   Copyright (C) 2014 Texas Instruments Incorporated
00004 *
00005 *   All rights reserved. Property of Texas Instruments Incorporated.
00006 *   Restricted rights to use, duplicate or disclose this code are
00007 *   granted through contract.
00008 *
00009 *   The program may not be used without the written permission of
00010 *   Texas Instruments Incorporated or against the terms and conditions
00011 *   stipulated in the agreement under which this program has been supplied,
00012 *   and under no circumstances can it be used with non-TI connectivity device.
00013 *
00014 ******************************************************************************/
00015 
00016 
00017 #ifndef __SERVER_CORE_H__
00018 #define __SERVER_CORE_H__
00019 
00020 #include "server_pkts.h"
00021 
00022 #ifdef __cplusplus
00023 extern "C"
00024 {
00025 #endif
00026 
00027 namespace mbed_mqtt {
00028 
00029 /**@file server_core.h
00030    The MQTT server daemon, a task, provisions the high level abstractions for the
00031    smart applicaltions. This is an intelligent layer that utilizes the services
00032    of the MQTT Server Packet Library and is responsible for the functions of the
00033    topic management, the client management and support of multiple server
00034    applications.
00035 
00036    The light-weight server enables the services of the MQTT protocol for an
00037    application to either extend and / or control the existing functions to suit
00038    the deployment specific scenario. These applications in practice are the
00039    plug-ins / add-ons to the core server functionalities. Specifically,
00040    these applications, among others capabilities, can be used for analyzing and
00041    approving the credentials of the remote clients, acting as a bridge between
00042    a MQTT external client and the server, and a snooper to learn about all the
00043    data transactions to / from the server.
00044 
00045    The server is targeted to conform to MQTT 3.1.1 specification.
00046 
00047    The services of the server are multi-task safe. Platform specific atomicity
00048    constructs are used, through abstractions, by the server to maintain data
00049    coherency and synchronization.
00050 
00051    The server offers the following compile line configurable parameters (-D opt)
00052    - <b> CFG_SR_MAX_MQP_TX_LEN: </b> the constant buffer length allocated for a TX.
00053    \n\n
00054    - <b> CFG_SR_MAX_SUBTOP_LEN: </b> the maximum buffer size to hold a sub-topic.
00055    For e.g., in the topic /x/y/z, the phrase /x, /y and z are sub-topics.
00056    \n\n
00057    - <b> CFG_SR_MAX_TOPIC_NODE: </b> the maximum number of topic nodes in server.
00058    For e.g., in the topic /x/y/z, there are three nodes (/x, /y and z).
00059    \n\n
00060    - <b> CFG_SR_MAX_CL_ID_SIZE: </b> the maximum length of the client-id string.
00061    \n\n
00062    - <b> CFG_SR_MAX_NUM_CLIENT: </b> the maximum number of clients to be managed.
00063    Note this is different from the maximum number of 'contexts'. A large number
00064    of clients can be managed using fewer number of 'contexts' (connections).
00065    \n\n
00066 
00067    @note Any future extensions & development must follow the following guidelines.
00068    A new API or an extension to the existing API
00069    a) must be rudimentary
00070    b) must not imply a rule or policy (including a state machine)
00071    b) must ensure simple design and implementation
00072 */
00073 
00074 
00075 /** @defgroup server_daemon The Server Daemon API(s)
00076     @{
00077 */
00078 
00079 struct mqtt_server_app_cbs {
00080 
00081         /** Connection request from remote client - assess credentials.
00082             This routine presents, to the application, the information about the
00083             credentials of the remote client that is trying to establish a MQTT
00084             connection with the server. The application shall utilize these data
00085             in conjunction with its policy to either allow or deny connection to
00086             the server.
00087 
00088             Should the application choose to allow the remote client to establish
00089             a MQTT connection, then it must provide in 'app-user' (place-holder),
00090             a handle that refers to the user of this connection. The server will
00091             provide this handle in follow-up routines to enable the application
00092             to refer to the associated connection in its implementation.
00093 
00094             @param[in] client_id UTF8 based ID of the remote client - is set to
00095             NULL to indicate a zero-length client id.
00096             @param[in] user_name UTF8 based user-name provided by the remote
00097             client. It is set to NULL if the client did not provide an user name
00098             @param[in] pass_word UTF8 based pass-word provided by the remote
00099             client. It is set to NULL if the client did not provide a pass-word
00100             @param[out] app_usr place-holder for application to provide a handle
00101             to the user of this specific connection / client.
00102             
00103             @return 16bit value for the variable header in the CONNACK message.
00104             The MSB in the return value refers to the 8bit parameter of the
00105             acknowledge flags and must be set 0. The LSB in the return value
00106             refers to the 8bit 'return code' parameter in the CONNACK message
00107             and must be set accordingly.
00108         */
00109         uint16_t  (*connect)(const struct utf8_string *client_id,
00110                         const struct utf8_string *user_name,
00111                         const struct utf8_string *pass_word,
00112                         void **app_usr);
00113 
00114         /** Indicate a PUBLISH message from the network.
00115             This routine presents, to the application, the topic and the related
00116             data along with other qualifiers  published by one of the clients
00117             associated with this server. The application must enroll with the
00118             server the particular topic for which the data should be notified.
00119             
00120             @param[in] topic UTF8 topic Name for which data has been published
00121             @param[in] data_buf the published binary data for the topic
00122             @param[in] data_len the length of the binary data
00123             @param[in] dup is this a duplicate data from remote client? 
00124             @param[in] qos quality of service of the message / data
00125             @param[in] retain should the server retain the data?
00126 
00127             @return none
00128         */
00129         void (*publish)(const struct utf8_string *topic,
00130                         const uint8_t *payload, uint32_t pay_len,
00131                         bool dup, uint8_t qos, bool retain);
00132 
00133         /** Notify disconnection to the remote client.
00134             This routine is invoked by the server to declare to the application
00135             to a particular client has been terminated and follow-up, if needed,
00136             can now commence. This routine aids the application by indicating if
00137             an error condition had caused the disconnection.
00138 
00139             @param[in] app_usr handle to refer to the user of the connection in
00140             the application
00141             @param[in] due2err has the connection been closed due to an error?
00142 
00143             @return none
00144         */
00145         void (*disconn)(const void *app_usr, bool due2err);
00146 };
00147 
00148 /** Enroll with server to receive data for a topic 
00149     This routine registers with the server, the specified topic for which the
00150     application should receive any published data from the network. Whenever,
00151     any of the remote clients that are connected to the server or applications,
00152     this or other, publishes data for the specified topic, the server will
00153     present the published information to this application.
00154 
00155     As part of the enrollment, the application should provide the maxmimum QoS
00156     with which the server should provide the published data. If the topic data
00157     received by the server bears a QoS higher than the one specified by the
00158     application, the server shall lower it to the QoS level preferred by the
00159     application. Otherwise, the QoS of the data shall be presented 'as-is'. In
00160     other words, the application should expect a published data with a lower QoS.
00161 
00162     @param[in] app_hnd handle to the application context in the server. This
00163     handle is provided by server @ref mqtt_server_app_register()
00164     @param[in] topic UTF8 based string for which the application needs to start
00165     getting the published data
00166     @param[in] qos the meximum QoS the application intends to receive data for
00167     this particular topic
00168 
00169     @return 0 on sucess, otherwise a negative value on error.
00170 */
00171 int32_t mqtt_server_topic_enroll(const void *app_hnd,
00172                              const struct utf8_string *topic, enum mqtt_qos qos);
00173 
00174 /** Cancel previous enrollment to receive data for a topic
00175     This routines terminates the previous registration, if any, made by the
00176     application to receive any publishised data for the specified topic. Once,
00177     the enrollment is removed, the application, there after, will not receive
00178     any data for this topic from the server.
00179 
00180     @param[in] app_hnd handle to the application context in the server. This
00181     handle is provided by server @ref mqtt_server_app_register()
00182     @param[in] topic UTF8 based string for which the application needs to stop
00183     getting the published data
00184 
00185     @return 0 on success, otherwise a negative value on error.
00186 */
00187 int32_t mqtt_server_topic_disenroll(const void *app_hnd,
00188                                 const struct utf8_string *topic);
00189 
00190 /** Send data to network for a topic
00191     This routine offers the binary data along-with associated properties for a
00192     specific topic to the server. The server, based on the subscriptions from the
00193     remote clients and the enrollments made by the local applications for this
00194     topic, will send the binary data and its qualifiers, adjusted for the maximum
00195     subscribed or enrolled QoS, to the remote clients and the local applications.
00196 
00197     @param[in] topic UTF8 topic Name for which data has been published
00198     @param[in] data_buf the published binary data for the topic
00199     @param[in] data_len the length of the binary data
00200     @param[in] qos quality of service of the message / data
00201     @param[in] retain should the server retain the data?
00202 
00203     @return on success, the length of data sent, otherwise -1 on error.
00204 */
00205 int32_t mqtt_server_app_pub_send(const  struct utf8_string *topic,
00206                              const uint8_t *data_buf, uint32_t data_len,
00207                              enum mqtt_qos qos, bool retain);
00208 
00209 /** Register an application with the server.
00210     This routine makes known to the server about an application identified by
00211     its name and creates a context / reference for the application in the
00212     server.
00213 
00214     An application intending to utlize the servicse of the MQTT server must be
00215     first registered with the server.
00216 
00217     @param[in] cbs callback routines from the application to be invoked by the
00218     server
00219     @param[in] name refers to the name of the application. The application must
00220     retain the memory used by the 'name' after the function call. The server
00221     does not copy the name into its internal buffers.
00222 
00223     @return a valid handle to context of application in the server, othewise
00224     NULL on error
00225 */
00226 void *mqtt_server_app_register(const struct mqtt_server_app_cbs *cbs,
00227                                const char *name);
00228 
00229 
00230 /** Configuration for the applications that utilize the MQTT Server Daemon.
00231     At the moment this configuration is not used and has been incorporated
00232     to support forward compatibility (future use)
00233 */
00234 struct mqtt_server_app_cfg {
00235 
00236         void        *place_holder; /**< Dummy, not used as of now */
00237 };
00238 
00239 /** Initialize the MQTT Server (Task / Daemon).
00240     This routine initializes the server implementation and sets it up using
00241     the provided configuration. The server implementation must be initialized
00242     prior to invoking of any other routine or service.
00243 
00244     This routine should be invoked as part of the platform initialization.
00245 
00246     @note This routine must be invoked only once in an run of the system. This
00247     routine internally invokes the @ref mqtt_server_lib_init( ) and therefore,
00248     there is no need to invoke the @ref mqtt_server_lib_init( ) explicitly.
00249 
00250     The server needs to be in a state to listen to incoming MQTT connection
00251     requests. Therefore, the platform sequence after provisioning the buffer
00252     using the API @ref mqtt_server_register_net_svc, must invoke the API @ref
00253     mqtt_server_run, in an infinite loop, to keep the server daemon active.
00254 
00255     @param[in] lib_cfg configuration information for the MQTT server packet
00256     library.
00257     @param[in] app_cfg configuration information for the server applications.
00258 
00259     @return 0 on success, otherwise -1 on error
00260 */
00261 int32_t mqtt_server_init(const struct mqtt_server_lib_cfg *lib_cfg,
00262                      const struct mqtt_server_app_cfg *app_cfg);
00263 
00264 /** @} */ /* End of server_daemon */
00265 
00266 }//namespace mbed_mqtt 
00267 
00268 #ifdef __cplusplus  
00269 }
00270 #endif 
00271 
00272 #endif
00273 
00274