HTTPServer.h

00001 /* HTTPServer.cpp */
00002 /*
00003 Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
00004  
00005 Permission is hereby granted, free of charge, to any person obtaining a copy
00006 of this software and associated documentation files (the "Software"), to deal
00007 in the Software without restriction, including without limitation the rights
00008 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00009 copies of the Software, and to permit persons to whom the Software is
00010 furnished to do so, subject to the following conditions:
00011  
00012 The above copyright notice and this permission notice shall be included in
00013 all copies or substantial portions of the Software.
00014  
00015 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00016 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00017 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00018 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00019 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00020 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00021 THE SOFTWARE.
00022 */
00023 #ifndef __HTTPSERVER_H__
00024 #define __HTTPSERVER_H__
00025 #include "mbed.h"
00026 #include "EthernetInterface.h"
00027 #include "HTTPConnection.h"
00028 #include "HTTPRequestHandler.h"
00029 
00030 #include <map>
00031 using std::map;
00032 #include <string>
00033 using std::string;
00034 
00035 #include <TCPSocketConnection.h>
00036 #include <TCPSocketServer.h>
00037 
00038 /** Typedefinition for a handler function
00039 */
00040 typedef void (*HTTPRequestHandlerFunction)(HTTPConnection::HTTPMessage&, TCPSocketConnection&);
00041 
00042 
00043 /** Class HTTPServer for use with <a href="http://mbed.org/users/samux/code/WiflyInterface/">WiflyInterface</a>.
00044 * This class is a simple implementation of an HTTP Server for use with the WiFly interface.
00045 * The class will listen for incoming connections on the (configurable) HTTP port. For each 
00046 * incoming connection, one request will be processed. 
00047 * After instantiating this class, add all required handlers using the \c addHandler function,
00048 * replace the default error handler using \c addErrorHandler if needed and call the \c start
00049 * method to initialize the class.
00050 * You need to continuously poll for any new incoming connections after one request has been
00051 * served using the \c poll member function.
00052 *
00053 * \b Example:
00054 * @code
00055 * #include "mbed.h"
00056 * #include "HTTPServer.h"
00057 * #include "LocalFileSystem.h"
00058 *
00059 * LocalFileSystem local("local"); 
00060 *
00061 * void main(void)
00062 * {
00063 *     HTTPServer svr;
00064 *     svr.mount("/local/", "/");
00065 *     svr.addHandler<HTTPFsRequestHandler>( "/" );
00066 *     svr.start();
00067 *     while(1)
00068 *     {
00069 *         if (svr.poll() < 0)
00070 *             exit(0);
00071 *     }
00072 * }
00073 * @endcode
00074 *
00075 * An alternate approach e.g. if you need to perform additional tasks using the EthernetInterface
00076 * there is the possibility to provide the EthernetInterface object in an initialized and connected
00077 * state. __NOTE: You should choose this scenario for compatibility reasons.___
00078 *
00079 * \b Example2:
00080 * @code
00081 * #include "mbed.h"
00082 * #include "HTTPServer.h"
00083 * #include "EthernetInterface.h"
00084 * #include "LocalFileSystem.h"
00085 *
00086 * LocalFileSystem local("local");
00087 * EthernetInterface eth;
00088 *
00089 * void main(void)
00090 * {
00091 *     HTTPServer svr;
00092 *     //    Initialize the ethernet interface
00093 *     if (eth.init() != 0) {
00094 *         printf("Initialization of EthernetInterface failed !");
00095 *         exit(0);
00096 *     }
00097 *     //    Connect using DHCP
00098 *     if (eth.connect() !=0) {
00099 *         printf("Failed to connect using DHCP !");
00100 *         exit(0);
00101 *     }
00102 *     
00103 *     // Moint the local file system and provide a handler for 'root'.
00104 *     svr.mount("/local/", "/");
00105 *     svr.addHandler<HTTPFsRequestHandler>( "/" );
00106 *     // Start the server on port 80, providing our own ethernet interface object.
00107 *     svr.start(80, &eth);
00108 *     while(1)
00109 *     {
00110 *         if (svr.poll() < 0)
00111 *             exit(0);
00112 *     }
00113 * }
00114 * @endcode
00115 *     
00116 */
00117 class HTTPServer
00118 {
00119         TCPSocketServer         m_Svr;
00120         bool                    m_bServerListening;
00121         EthernetInterface*      m_pEthernet;
00122        
00123     public:
00124         /** Constructor for HTTPServer objects.
00125         */
00126         HTTPServer();
00127         
00128         /** Destructor for HTTPServer objects.
00129         */
00130         ~HTTPServer();
00131 
00132         /**
00133         * Structure which will allow to order the stored handlers according to their associated path.
00134         */
00135         struct handlersComp //Used to order handlers in the right way
00136         {
00137             bool operator() (const string& handler1, const string& handler2) const
00138             {
00139                 //The first handler is longer than the second one
00140                 if (handler1.length() > handler2.length())
00141                     return true; //Returns true if handler1 is to appear before handler2
00142                 else if (handler1.length() < handler2.length())
00143                     return false;
00144                 else //To avoid the == case, sort now by address
00145                     return ((&handler1)>(&handler2));
00146             }
00147         };
00148 
00149         /**
00150         * Adds a request handler to the handlers list. You will have to use one of the existing implementations.
00151         * With each handler a \c uri or \c path is associated. Whenever a request is received the server will
00152         * walk through all registered handlers and check which \c path is matching.
00153         * @param T : class which will be instanciated to serve these requests for the associated \b path.
00154         * @param path : request uri starting with this \c path will be served using this handler.
00155         */
00156         template<typename T>
00157         void addHandler(const char* path)
00158         { m_lpHandlers[path] = &T::create; }
00159     
00160         /**
00161         * Replaces the standard error Handler. The error Handler will be called everytime a request is not
00162         * matching any of the registered \c paths or \c uris.
00163         * @param hdlFunc: User specified handler function which will be used in error conditions.
00164         */
00165         void addErrorHandler(HTTPRequestHandlerFunction hdlFunc)
00166         { m_pErrorHandler = hdlFunc!=NULL ?hdlFunc : StdErrorHandler; }    
00167 
00168         /** Binds server to a specific port and starts listening. This member prepares the internal variables and the server socket
00169         * and terminates after successfull initialization
00170         * @param port : port on which to listen for incoming connections
00171         * @param pEthernet : a pointer to an existing EthernetInterface object or NULL if the HTTPServer shall allocate the object. _Please note that for compatibility reasons
00172         * your should consider to create the EthernetInterface as a static variable. Otherwise the the object will be created on the heap._
00173         * @returns : false if an unrecoverable error occured or if the ethernet interface was not set or not initialized correctly, or true if everything was ok.
00174         */
00175         bool start(int port = 80, EthernetInterface* pEthernet = NULL);
00176         
00177         /** Performs the regular polling of the server component. Needs to be called cyclically.
00178         * The function will internally check whether new connections are requested by a client and will also poll all existing client connections.
00179         * @param blocking : if true, 
00180         * @returns -1 if there was a problem. If 0 is returned, the latest request was served successfully and the server is
00181         * ready for processing the next request. Simply call \c poll as long as you want to serve new incoming requests.
00182         */
00183         int poll(bool blocking = true);
00184         
00185     private:
00186         
00187         /** The standard error handler function.
00188         * @param msg : Request message data.
00189         * @param tcp : Socket to be used for responding.
00190         */
00191         static void StdErrorHandler(HTTPConnection::HTTPMessage& msg, TCPSocketConnection& tcp);
00192         
00193         /** Internal function which processes a request and which will try to find the matching handler function
00194         * for the given request. Please note that the function will search through the list of handlers, iterating
00195         * from longest to shortest \c paths. If the registered \c path is a subset of the request the associated
00196         * handler is considered as being a match.
00197         * @param msg : Request message data. Contains the requested logical \c uri. 
00198         * @param tcp : Socket to be used for communication with the client.
00199         */
00200         void HandleRequest(HTTPConnection::HTTPMessage& msg, TCPSocketConnection& tcp);
00201     
00202         /** Map of handler objects. Can be any object derived from \ref HTTPRequestHeader. Use the \ref addHandler function
00203         * to register new handler objects.
00204         */
00205         map<string, HTTPRequestHandler* (*)(const char*, const char*, HTTPConnection::HTTPMessage&, TCPSocketConnection&), handlersComp>   m_lpHandlers;
00206         HTTPRequestHandlerFunction m_pErrorHandler;
00207         
00208  };
00209  
00210  #endif //__HTTPSERVER_H__