sl_mqtt_server.h

00001 /*******************************************************************************
00002 Copyright (c) (2014) Texas Instruments Incorporated
00003 All rights reserved not granted herein.
00004 
00005 Limited License.  
00006 
00007 Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive 
00008 license under copyrights and patents it now or hereafter owns or controls to make, 
00009 have made, use, import, offer to sell and sell ("Utilize") this software subject 
00010 to the terms herein.  With respect to the foregoing patent license, such license 
00011 is granted  solely to the extent that any such patent is necessary to Utilize the 
00012 software alone.  The patent license shall not apply to any combinations which 
00013 include this software, other than combinations with devices manufactured by or 
00014 for TI (�TI Devices�).  No hardware patent is licensed hereunder.
00015 
00016 Redistributions must preserve existing copyright notices and reproduce this license 
00017 (including the above copyright notice and the disclaimer and (if applicable) source 
00018 code license limitations below) in the documentation and/or other materials provided 
00019 with the distribution
00020 
00021 Redistribution and use in binary form, without modification, are permitted provided 
00022 that the following conditions are met:
00023 * No reverse engineering, decompilation, or disassembly of this software is 
00024   permitted with respect to any software provided in binary form.
00025 * any redistribution and use are licensed by TI for use only with TI Devices.
00026 * Nothing shall obligate TI to provide you with source code for the software 
00027   licensed and provided to you in object code.
00028 
00029 If software source code is provided to you, modification and redistribution of the 
00030 source code are permitted provided that the following conditions are met;
00031 * any redistribution and use of the source code, including any resulting derivative 
00032   works, are licensed by TI for use only with TI Devices.
00033 * any redistribution and use of any object code compiled from the source code and 
00034   any resulting derivative works, are licensed by TI for use only with TI Devices.
00035 
00036 Neither the name of Texas Instruments Incorporated nor the names of its suppliers 
00037 may be used to endorse or promote products derived from this software without 
00038 specific prior written permission.
00039 
00040 DISCLAIMER.
00041 
00042 THIS SOFTWARE IS PROVIDED BY TI AND TI�S LICENSORS "AS IS" AND ANY EXPRESS OR IMPLIED 
00043 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 
00044 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TI AND TI�S 
00045 LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
00046 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
00047 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
00048 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
00049 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
00050 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00051 
00052 ******************************************************************************/
00053 
00054 #include <stdio.h>
00055 #include <string.h>
00056 #include <stdbool.h>
00057 #include "cc3100_simplelink.h"
00058 
00059 #ifndef __SL_MQTT_SRVR_H__
00060 #define __SL_MQTT_SRVR_H__
00061 
00062 #ifdef __cplusplus
00063 extern "C"
00064 {
00065 #endif
00066 
00067 namespace mbed_mqtt {
00068 
00069         /*!
00070           \mainpage SimpleLink MQTT Server Layer
00071           
00072           \section intro_sec Introduction
00073 
00074           The SimpleLink MQTT Server Layer provides an easy-to-use API(s) to enable
00075           constrained and deeply embedded microcontroller based products to interact
00076           with cloud or network based clients for telemetry. The users of SL MQTT
00077           server services, while benefiting from the abstraction of the MQTT protocol
00078           would find them suitable for development of MQTT Servers.
00079 
00080                    
00081           \section descrypt_sec Description
00082 
00083           The SL MQTT Server Layer, in addition to providing services to the server
00084           application, encompasses an RTOS task to handle the incoming messages from the
00085           various clients conencted to the server.
00086           Such a dedicated context to process the messages from the clients facilitates the
00087           app to receive data (for ex. PUBLISH messages) even when it is 
00088           transacting with another client. This is important considering that a server 
00089           application has to manage messages from multiple clients connected
00090           to it simulatneously.
00091           The receive task in the SL MQTT Server Layer can not be disabled anytime, 
00092           however its system wide priority is configurable and can be set.
00093 
00094           Some of the salient features of the SL MQTT Layer are 
00095           
00096           - Easy-to-use, intuitive and small set of MQTT API
00097           - App can indicate its choice to await ACK for a message transaction
00098 
00099           \section config_sec Configurations
00100           The SL implementation enables the application developers to configure the
00101       following parameters using the compile line flags (-D option):
00102           - <b> CFG_SR_MAX_MQP_RX_LEN</b> max length of the RX buffer for the server.
00103           - <b> CFG_SR_MAX_MQP_TX_LEN: </b> the constant buffer length allocated for a TX.\n\n
00104           - <b> CFG_SR_MAX_SUBTOP_LEN: </b> the maximum buffer size to hold a sub-topic.
00105           For e.g., in the topic /x/y/z, the phrase /x, /y and z are sub-topics. \n\n
00106           - <b> CFG_SR_MAX_TOPIC_NODE: </b> the maximum number of topic nodes in server.
00107           For e.g., in the topic /x/y/z, there are three nodes (/x, /y and z). \n\n
00108           - <b> CFG_SR_MAX_CL_ID_SIZE: </b> the maximum length of the client-id string. \n\n
00109           - <b> CFG_SR_MAX_NUM_CLIENT: </b> the maximum number of clients to be managed.
00110           Note this is different from the maximum number of 'contexts'. A large number
00111           of clients can be managed using fewer number of 'contexts' (connections). \n\n
00112 
00113           \note An app that has chosen not to await an ACK from the client for a
00114           scheduled transaction can benefit from the availability of control to
00115           pursue other activities to make overall progress in the system. However,
00116           an attempt to schedule another transaction with the client, while the
00117           previous one is still active, will cause the application to block. The
00118           app will unblock, once the previous transaction is completed.         
00119 
00120         */
00121 
00122         /** @defgroup sl_mqtt_srvr_api SL MQTT Server APIs
00123             @{
00124         */
00125   
00126         /** @defgroup sl_mqtt_srvr_evt SL MQTT Server Events
00127             @{ 
00128         */
00129 #define SL_MQTT_SRVR_EVT_PUBACK   0x11  /**< PUBACK has been received from a client */
00130 #define SL_MQTT_SRVR_EVT_NOCONN   0x12  /**< Server has lost network connection with a client */
00131         /** @} */ /* End SL MQTT Server events */
00132         
00133            
00134         /** Callbacks Routines
00135             The routines are invoked by SL MQTT Server Implementation onto Server application
00136 
00137             * \note The user applications implement the callbacks that are registered 
00138                     with the libraries. While using the MQTT library, invoking the 
00139                     core library APIs from a callback should be avoided and 
00140                     can lead to lockup scenarios. It is recommended to signal another 
00141                     task from the callback routines invoked from the library 
00142                     and invoke the core library API calls from that task.
00143          */
00144         typedef struct {
00145                 
00146                 /** Connect Request: Callback routine to indicate to server application that a CONNECT 
00147                 request has been received by the server.
00148                                         
00149                     \param[in] clientId_str clientId field in the CONNECT message received.
00150                     \param[in] clientId_len length of ClientId
00151                     \param[in] username_str Username field in teh CONNECT message received.
00152                     \param[in] username_len length of username
00153                     \param[in] password_str Password field in the CONNECT message received.
00154                     \param[in] password_len length of password
00155                     \param[out] usr placeholder to provision app's handle to this connection.
00156                     \return 0x0000 or 0x0100 for success; Otherwise 0x02, 0x04 or 0x05 
00157                     refer to spec for connack codes
00158                     
00159                 */
00160                 uint8_t  (*sl_ExtLib_MqttConn)(const char *clientId_str, int32_t clientId_len,
00161                                             const char *username_str, int32_t username_len,
00162                                             const char *password_str, int32_t password_len,
00163                                             void **usr);
00164 
00165                                       
00166                 /** Callback routine to receive a PUBLISH from a client.
00167                     The server app must provide this routine for the instances where it 
00168                     receives PUBLISH messages from clients. The callback is
00169                     invoked in the context of the internal SL MQTT server Receive Task.
00170                     
00171                     \param[in] topstr name of topic on which PUBLISH is received by the server. Not NULL terminated.
00172                     \param[in] toplen length of the topic name 
00173                     \param[in] payload refers to payload published by the server.
00174                     \param[in] pay_len length of the payload.
00175                     \param[in] dup assert to indicate that it is a duplicate message sent by the client
00176                     \param[in] qoS quality of service of the received published message.
00177                     \param[in] retain asserted to indicate that a retained message has been received
00178                     \return none.
00179                 */
00180                 void (*sl_ExtLib_MqttRecv)(const char *topstr,   int32_t toplen,
00181                                             const void *payload, int32_t pay_len,
00182                                             bool dup, uint8_t qos,
00183                                             bool retain);
00184 
00185                 // Note: Double check whether retain, dup, qos would be required for a server app (with no topic management)
00186 
00187                 /** DISCONNECT: Callback routine to indicate to the Server Application
00188                     that a client has disconnected.
00189                 
00190                     \param[in] usr app's handle to this connection.
00191                     \param[in] due2err set to 1, if connection has been closed, without server
00192                     receiving a DISCONNECT messsage.
00193                     \return none.
00194                 */
00195                 void (*sl_ExtLib_MqttDisconn)(void *usr, bool due2err);
00196 
00197                 
00198                 /** Indication of event either from the server library or implementation generated.
00199                     TBD - Reserved for future use.
00200                     
00201                     \param[in] usr app's handle to this connection.
00202                     \param[in] evt identifier to the reported event. Refer to @ref sl_mqtt_srvr_evt - TBD
00203                     \param[in] buf points to buffer
00204                     \param[in] len length of buffer   
00205                     \return none.             
00206                 */
00207                 void (*sl_ExtLib_MqttEvent)(void *usr, int32_t evt, const void *buf, uint32_t len);
00208                 
00209         } SlMqttServerCbs_t;
00210 
00211         /** Secure Socket Parameters to open a secure connection */
00212         typedef struct {
00213 
00214                 #define SL_MQTT_SRVR_NETCONN_IP6  0x01  /**< Assert for IPv6 connection, otherwise  IPv4 */
00215                 #define SL_MQTT_SRVR_NETCONN_URL  0x02  /**< Server address is an URL and not IP address */
00216                 #define SL_MQTT_SRVR_NETCONN_SEC  0x04  /**< Connection to server  must  be secure (TLS) */
00217 
00218                 uint32_t         netconn_flags; /**< Enumerate connection type  */
00219                 const char          *server_addr;   /**< Server Address: URL or IP  */
00220                 uint8_t       port_number;   /**< Port number of MQTT server */
00221                 uint8_t        method;        /**< Method to tcp secured socket */
00222                 uint32_t         cipher;        /**< Cipher to tcp secured socket */
00223                 uint32_t         n_files;       /**< Number of files for secure transfer */
00224                 char * const        *secure_files; /*SL needs 4 files*/
00225                 
00226         } SlMqttServerParams_t;
00227         
00228 
00229         /** MQTT Server Lib structure which holds Initialization Data */
00230         typedef struct
00231         {
00232                 SlMqttServerParams_t  server_info;      /**< Server information */
00233                 uint8_t  loopback_port;    /**< Loopback port to manage lib internal functioning - Mandatory */
00234                 uint32_t   rx_tsk_priority;  /**< Priority of the receive task in server */
00235                 uint32_t    resp_time;        /**< Reasonable response wait time (seconds) for server */                
00236                 bool aux_debug_en;  /**< Assert to indicate additional debug info */
00237                 int32_t (*dbg_print)(const char *pcFormat, ...); /**< Print debug information */
00238         } SlMqttServerCfg_t;
00239     
00240         /** Initialize the SL MQTT Server Implementation.
00241             A caller must initialize the MQTT Server implementation prior to using its services.
00242             
00243             \param[in] cfg refers to configuration parameters
00244             \param[in] cbs callbacks into server application 
00245             \return Success (0) or Failure (-1)
00246         */
00247         int32_t sl_ExtLib_MqttServerInit(const SlMqttServerCfg_t *cfg,
00248                                        const SlMqttServerCbs_t *cbs);
00249 
00250         /** Enroll a topic to receive data
00251             App can enroll a topic of interest and the SL layer will forward to the app any
00252             data subsequently published for the enrolled topic to the server by any of the
00253             connected MQTT clients.
00254  
00255             This is analogous or similar to a subsription to a topic by an MQTT client.
00256             
00257             \param[in] topic  enrollment topic for data to be received. It is NULL terminated.
00258             \return Success(0) or Failure (-1).
00259         */
00260         int32_t sl_ExtLib_MqttTopicEnroll(const char *topic);
00261 
00262         static inline int32_t sl_ExtLib_MqttTopicSub(const char *topic)
00263         {
00264                 return sl_ExtLib_MqttTopicEnroll(topic);
00265         }
00266         
00267         /** DisEnroll a topic.
00268             App can cancel the previous enrollment of a topic and the SL layer will now stop
00269             forwarding data published for that topic to the server by the connected clients. 
00270             This is analogous oe similar to an unsubsription by an MQTT client.
00271             
00272             \param[in] topic  disenrollment topic. It is NULL terminated.
00273             \return Success(0) or Failure(-1).
00274         */
00275         int32_t sl_ExtLib_MqttTopicDisenroll(const char *topic);
00276 
00277         static inline int32_t sl_ExtLib_MqttTopicUnsub(const char *topic)
00278         {
00279                 return sl_ExtLib_MqttTopicDisenroll(topic);
00280         }
00281 
00282         /** PUBLISH a named message to a client.
00283             In addition to the PUBLISH specific parameters, the caller can indicate
00284             whether the routine should block until the time, the message has been
00285             acknowleged by the client. This is applicable only for non-QoS0 messages.
00286 
00287             In case, the app has chosen not to await for the ACK from the client, 
00288             the SL MQTT Server implementation will notify the app about the received ACK
00289             through the callback routine.
00290 
00291             \note Only QoS0 and QoS1 messages are supported.
00292 
00293             \param[in] topic  topic of the data to be published. It is NULL terminated.
00294             \param[in] data   binary data to be published
00295             \param[in] len    length of the data
00296             \param[in] qos    QoS for the publish message
00297             \param[in] retain Retain bit in the PUBLISH message sent out
00298             \param[in] flags  Reserved for future use.
00299             \return Success(0) or Failure(-1).
00300         */
00301         int32_t sl_ExtLib_MqttServerSend(const char *topic, const void *data, int32_t len,
00302                                        uint8_t qos, bool retain, uint32_t flags);
00303 
00304         /** @} */ /* End SL MQTT Server API */
00305         
00306 }//namespace mbed_mqtt         
00307 
00308 #ifdef __cplusplus  
00309 }
00310 #endif  
00311 
00312 
00313 
00314 #endif // __SL_MQTT_SRVR_H__
00315 
00316 
00317