Diff: HTTPServer.h

Revision:

4:d065642c32cc

Parent:

3:d6224049b3bf

Child:

6:fe661fa9d18a

--- a/HTTPServer.h	Tue May 28 01:56:14 2013 +0000
+++ b/HTTPServer.h	Tue May 28 21:20:58 2013 +0000
@@ -74,6 +74,11 @@
 */
 class HTTPServer
 {
+        
+        TCPSocketServer*        m_pSvr;
+        bool                    m_bServerListening;
+        Serial*                 m_pDbg;
+
     public:
         /** Constructor for HTTPServer objects.
         */
@@ -83,6 +88,9 @@
         */
         ~HTTPServer();
 
+        /**
+        * Structure which will allow to order the stored handlers according to their associated path.
+        */
         struct handlersComp //Used to order handlers in the right way
         {
             bool operator() (const string& handler1, const string& handler2) const
@@ -97,20 +105,21 @@
             }
         };
 
-        ///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
+        * Adds a request handler to the handlers list. You will have to use one of the existing implementations.
+        * With each handler a \c uri or \c path is associated. Whenever a request is received the server will
+        * walk through all registered handlers and check which \c path is matching.
+        * @param T : class which will be instanciated to serve these requests for the associated \b path.
+        * @param path : request uri starting with this \c 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.
+        * Replaces the standard error Handler. The error Handler will be called everytime a request is not
+        * matching any of the registered \c paths or \c uris.
+        * @param hdlFunc: User specified handler function which will be used in error conditions.
         */
         void addErrorHandler(HTTPRequestHandlerFunction hdlFunc)
         { m_pErrorHandler = hdlFunc!=NULL ?hdlFunc : StdErrorHandler; }    
@@ -124,18 +133,30 @@
         
         /** 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.
+        * @returns -1 if there was a problem. If 0 is returned, the latest request was served successfully and the server is
+        * ready for processing the next request. Simply call \c poll as long as you want to serve new incoming requests.
         */
         int poll();
   
-    private:        
-        static void StdErrorHandler(HTTPConnection::HTTPMessage&, TCPSocketConnection&);
+    private:
+        /** The standard error handler function.
+        * @param msg : Request message data.
+        * @param tcp : Socket to be used for responding.
+        */
+        static void StdErrorHandler(HTTPConnection::HTTPMessage& msg, TCPSocketConnection& tcp);
         
-        TCPSocketServer* m_pSvr;
-        bool    m_bServerListening;
-            
-        Serial* m_pDbg;
-        void HandleRequest(HTTPConnection::HTTPMessage& con, TCPSocketConnection&);
+        /** Internal function which processes a request and which will try to find the matching handler function
+        * for the given request. Please note that the function will search through the list of handlers, iterating
+        * from longest to shortest \c paths. If the registered \c path is a subset of the request the associated
+        * handler is considered as being a match.
+        * @param msg : Request message data. Contains the requested logical \c uri. 
+        * @param tcp : Socket to be used for communication with the client.
+        */
+        void HandleRequest(HTTPConnection::HTTPMessage& msg, TCPSocketConnection& tcp);
     
+        /** Map of handler objects. Can be any object derived from \ref HTTPRequestHeader. Use the \ref addHandler function
+        * to register new handler objects.
+        */
         map<string, HTTPRequestHandler* (*)(const char*, const char*, HTTPConnection::HTTPMessage&, TCPSocketConnection&), handlersComp>   m_lpHandlers;
         HTTPRequestHandlerFunction m_pErrorHandler;