Desciprtion of the library

File content as of revision 3:d6224049b3bf:

/* HTTPServer.cpp */
/*
Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/
#ifndef __HTTPSERVER_H__
#define __HTTPSERVER_H__
#include "mbed.h"
#include "HTTPConnection.h"
#include "HTTPRequestHandler.h"

#include <map>
using std::map;
#include <string>
using std::string;

#include <TCPSocketConnection.h>
#include <TCPSocketServer.h>

/** Typedefinition for a handler function
*/
typedef void (*HTTPRequestHandlerFunction)(HTTPConnection::HTTPMessage&, TCPSocketConnection&);


/** Class HTTPServer for use with <a href="http://mbed.org/users/samux/code/WiflyInterface/">WiflyInterface</a>.
* This class is a simple implementation of an HTTP Server for use with the WiFly interface.
* The class will listen for incoming connections on the (configurable) HTTP port. For each 
* incoming connection, one request will be processed. 
* After instantiating this class, add all required handlers using the \c addHandler function,
* replace the default error handler using \c addErrorHandler if needed and call the \c start
* method to initialize the class.
* You need to continuously poll for any new incoming connections after one request has been
* served using the \c poll member function.
*
* \b Example:
* @code
* #include "mbed.h"
* #include "HTTPServer.h"
* #include "LocalFileSystem.h"
*
* LocalFileSystem local("local"); 
* WiflyInterface wifly(p9, p10, p25, p26, "<your access point>", "<your password>", WPA);
*
* void main(void)
* {
*     HTTPServer svr;
      svr.mount("/local/", "/");
*     svr.addHandler<HTTPFsRequestHandler>( "/" );
*     svr.start();
*     while(1)
*     {
*         if (svr.poll() < 0)
*             exit(0);
*     }
* }
* @endcode
*/
class HTTPServer
{
    public:
        /** Constructor for HTTPServer objects.
        */
        HTTPServer(Serial* dbg = NULL);
        
        /** Destructor for HTTPServer objects.
        */
        ~HTTPServer();

        struct handlersComp //Used to order handlers in the right way
        {
            bool operator() (const string& handler1, const string& handler2) const
            {
                //The first handler is longer than the second one
                if (handler1.length() > handler2.length())
                    return true; //Returns true if handler1 is to appear before handler2
                else if (handler1.length() < handler2.length())
                    return false;
                else //To avoid the == case, sort now by address
                    return ((&handler1)>(&handler2));
            }
        };

        ///Adds a handler
        /**
        Appends a handler to the handlers list
        @param T : class which will be instanciated to serve these requests
        @param path : requests starting with this path will be served using this handler
        */
        template<typename T>
        void addHandler(const char* path)
        { m_lpHandlers[path] = &T::create; }
    
        /**
        Replaces the standard error Handler. The error Handler will be called everytime a request is not
        handled by a handler from the handler list.
        @param hdlFunc: Handler which serves an error condition.
        */
        void addErrorHandler(HTTPRequestHandlerFunction hdlFunc)
        { m_pErrorHandler = hdlFunc!=NULL ?hdlFunc : StdErrorHandler; }    

        /** Binds server to a specific port and starts listening. This member prepares the internal variables and the server socket
        * and terminates after successfull initialization
        * @param port : port on which to listen for incoming connections
        * @returns : -1 if an unrecoverable error occured, or 0 if everything was ok.
        */
        int start(int port = 80);
        
        /** Performs the regular polling of the server component. Needs to be called cyclically.
        * The function will internally check whether new connections are requested by a client and will also poll all existing client connections.
        */
        int poll();
  
    private:        
        static void StdErrorHandler(HTTPConnection::HTTPMessage&, TCPSocketConnection&);
        
        TCPSocketServer* m_pSvr;
        bool    m_bServerListening;
            
        Serial* m_pDbg;
        void HandleRequest(HTTPConnection::HTTPMessage& con, TCPSocketConnection&);
    
        map<string, HTTPRequestHandler* (*)(const char*, const char*, HTTPConnection::HTTPMessage&, TCPSocketConnection&), handlersComp>   m_lpHandlers;
        HTTPRequestHandlerFunction m_pErrorHandler;
        
 };
 
 #endif //__HTTPSERVER_H__