7 files changed, 968 insertions, 0 deletions

diff --git a/doc/chapters/basicauthentication.inc b/doc/chapters/basicauthentication.inc
new file mode 100644
index 00000000..8e7f4c60
--- /dev/null
+++ b/doc/chapters/basicauthentication.inc
@@ -0,0 +1,207 @@
+With the small exception of IP address based access control, 
+requests from all connecting clients where served equally until now.
+This chapter discusses a first method of client's authentication and
+its limits. 
+
+A very simple approach feasible with the means already discussed would
+be to expect the password in the @emph{URI} string before granting access to
+the secured areas. The password could be separated from the actual resource identifier
+by a certain character, thus the request line might look like
+@verbatim
+GET /picture.png?mypassword
+@end verbatim
+@noindent
+
+In a situation, where the client is customized enough and the connection occurs
+through secured lines (e.g., a embedded device directly attached to another via wire),
+this can be a reasonable choice.
+
+But when it is assumed that the user connecting does so with an ordinary Internet browser,
+this implementation brings some problems about. For example, the URI including the password
+stays in the address field or at least in the history of the browser for anybody near enough to see. 
+It will also be inconvenient to add the password manually to any new URI when the browser does
+not know how to compose this automatically.
+
+At least the convenience issue can be addressed by employing the simplest built-in password
+facilities of HTTP compliant browsers, hence we want to start there. It will however turn out
+to have still severe weaknesses in terms of security which need consideration.
+
+Before we will start implementing @emph{Basic Authentication} as described in @emph{RFC 2617},
+we should finally abandon the bad practice of responding every request the first time our callback
+is called for a given connection. This is becoming more important now because the client and 
+the server will have to talk in a more bi-directional way than before to 
+
+But how can we tell whether the callback has been called before for the particular connection?
+Initially, the pointer this parameter references is set by @emph{MHD} in the callback. But it will 
+also be "remembered" on the next call (for the same connection).
+Thus, we will generate no response until the parameter is non-null---implying the callback was
+called before at least once. We do not need to share information between different calls of the callback,
+so we can set the parameter to any adress that is assured to be not null. The pointer to the 
+@code{connection} structure will be pointing to a legal adress, so we take this.
+
+Not even the headers will be looked at on the first iteration.
+
+@verbatim
+int answer_to_connection (void *cls, struct MHD_Connection *connection,
+                          const char *url, const char *method, const char *version, 
+                          const char *upload_data, unsigned int *upload_data_size,
+                          void **con_cls)
+{
+  if (0 != strcmp(method, "GET")) return MHD_NO;
+  if (NULL == *con_cls) {*con_cls = connection; return MHD_YES;}
+
+  ... 
+  /* else respond accordingly */
+  ...
+}
+@end verbatim
+@noindent
+
+Note how we lop off the connection on the first condition, but return asking for more on 
+the other one with @code{MHD_YES}.
+With the framework improved, we can proceed to implement the actual authentication process.
+
+@heading Request for authentication 
+
+Let us assume we had only files not intended to be handed out without the correct username/password,
+so every "GET" request will be challenged.
+@emph{RFC 2617} describes how the server shall ask for authentication by adding a
+@emph{WWW-Authenticate} response header with the name of the @emph{realm} protected.
+
+We let an extra function function do this.
+@verbatim
+int ask_for_authentication (struct MHD_Connection *connection, const char *realm)
+{
+  int ret;
+  struct MHD_Response *response;
+  char *headervalue;
+  const char *strbase = "Basic realm=";
+  
+  response = MHD_create_response_from_data (0, NULL, MHD_NO, MHD_NO);
+  if (!response) return MHD_NO;
+  
+  headervalue = malloc (strlen (strbase) + strlen (realm) + 1);
+  if (!headervalue) return MHD_NO;  
+
+  strcpy (headervalue, strbase);
+  strcat (headervalue, realm);
+  
+  ret = MHD_add_response_header (response, "WWW-Authenticate", headervalue);
+  free (headervalue);  
+  if (!ret) {MHD_destroy_response (response); return MHD_NO;}
+
+  ret = MHD_queue_response (connection, MHD_HTTP_UNAUTHORIZED, response);
+  
+  MHD_destroy_response (response);
+
+  return ret;
+}
+@end verbatim
+@noindent
+
+@code{#define} the realm name according to your own taste, e.g. "Maintenance" or "Area51" but
+it will need to have extra quotes.
+
+But the client may send the authentication right away, so it would be wrong to ask for
+it without checking the request's header--where the authentication is expected to be found.
+
+@heading Authentication in detail
+Checking @emph{RFC 2617} again, we find that the client will pack the username and password, by
+whatever means he might have obtained them, in a line separated by a colon---and then encodes
+them to @emph{Base64}. The actual implementation of this encoding are not within the scope of
+this tutorial although a working function is included in the complete source file of the example.
+
+An unencoded word describing the authentication method (here "Basic") will precede the code
+and the resulting line is the value of a request header of the type "Authorization".  
+
+This header line thus is of interest to the function checking a connection for a given username/password:
+@verbatim
+int is_authenticated (struct MHD_Connection *connection,
+                      const char *username, const char *password)
+{
+  const char *headervalue;
+  ...
+
+  headervalue = MHD_lookup_connection_value (connection, MHD_HEADER_KIND,
+                                             "Authorization");
+  if (NULL == headervalue) return 0;
+@end verbatim
+@noindent
+
+where, firstly, the authentication method will be checked.
+@verbatim
+const char *strbase = "Basic ";
+...
+if (0 != strncmp (headervalue, strbase, strlen (strbase))) return 0;
+@end verbatim
+@noindent
+
+Of course, we could decode the passed credentials in the next step and compare them directly to
+the given strings. But as this would involve string parsing, which is more complicated then string
+composing, it is done the other way around---the clear text credentials will be encoded to @emph{Base64}
+and then compared against the headerline. The authentication method string will be left out here as
+it has been checked already at this point.
+@verbatim
+  char *expected_b64, *expected;
+  int authenticated;
+
+  ...
+  strcpy (expected, username);
+  strcat (expected, ":");
+  strcat (expected, password);  
+
+  expected_b64 = string_to_base64 (expected);
+  if (NULL == expected_b64) return 0;
+ 
+  strcpy (expected, strbase);
+  authenticated = (strcmp (headervalue + strlen (strbase), expected_b64) == 0);
+
+  free (expected_b64);
+
+  return authenticated;
+}
+@end verbatim
+@noindent
+
+These two functions---together with a response function in case of positive authentication doing little 
+new---allow the rest of the callback function to be rather short. 
+@verbatim
+  if (!is_authenticated (connection, USER, PASSWORD)) 
+    return ask_for_authentication (connection, REALM); 
+  
+  return secret_page (connection);
+}
+@end verbatim
+@noindent
+
+See the @code{examples} directory for the complete example file.
+
+@heading Remarks
+For a proper server, the conditional statements leading to a return of @code{MHD_NO} should yield a 
+response with a more precise status code instead of silently closing the connection. For example,
+failures of memory allocation are best reported as @emph{internal server error} and unexpected 
+authentication methods as @emph{400 bad request}.
+
+@heading Exercises
+@itemize @bullet
+@item
+Make the server respond to wrong credentials (but else correct requests) with the recommended
+@emph{401 unauthorized} status code. If the client still does not authenticate correctly within the
+same connection, close it and store the client's IP address for a certain time. (It is OK to check for
+expiration not until the main thread wakes up again on the next connection.) If the client fails
+authenticating three times during this period, add it to another list whose entries the 
+@code{AcceptPolicyCallback} function denies connection (temporally).
+
+@item
+With the network utility @emph{netcat} connect and log the response of a "GET" request as you
+did in the exercise of the first example, this time to a file. Now stop the server and let @emph{netcat}
+listen on the same port the server used to listen on and have it fake being the proper server by giving
+the file's content as the response (e.g. @code{cat log | nc -l -p 8888}). Pretending to think your were
+connecting to the actual server, browse to the eavesdropper and give the correct credentials.
+
+Copy and paste the encoded string you see in netcat's output to some of the Base64 decode tools available online
+and see how both the user's name and password could be completely restored.
+
+@end itemize
+
+
diff --git a/doc/chapters/bibliography.inc b/doc/chapters/bibliography.inc
new file mode 100644
index 00000000..547028f5
--- /dev/null
+++ b/doc/chapters/bibliography.inc
@@ -0,0 +1,30 @@
+@itemize @bullet
+@heading API reference
+@item
+The @emph{GNU libmicrohttpd} manual by Christian Grothoff 2008 
+@uref{http://gnunet.org/libmicrohttpd/microhttpd.html}
+
+@heading Requests for comments 
+All referenced RFCs can be found on the website of @emph{The Internet Engineering Task Force}
+@uref{http://www.ietf.org/}
+
+@item
+@emph{RFC 2616}: Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. Berners-Lee,
+"Hypertext Transfer Protocol -- HTTP/1.1", RFC 2016, January 1997.
+
+@item
+@emph{RFC 2617}: Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P.,
+Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999.
+
+
+@heading Recommended readings
+@item 
+A well--structured @emph{HTML} reference can be found on
+@uref{http://www.echoecho.com/html.htm}
+
+For those readers understanding German or French, there is an excellent document both for learning
+@emph{HTML} and for reference, whose English version unfortunately has been discontinued.
+@uref{http://de.selfhtml.org/} and @uref{http://fr.selfhtml.org/}
+
+
+@end itemize
diff --git a/doc/chapters/exploringrequests.inc b/doc/chapters/exploringrequests.inc
new file mode 100644
index 00000000..11a169dd
--- /dev/null
+++ b/doc/chapters/exploringrequests.inc
@@ -0,0 +1,103 @@
+This chapter will deal with the information which the client sends to the
+server at every request. We are going to examine the most useful fields of such an request
+and print them out in a readable manner. This could be useful for logging facilities.
+
+The starting point is the @emph{hellobrowser} program with the former response removed.
+
+This time, we just want to collect information in the callback function, thus we will
+just return MHD_NO after we have probed the request. This way, the connection is closed
+without much ado by the server.
+
+@verbatim
+int answer_to_connection (void *cls, struct MHD_Connection *connection, const char *url, 
+                         const char *method, const char *version, const char *upload_data, 
+                         unsigned int *upload_data_size, void **con_cls)
+{
+  ...  
+  return MHD_NO;
+}
+@end verbatim
+@noindent
+The ellipsis marks the position where the following instructions shall be inserted.
+
+
+We begin with the most obvious information available to the server, the request line. You should
+already have noted that a request consists of a command (or "method") and a URI (e.g. a filename).
+It also contains a string for the version of the protocol which can be found in @code{version}.
+To call it a "new request" is justified because we return only @code{MHD_NO}, thus ensuring the 
+function will not be called again for this connection. 
+@verbatim
+printf ("New request %s for %s using version %s\n", method, url, version);
+@end verbatim
+@noindent
+
+The rest of the information is a bit more hidden. Nevertheless, there is lot of it sent from common
+Internet browsers. It is stored in "key-name" pairs and we want to list what we find in the header. 
+As there is no mandatory set of keys a client has to send, each key--name pair is printed out one by
+one until there are no more left. We do this by writing a separate function which will be called for
+each pair just like the above function is called for each HTTP request. 
+It can then print out the content of this pair.
+@verbatim
+int print_out_key (void *cls, enum MHD_ValueKind kind, const char *key, const char *value)
+{
+  printf ("%s = %s\n", key, value);
+  return MHD_YES;
+}
+@end verbatim
+@noindent
+
+To start the iteration process that calls our new function for every key, the line
+@verbatim
+MHD_get_connection_values (connection, MHD_HEADER_KIND, print_out_key, NULL);
+@end verbatim
+@noindent
+needs to be inserted in the connection callback function too. The second parameter tells the function 
+that we are only interested in keys from the general HTTP header of the request. Our iterating
+function @code{PrintOutKey} does not rely on any additional information to fulfill its duties
+so the last parameter can be NULL.
+
+All in all, this constitutes the complete @code{logger.c} program for this chapter which can be 
+found in the @code{examples} section.
+
+Connecting with any modern Internet browser should yield a handful of keys. You should try to 
+interpret them with the aid of @emph{RFC 2616}.
+Especially worth mentioning is the host key which is often used to serve several different websites
+hosted under one single IP address but reachable by different domain names.
+
+@heading Conclusion
+The introduced capabilities to itemize the content of a simple GET request---especially the
+URI---should already allow the server to satisfy clients' requests for small specific resources
+(e.g. files) or even induce alteration of how the server operates. However, the latter is not
+recommended as the GET method (including its header data) is by convention considered a "SAFE"
+operation, which should not change the server's state in a significant way, but temporally actions
+like searching for a passed string is fine.
+
+Of course, no transmission can occur while the return value is still set to @code{MHD_NO} in the
+callback function.
+
+@heading Exercises
+@itemize @bullet
+@item
+By parsing the @code{url} string and delivering responses accordingly, implement a small server for
+"virtual" files. When asked for @code{/index.htm@{l@}}, let the response consist of a HTML page
+containing a link to @code{/another.html} page which is also to be created "on the fly" in case of
+being requested. If neither of these two pages are requested, @code{MHD_HTTP_NOT_FOUND} shall be
+returned accompanied by an informative message.
+
+@item
+A very interesting information has still been ignored by our logger---the client's IP address. 
+Implement a callback function 
+@verbatim
+int on_client_connect (void *cls,
+                       const struct sockaddr *addr,socklen_t addrlen)
+@end verbatim
+@noindent
+that prints out the IP address in an appropriate format. You might want to use the posix function
+@code{inet_ntoa} but bear in mind that @code{addr} is actually just a structure containing other
+substructures and is @emph{not} the variable this function expects. 
+Make sure to return @code{MHD_YES} so that the library knows the client is allowed to connect
+(and to request). If one wanted to limit access basing on IP addresses, this would be the place
+to do it. The address of your function will then be passed as the third parameter of the
+@code{MHD_start_daemon} call.
+
+@end itemize
diff --git a/doc/chapters/hellobrowser.inc b/doc/chapters/hellobrowser.inc
new file mode 100644
index 00000000..0513a674
--- /dev/null
+++ b/doc/chapters/hellobrowser.inc
@@ -0,0 +1,203 @@
+The most basic task for a HTTP server is to deliver a static text message to any client connecting to it.
+Given that this is also easy to implement, it is an excellent problem to start with.
+
+For now, the particular filename the client asks for shall have no effect on the message that will 
+be returned. In addition, the server shall end the connection after the message has been sent so that
+the client will know there is nothing more to expect.
+
+The C program @code{hellobrowser.c}, which is to be found in the examples section, does just that.
+If you are very eager, you can compile and start it right away but it is advisable to type the
+lines in by yourself as they will be discussed and explained in detail. 
+
+After the unexciting includes and the definition of the port which our server should listen on
+@verbatim
+#include <microhttpd.h>
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+@end verbatim
+@noindent
+the desired behaviour of our server when HTTP request arrive have to be implemented. We already have
+agreed that it should not care about the particular details of the request, such as who is requesting
+what. The server will respond merely with the same small HTML page to every request. 
+
+The function we are going to write now will be called by @emph{GNU libmicrohttpd} every time an
+appropriate request comes in. While the name of this callback function is arbitrary, its parameter
+list has to follow a certain layout. So please, ignore the lot of parameters for now, they will be
+explained at the point they are needed. We have to use only one of them,
+@code{struct MHD_Connection *connection}, for the minimalistic functionality we want to archive at the moment.
+
+This parameter is set by the @emph{libmicrohttpd} daemon and holds the necessary information to
+relate the call with a certain connection. Keep in mind that a server might have to satisfy hundreds
+of concurrent connections and we have to make sure that the correct data is sent to the destined
+client. Therefore, this variable is a means to refer to a particular connection if we ask the
+daemon to sent the reply.
+
+Talking about the reply, it is defined as a string right after the function header
+@verbatim
+int answer_to_connection (void *cls, struct MHD_Connection *connection, const char *url, 
+                          const char *method, const char *version, const char *upload_data, 
+                          unsigned int *upload_data_size, void **con_cls)
+{
+  const char *page  = "<html><body>Hello, browser!</body></html>";
+@end verbatim
+@noindent
+HTTP is a rather strict protocol and the client would certainly consider it "inappropriate" if we
+just sent the answer string "as is". Instead, it has to be wrapped in certain layers, called headers,
+of additional information. Luckily, most of the work in this area is done by the library for us---we
+just have to ask. Our reply string packed in the necessary layers will be called a "response".
+To obtain such a response we hand our data (the reply--string) and its size over to the 
+@code{MHD_create_response_from_data} function. The last two parameters basically tell @emph{MHD}
+that we do not want it to dispose the message data for us when it has been sent and there also needs
+no internal copy to be done because the @emph{constant} string won't change anyway.
+
+@verbatim
+  struct MHD_Response *response;
+  int ret;
+
+  response = MHD_create_response_from_data (strlen (page),
+                                            (void*) page, MHD_NO, MHD_NO);
+@end verbatim
+@noindent
+Now that the the response has been laced up, it is ready for delivery and can be queued for sending. 
+This is done by passing it to another @emph{GNU libmicrohttpd} function. As all our work was done in
+the scope of one function, the recipient is without doubt the one associated with the
+local variable @code{connection} and consequently this variable is given to the queue function. 
+Every HTTP response is accompanied by a status code, here "OK", so that the client knows 
+this response is the intended result of his request and not due to some error or malfunction.
+
+Finally, the packet is destroyed and the return value from the queue returned,
+already being set at this point to either MHD_YES or MHD_NO in case of success or failure.
+
+@verbatim
+  ret = MHD_queue_response (connection, MHD_HTTP_OK, response);
+  MHD_destroy_response (response);
+
+  return ret;
+}
+@end verbatim
+@noindent
+With the primary task of our server implemented, we can start the actual server daemon which will listen 
+on @code{PORT} for connections. This is done in the main function.
+@verbatim
+int main ()
+{
+  struct MHD_Daemon *daemon;
+
+  daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL, 
+                             &answer_to_connection, NULL, MHD_OPTION_END);
+  if (NULL == daemon) return 1;
+@end verbatim
+@noindent
+The first parameter is one of three possible modes of operation. Here we want the daemon to run in
+a separate thread and to manage all incoming connections in the same thread. This means that while
+producing the response for one connection, the other connections will be put on hold. In this
+chapter, where the reply is already known and therefore the request is served quickly, this poses no problem.
+
+We will allow all clients to connect regardless of their name or location, therefore we do not check
+them on connection and set the forth and fifth parameter to NULL.
+
+Parameter six is the address of the function we want to be called whenever a new connection has been
+established. Our @code{AnswerToConnection} knows best what the client wants and needs no additional
+information (which could be passed via the next parameter) so the next parameter is NULL. Likewise,
+we do not need to pass extra options to the daemon so we just write the MHD_OPTION_END as the last parameter.
+
+As the server daemon runs in the background in its own thread, the execution flow in our main
+function will contine right after the call. Because of this, we must delay the execution flow in the
+main thread or else the program will terminate prematurely. We let it pause in a processing-time
+friendly manner by waiting for the enter key to be pressed. In the end, we stop the daemon so it can
+do its cleanup tasks.
+@verbatim
+  getchar (); 
+
+  MHD_stop_daemon (daemon);
+  return 0;
+}
+
+@end verbatim
+@noindent
+The first example is now complete.
+
+Compile it with 
+@verbatim
+cc hellobrowser.c -o hellobrowser -I$PATH_TO_LIBMHD_INCLUDES 
+  -L$PATH_TO_LIBMHD_INCLUDES -static -lmicrohttpd -pthread
+@end verbatim
+with the two paths set accordingly and run it.
+
+Now open your favorite Internet browser and go to the address @code{localhost:8888}, provided that
+is the port you chose. If everything works as expected, the browser will present the message of the
+static HTML page it got from our minimal server.
+
+@heading Remarks
+To keep this first example as small as possible, some drastic shortcuts were taken and are to be
+discussed now. 
+
+Firstly, there is no distinction made between the kinds of requests a client could send. We implied
+that the client sends a GET request, that means, that he actually asked for some data. Even when
+it is not intended to accept POST requests, a good server should at least recognize that this
+request does not constitute a legal request and answer with an error code. This can be easily
+implemented by checking if the parameter @code{method} equals the string "GET" and returning a
+@code{MHD_NO} if not so.
+
+Secondly, the above practice of queuing a response upon the first call of the callback function
+brings with it some limitations. This is because the content of the message body will not be
+received if a response is queued in the first iteration. Furthermore, the connection will be closed
+right after the response has been transferred then.
+
+Both of these issues you will find addressed in the official @code{minimal_example.c} residing in
+the @code{src/examples} directory of the @emph{GNU libmicrohttpd} package. The source code of this
+program should look very familiar to you by now and easy to understand.
+
+For our example, the @code{must_copy} and @code{must_free} parameter at the response construction
+function could be set to @code{MHD_NO}. In the usual case, responses cannot be sent immediately
+after being queued. For example, there might be other data on the system that needs to be sent with
+a higher priority. Nevertheless, the queue function will return successfully---raising the problem
+that the data we have pointed to may be invalid by the time it is about being sent. This is not an
+issue here because we can expect the @code{page} string, which is a constant @emph{string literal}
+here, to be static. That means it will be present and unchanged for as long as the program runs. 
+For dynamic data, one could choose to either have @emph{MHD} free the memory @code{page} points 
+to itself when it is not longer needed or, alternatively, have the library to make and manage 
+its own copy of it.
+
+@heading Exercises
+@itemize @bullet
+@item
+While the server is running, use a program like telnet or netcat to connect to it. Try to form a
+valid HTTP1.1 request yourself like
+@verbatim
+GET /dontcare HTTP1.1
+Host: itsme
+<enter>
+@end verbatim
+@noindent
+and see what the server returns to you.
+     
+
+@item
+Also, try other requests, like POST, and see how our server does not mind and why.
+How far in malforming a request can you go before the builtin functionality of @emph{MHD} intervenes
+and an altered response is sent? Make sure you read about the status codes in the @emph{RFC}.
+
+
+@item
+Add the option @code{MHD_USE_PEDANTIC_CHECKS} to the start function of the daemon in @code{main}.
+Mind the special format of the parameter list here which is described in the manual. How indulgent
+is the server now to your input?
+
+
+@item
+Let the main function take a string as the first command line argument and pass @code{argv[1]} to
+the @code{MHD_start_daemon} function as the sixth parameter. The address of this string will be
+passed to the callback function via the @code{cls} variable. Decorate the text given at the command
+line when the server is started with proper HTML tags and send it as the response instead of the
+former static string.
+
+
+@item
+@emph{Demanding:} Write a separate function returning a string containing some useful information, 
+for example, the time. Pass the function's address as the sixth parameter and evaluate this function
+on every request anew in @code{AnswerToConnection}. Remember to free the memory of the string
+every time after satisfying the request.
+
+@end itemize
diff --git a/doc/chapters/introduction.inc b/doc/chapters/introduction.inc
new file mode 100644
index 00000000..722d0fb7
--- /dev/null
+++ b/doc/chapters/introduction.inc
@@ -0,0 +1,17 @@
+This tutorial is for developers who want to learn how they can add HTTP serving 
+capabilities to their applications with the @emph{GNU libmicrohttpd} library,
+abbreviated @emph{MHD}.  The reader will learn how to
+implement basic HTTP functions from simple executable
+sample programs that implement various features.
+
+The text is supposed to be a supplement to the API reference manual of 
+@emph{GNU libmicrohttpd} and for that reason does not explain many of the parameters.
+Therefore, the reader should always consult the manual to find the exact meaning
+of the functions used in the tutorial.  Furthermore, the reader is 
+encouraged to study the relevant @emph{RFCs}, which document the HTTP standard.
+
+@emph{GNU libmicrohttpd} is assumed to be already installed.  This tutorial
+is written for version @value{VERSION}.  At the time being, 
+this tutorial has only been tested on @emph{GNU/Linux} machines even though
+efforts were made not to rely on anything that would prevent the samples from being
+built on similar systems.
diff --git a/doc/chapters/processingpost.inc b/doc/chapters/processingpost.inc
new file mode 100644
index 00000000..0677c7e8
--- /dev/null
+++ b/doc/chapters/processingpost.inc
@@ -0,0 +1,231 @@
+The previous chapters already have demonstrated a variety of possibilities to send information 
+to the HTTP server, but it is not recommended that the @emph{GET} method is used to alter the way
+the server operates. To induce changes on the server, the @emph{POST} method is preferred over
+and is much more powerful than @emph{GET} and will be introduced in this chapter.
+
+We are going to write an application that asks for the visitor's name and, after the user has posted it,
+composes an individual response text. Even though it was not mandatory to use the @emph{post} method here,
+as there is no permanent change caused by the post, it is an illustrative example on how to share data
+between different functions for the same connection. Furthermore, the reader should be able to extend
+it easily.
+
+@heading GET request
+When the first @emph{GET} request arrives, the server shall respond with a HTML page containing an
+edit field for the name.
+
+@verbatim
+const char* askpage = "<html><body>\
+                       What's your name, Sir?<br>\
+                       <form action=\"/namepost\" method=\"post\">\
+                       <input name=\"name\" type=\"text\"\
+                       <input type=\"submit\" value=\" Send \"></form>\
+                       </body></html>";
+@end verbatim
+@noindent
+
+The @code{action} entry is the @emph{URI} to be called by the browser when posting, and the
+@code{name} will be used later to be sure it is the editbox's content that has been posted.
+
+We also prepare the answer page, where the name is to be filled in later, and an error page 
+as the response for anything but proper @emph{GET} and @emph{POST} requests:
+
+@verbatim
+const char* greatingpage="<html><body><h1>Welcome, %s!</center></h1></body></html>";
+
+const char* errorpage="<html><body>This doesn't seem to be right.</body></html>";
+@end verbatim
+@noindent
+
+Whenever we need to send a page, we use an extra function
+@code{int SendPage(struct MHD_Connection *connection, const char* page)}
+for this, which does not contain anything new and whose implementation is therefore left out here. 
+
+
+@heading POST request
+Posted data can be of arbitrary and considerable size; for example, if a user uploads a big
+image to the server. Similar to the case of the header fields, there may also be different streams
+of posted data, such as one containing the text of an editbox and another the state of a button.
+Likewise, we will have to register an iterator function that is going to be called maybe several times 
+not only if there are different POSTs but also if one POST has only been received partly yet and
+needs processing before another chunk can be received.
+
+Such an iterator function is called by a @emph{postprocessor}, which must be created upon arriving
+of the post request.  We want the iterator function to read the first post data which is tagged
+@code{name} and to create an individual greeting string based on the template and the name. 
+But in order to pass this string to other functions and still be able to differentiate different
+connections, we must first define a structure to share the information, holding the most import entries.
+
+@verbatim
+struct connection_info_struct
+{
+  int connectiontype;
+  char *answerstring;
+  struct MHD_PostProcessor *postprocessor; 
+};
+@end verbatim
+@noindent
+
+With these information available to the iterator function, it is able to fulfill its task. 
+Once it has composed the greeting string, it returns @code{MHD_NO} to inform the post processor
+that it does not need to be called again. Note that this function does not handle processing
+of data for the same @code{key}. If we were to expect that the name will be posted in several
+chunks, we had to expand the namestring dynamically as additional parts of it with the same @code{key}
+came in. But in this example, the name is assumed to fit entirely inside one single packet.
+
+@verbatim
+int iterate_post (void *coninfo_cls, enum MHD_ValueKind kind, const char *key,
+                  const char *filename, const char *content_type,
+                  const char *transfer_encoding, const char *data, size_t off, size_t size)
+{
+  struct connection_info_struct *con_info = (struct connection_info_struct*) coninfo_cls;
+  
+
+  if (0 == strcmp (key, "name"))
+    {
+      if ((size > 0) && (size <= MAXNAMESIZE))
+        {
+          char *answerstring;
+          answerstring = malloc (MAXANSWERSIZE);
+          if (!answerstring) return MHD_NO;
+      
+          snprintf (answerstring, MAXANSWERSIZE, greatingpage, data);
+          con_info->answerstring = answerstring;      
+        } 
+      else con_info->answerstring = NULL;
+
+      return MHD_NO;
+    }
+
+  return MHD_YES;
+}
+@end verbatim
+@noindent
+
+Once a connection has been established, it can be terminated for many reasons. As these
+reasons include unexpected events, we have to register another function that cleans up any resources
+that might have been allocated for that connection by us, namely the post processor and the greetings
+string. This cleanup function must take into account that it will also be called for finished 
+requests other than @emph{POST} requests.
+
+@verbatim
+void request_completed (void *cls, struct MHD_Connection *connection, void **con_cls,
+                        enum MHD_RequestTerminationCode toe)
+{
+  struct connection_info_struct *con_info = (struct connection_info_struct*) *con_cls;
+
+
+  if (NULL == con_info) return;
+
+  if (con_info->connectiontype == POST)
+    {
+      MHD_destroy_post_processor (con_info->postprocessor);        
+      if (con_info->answerstring) free (con_info->answerstring);
+    }
+  
+  free (con_info);
+  *con_cls = NULL;   
+}
+@end verbatim
+@noindent
+
+@emph{GNU libmicrohttpd} is informed that it shall call the above function when the daemon is started
+in the main function.
+
+@verbatim
+...
+daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL,
+                           &answer_to_connection, NULL, MHD_OPTION_NOTIFY_COMPLETED,
+                           request_completed, NULL, MHD_OPTION_END);
+...
+@end verbatim
+@noindent
+
+@heading Request handling
+With all other functions prepared, we can now discuss the actual request handling.
+
+On the first iteration for a new request, we start by allocating a new instance of a 
+@code{ConnectionInfoStruct} structure, which will store all necessary information for later
+iterations and other functions.
+
+@verbatim
+int answer_to_connection (void *cls, struct MHD_Connection *connection, const char *url, 
+                          const char *method, const char *version, const char *upload_data, 
+                          unsigned int *upload_data_size, void **con_cls)
+{
+  if(NULL == *con_cls) 
+    {
+      struct connection_info_struct *con_info;
+
+      con_info = malloc (sizeof (struct connection_info_struct));
+      if (NULL == con_info) return MHD_NO;
+      con_info->answerstring = NULL;
+@end verbatim
+@noindent
+
+If the new request is a @emph{POST}, the postprocessor must be created now. In addition, the type
+of the request is stored for convenience.
+@verbatim
+      if (0 == strcmp (method, "POST")) 
+        {      
+          con_info->postprocessor = MHD_create_post_processor (connection, POSTBUFFERSIZE, 
+                                                               iterate_post, (void*) con_info);   
+
+          if (NULL == con_info->postprocessor) 
+            {
+              free (con_info); 
+              return MHD_NO;
+            }
+
+          con_info->connectiontype = POST;
+        } 
+      else con_info->connectiontype = GET;
+@end verbatim
+@noindent
+
+The address of our structure will both serve as the indicator for successive iterations and to remember
+the particular details about the connection.
+@verbatim
+      *con_cls = (void*) con_info; 
+      return MHD_YES;
+    }
+@end verbatim
+@noindent
+
+The rest of the function will not be executed on the first iteration. A @emph{GET} request is easily
+satisfied by sending the question form.
+@verbatim
+  if (0 == strcmp (method, "GET")) 
+    {
+      return send_page (connection, askpage);     
+    } 
+@end verbatim
+@noindent
+
+In case of @emph{POST}, we invoke the post processor for as long as data keeps incoming, setting
+@code{*upload_data_size} to zero in order to indicate that we have processed---or at least have
+considered---all of it.
+@verbatim
+  if (0 == strcmp (method, "POST")) 
+    {
+      struct connection_info_struct *con_info = *con_cls;
+
+      if (*upload_data_size != 0) 
+        {
+          MHD_post_process(con_info->postprocessor, upload_data, *upload_data_size);
+          *upload_data_size = 0;
+          
+          return MHD_YES;
+        } 
+      else if (NULL != con_info->answerstring) return send_page (connection, con_info->answerstring);
+    } 
+@end verbatim
+@noindent
+
+If they are neither @emph{GET} nor @emph{POST} requests, the error page is returned finally.
+@verbatim
+  return send_page(connection, errorpage); 
+}
+@end verbatim
+@noindent
+
+These were the important parts of the program @code{simplepost.c}.
diff --git a/doc/chapters/responseheaders.inc b/doc/chapters/responseheaders.inc
new file mode 100644
index 00000000..19d10142
--- /dev/null
+++ b/doc/chapters/responseheaders.inc
@@ -0,0 +1,177 @@
+Now that we are able to inspect the incoming request in great detail,
+this chapter discusses the means to enrich the outgoing responses likewise.
+
+As you have learned in the @emph{Hello, Browser} chapter, some obligatory 
+header fields are added and set automatically for simple responses by the library
+itself but if more advanced features are desired, additional fields have to be created.
+One of the possible fields is the content type field and an example will be developed around it.
+This will lead to an application capable of correctly serving different types of files.
+
+
+When we responded with HTML page packed in the static string previously, the client had no choice
+but guessing about how to handle the response, because the server hadn't told him. 
+What if we had sent a picture or a sound file?  Would the message have been understood
+or merely been displayed as an endless stream of random characters in the browser?
+This is what the mime content types are for. The header of the response is extended
+by certain information about how the data is to be interpreted. 
+
+To introduce the concept, a picture of the format @emph{PNG} will be sent to the client 
+and labeled accordingly with @code{image/png}.
+Once again, we can base the new example on the @code{hellobrowser} program.
+
+@verbatim
+#define FILENAME "picture.png"
+#define MIMETYPE "image/png"
+
+int answer_to_connection (void *cls, struct MHD_Connection *connection, const char *url, 
+                          const char *method, const char *version, const char *upload_data, 
+                          unsigned int *upload_data_size, void **con_cls)
+{
+  unsigned char *buffer = NULL;
+  struct MHD_Response *response;
+@end verbatim
+@noindent
+ 
+We want the program to load the graphics file into memory:
+@verbatim
+  long size;
+  FILE *fp;
+  int ret = 0;
+
+  if (0 != strcmp(method, "GET")) return MHD_NO;
+
+  size = get_file_size (FILENAME);
+  if (size != 0)
+    {
+      fp = fopen (FILENAME, "rb");
+      if (fp) 
+        {
+          buffer = malloc (size);
+      
+            if (buffer)
+              if (size == fread (buffer, 1, size, fp)) ret = 1;
+      
+          fclose(fp);
+        }     
+    }
+@end verbatim
+@noindent
+
+The @code{GetFileSize} function, which returns a size of zero if the file could not be opened or
+found, is left out on this page for tidiness. 
+
+When dealing with files and allocating memory, there is a lot that could go wrong on the
+server side and if so, the client should be informed with @code{MHD_HTTP_INTERNAL_SERVER_ERROR}.
+
+@verbatim
+  if (!ret) 
+    {
+      const char *errorstr = "<html><body>An internal server error has occured!\
+                              </body></html>";
+
+      if (buffer) free(buffer);
+    
+      response = MHD_create_response_from_data(strlen(errorstr), (void*)errorstr,
+                                               MHD_NO, MHD_NO);
+
+      if (response)
+        {     
+          ret = MHD_queue_response (connection, MHD_HTTP_INTERNAL_SERVER_ERROR, response);
+          MHD_destroy_response (response);
+
+          return MHD_YES;    
+        } 
+      else return MHD_NO;
+    }
+@end verbatim
+@noindent
+
+Note that we nevertheless have to create a response object even for sending a simple error code.
+Otherwise, the connection would just be closed without comment, leaving the client curious about
+what has happened.
+
+But in the case of success a response will be constructed that contains the buffer filled with the
+file's content. 
+
+@verbatim
+response = MHD_create_response_from_data (size, (void*)buffer, MHD_YES, MHD_NO);
+@end verbatim
+@noindent
+
+Contrary to the above case where a static string will be sent, this time we have to 
+keep track of the dynamically allocated buffer. As discussed in the @ref{Hello browser example}, 
+the buffer cannot be safely freed as soon as the function call returns. Instead, we ask the function
+to keep charge of freeing the buffer itself when it is not longer needed. Thus, no further @code{free}
+command is invoked by us.
+
+Up to this point, there was little new. The actual novelty is that we enhance the header with the
+meta data about the content. Aware of the field's name we want to add, it is as easy as that:
+@verbatim
+MHD_add_response_header(response, "Content-Type", MIMETYPE);
+@end verbatim
+@noindent
+We do not have to append a colon expected by the protocol hehind the first 
+field---@emph{GNU libhttpdmicro} will take care of this. 
+
+The function finishes with the well-known lines
+@verbatim
+  ret = MHD_queue_response (connection, MHD_HTTP_OK, response);
+  MHD_destroy_response (response);
+  return ret;
+}
+@end verbatim
+@noindent
+
+The complete program @code{responseheaders.c} is in the @code{examples} section as usual.
+Find a @emph{PNG} file you like and save it to the directory the example is run from under the name
+@code{picture.png}. You should find the image displayed on your browser if everything worked well.
+
+@heading Remarks
+The include file of the @emph{MHD} library comes with the header types mentioned in @emph{RFC 2616}
+already defined as macros. Thus, we could have written @code{MHD_HTTP_HEADER_CONTENT_TYPE} instead
+of @code{"Content-Type"} as well. However, one is not limited to these standard headers and could
+add custom response headers without violating the protocol. Whether, and how, the client would react
+to these custom header is up to the receiver. Likewise, the client is allowed to send custom request
+headers to the server as well, opening up yet more possibilities how client and server could 
+communicate with each other.
+
+The method of creating the response from one big chunk of data is only feasible for smaller files.
+A public file server satisfying many request at the same time would be choking under these high
+demands on memory very soon. Serving responses in smaller parts would be more adequate here and
+will be a topic of a future chapter.
+
+@heading Exercises
+@itemize @bullet
+
+@item
+Remember that the original program was written under a few assumptions---a small, static response
+being one of them. In order to simulate a very large or hard to reach file that cannot be provided
+instantly, postpone the queuing in the callback with the @code{sleep} function for 30 seconds 
+@emph{if} the file @code{/big.png} is requested (but deliver the same as above). A request for
+@code{/picture.png} should provide just the same but without any artificial delays.
+
+Now start two instances of your browser (or even use two machines) and see how the second client
+is put on hold while the first waits for his request on the slow file to be fulfilled.
+
+Finally, change the sourcecode to use @code{MHD_USE_THREAD_PER_CONNECTION} when the daemon is 
+started and try again.
+
+
+@item
+Did you succeed in implementing the clock exercise yet? This time, let the server save the 
+program's start time @code{t} and implement a response simulating a countdown that reaches 0 at
+@code{t+60}. Returning a message saying on which point the countdown is, the response should
+ultimately be to reply "Done" if the program has been running long enough,
+
+A non official, but widely understood, response header line is @code{Refresh: DELAY; url=URL} with
+the uppercase words substituted to tell the client it should request the given resource after 
+the given delay again. Improve your program in that the browser (any modern browser should work)
+automatically reconnects and asks for the status again every 5 seconds or so. The URL would have
+to be composed so that it begins with "http://", followed by the @emph{URI} the server is reachable
+from the client's point of view.
+
+Maybe you want also to visualize the countdown as a status bar by creating a 
+@code{<table>} consisting of one row and @code{n} columns whose fields contain small images of either
+a red or a green light.
+
+@end itemize