Diff: SW_HTTPServer.h

Revision:

37:0cb2774e2410

Parent:

36:1bb5fa6b109c

Child:

38:c8fa31e6fe02

--- a/SW_HTTPServer.h	Fri May 02 00:26:06 2014 +0000
+++ b/SW_HTTPServer.h	Sun May 11 21:16:42 2014 +0000
@@ -202,7 +202,9 @@
     /**
     * This is the prototype for custom handlers that are activated via a callback
     *
-    * This callback gets overloaded for a few purposes, which can be identified by the \see CallBackType parameter
+    * This callback gets overloaded for a few purposes, which can be identified by the 
+    * \see CallBackType parameter.
+    *
     * @li CONTENT_LENGTH_REQUEST - the server is asking the callback if it wants to receive the message,
     *       which may require significant memory. If the request is accepted, true should be returned.
     *       If the request is denied, false should be returned.
@@ -220,14 +222,17 @@
     *
     * @param svr is a handle to this class, so the callback has access to member functions
     * @param type is the callback type @see CallBackType
-    * @param path is the pointer to a large block of information being transferred
+    * @param path is the pointer to a large block of information being transferred. This pointer
+    *        references a dynamically managed resource, so any information of value must be 
+    *        extracted from here, and not referenced into this memory space.
     * @param queryParams is a pointer based on the callback type.
     * @param count is the number of items - for type = CONTENT_LENGTH_REQUEST this is the number of 
     *        name=value pars in the queryParams parameter, and for the DATA_TRANSFER this is the 
     *        number of bytes being passed in the path parameters.
     * @return one of the @see CallBackResults signals indicating error or successes
     */
-    typedef CallBackResults (* Handler)(HTTPServer * svr, CallBackType type, const char *path, const namevalue *queryParams, int queryParamCount);
+    typedef CallBackResults (* Handler)(HTTPServer * svr, CallBackType type, const char *path, 
+        const namevalue *queryParams, int queryParamCount);
 
     /**
     * Create the HTTPServer object.
@@ -236,16 +241,19 @@
     * @param port is the optional parameter for the port number to use, default is 80.
     * @param webroot is a file system path to the root folder for the web space. If any trailing '/'
     *        is included (e.g. "/web/path/") it will be removed (to "/web/path").
-    * @param maxheaderParams defines the maximum number of parameters to extract from a header (Host: 192..\r\nConnection: keep-alive\r\n...)
-    * @param maxqueryParams defines the maximum number of query parameters to a dynamic function (and the memory to support them).
+    * @param maxheaderParams defines the maximum number of parameters to extract from a header 
+    *        (Host: 192..\r\nConnection: keep-alive\r\n...)
+    * @param maxqueryParams defines the maximum number of query parameters to a dynamic function 
+    *        (and the memory to support them).
     * @param maxdynamicpages defines the maximum number of dynamic pages that can be registered.
     * @param pc is the serial port for debug information (I should transform this to a log interface)
     * @param allocforheader is the memory allocation to support the largest expected header from a client
-    * @param allocforfile is the memory allocation to support sending a file to the client. This is typically sized to fit
-    *        an ethernet frame.
+    * @param allocforfile is the memory allocation to support sending a file to the client. This is 
+    *        typically sized to fit an ethernet frame.
     */
-    HTTPServer(Wifly * wifly, int port = 80, const char * webroot = "/", int maxheaderParams = 15, int maxqueryParams = 30, int maxdynamicpages = 10,
-               PC * pc = NULL, int _allocforheader = MAX_HEADER_SIZE, int _allocforfile = FILESEND_BUF_SIZE);
+    HTTPServer(Wifly * wifly, int port = 80, const char * webroot = "/", int maxheaderParams = 15, 
+        int maxqueryParams = 30, int maxdynamicpages = 10,
+        PC * pc = NULL, int _allocforheader = MAX_HEADER_SIZE, int _allocforfile = FILESEND_BUF_SIZE);
 
     /**
     * Destructor, which can clean up memory.
@@ -287,7 +295,8 @@
     * @param optional_text is a pointer to any other text that is part of the header, which must
     *        have \r\n termination.
     */
-    void header(int code = 404, const char * code_text = "Not Found", const char * content_type = NULL, const char * optional_text = NULL);
+    void header(int code = 404, const char * code_text = "Not Found", const char * content_type = NULL, 
+        const char * optional_text = NULL);
 
     /**
     * Send text to the client
@@ -326,7 +335,8 @@
     *   svr.RegisterHandler("/dyn1", SimpleDynamicPage);svr.RegisterHandler("/dyn1", SimpleDynamicPage);
     *   ...
     *
-    *   bool SimpleDynamicPage(HTTPServer *svr, HTTPServer::CallBackType type, const char * path, const HTTPServer::namevalue *queryParams, int queryParamCount) {
+    *   bool SimpleDynamicPage(HTTPServer *svr, HTTPServer::CallBackType type, const char * path, 
+    *       const HTTPServer::namevalue *queryParams, int queryParamCount) {
     *       char buf[100];
     *       bool ret = false;
     *
@@ -414,8 +424,10 @@
     * #fragment_id on the end of the string, it will be removed.
     *
     * @param pString is a pointer to the string.
+    * @returns The total number of items that have been parsed, 
+    *       which can include a count from a url query string.
     */
-    void ParseParameters(char * pString);
+    int ParseParameters(char * pString);
 
     /**
     * Unescape string converts a coded string "in place" into a normal string.