Initial version of C http thorn. There are still a fair number of things on

my to-do list, but it is fairly usable now as far as functionality is
concerned.

Tom



git-svn-id: http://svn.cactuscode.org/arrangements/CactusConnect/HTTPD/trunk@2 1faa4e14-9dd3-4be0-9f0e-ffe519881164

1 files changed, 138 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..a267fad
--- /dev/null
+++ b/README
@@ -0,0 +1,138 @@
+Cactus Code Thorn httpd
+Authors    : Tom Goodale
+CVS info   : $Header$
+--------------------------------------------------------------------------
+
+Purpose of the thorn:
+-------------------
+This is a prototype C version of a web server thorn.
+
+Usage:
+-------------------
+
+Interface:
+---------
+
+The current interface for this webserver is contained in
+
+http_Request.h
+
+(Note that this will change once we have an agreed common protocol for
+other thorns to talk to web-serving thorns.)
+
+The primary mechanism is to
+
+HTTP_RegisterPage(path, function, data)
+
+where 'path' is the URI you want to register, e.g.
+
+/parameters
+
+'function' is a function of the form
+
+int foo(cGH *cctkGH, httpRequest *request, void *data)
+
+which will be called when the page is accessed, with 'data' being the
+same data pointer that was passed into the registration routine.
+
+Note that a request of the form '/foo/bar/' will look for a page of
+the called '/foo/var/index.html' first, followed by '/foo/bar',
+followed by '/foo' followed by '/'.
+
+The httpRequest structure contains various pieces of information -
+
+request->filedes            The file descriptor of the socket to write
+                            to.
+
+request->body               The body of the http request.  This is
+                            empty for a GET.
+
+request->body_length        The length of the body.
+
+request->method             The http method.
+request->uri                The full URI of the request.
+request->residual           The URI remaining after the registered URI 
+                            is removed from it.
+
+request->http_major_version The major version of the HTTP protocol
+                            used.
+
+request->http_minor_version The minor version of the HTTP protocol
+                            used.
+
+request->n_arguments        The number of arguments passed to the
+                            request.
+
+All other members of the structure should be considered opaque.
+
+
+To get details of arguments or HTTP header lines, the functions
+
+const char *HTTP_ArgumentValue(const httpRequest *request, 
+                               const char *arg);
+
+const char *HTTP_HeaderValue(const httpRequest *request, 
+                             const char *header);
+
+may be used.  Given the name of a header field or an argument, these
+functions will return the corresponding value, or NULL if the argument 
+or header does not exist.
+
+
+Writing to the browser:
+----------------------
+
+Currently this is done via the 'write' command.  This takes three
+arguments - the file-descripter, a buffer, and the length of the
+buffer.
+
+The first line sent to the browser should be
+
+write(request->filedes, "HTTP/1.0 200 OK\r\n",19)
+
+(or an error code, e.g. "404 Not Found").  This should be followed by
+any HTTP headers, such as "Content-Type", followed by "\r\n\r\n" and
+then the content of your page, or at least that's what the standard
+says 8-).
+
+
+Examples:
+---------
+
+For examples of how to use the interface, please look at the Content.c 
+file.
+
+Structure of the thorn:
+----------------------
+
+The thorn is split into two parts - web serving and content provision.
+
+Web serving:
+-----------
+The web server capabilities are held in
+
+Sockets.c           - basic socket utilities;  these should be
+                      replaced by or moved to the Socket thorn.
+
+Server.c            - Stuff to register and serve pages.
+
+http.c              - Parsing of HTTP requests.
+
+Startup.c           - normal scheduled stuff.
+
+The above files should not need to be touched apart from debugging
+purposes, to add more HTTP methods, or otherwise to enhance the
+interaction with the network and protocols.
+
+Content Provision:
+-----------------
+
+The content provision is currently all in 
+
+Content.c
+
+This makes use of the interfaces in http_Request.h described above to
+provide content.  In principle this could be in another thorn, but
+that should wait until we have an agreed set of interfaces to allow
+web-server thorns to be interchangeable, at least at compile time, but 
+hopefully at run-time.