diff options
Diffstat (limited to 'doc/chapters/hellobrowser.inc')
| -rw-r--r-- | doc/chapters/hellobrowser.inc | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/doc/chapters/hellobrowser.inc b/doc/chapters/hellobrowser.inc new file mode 100644 index 00000000..58597786 --- /dev/null +++ b/doc/chapters/hellobrowser.inc @@ -0,0 +1,222 @@ +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 URI 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 necessary includes and the definition of the port which our server should listen on +@verbatim +#include <sys/types.h> +#include <sys/select.h> +#include <sys/socket.h> +#include <microhttpd.h> + +#define PORT 8888 + +@end verbatim + +@noindent +the desired behaviour of our server when HTTP request arrive has 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, + size_t *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 with additional information stored in so-called headers and footers. 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_buffer} 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_buffer (strlen (page), + (void*) page, MHD_RESPMEM_PERSISTENT); + +@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 +example, 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{answer_to_connection} 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_LIBS -lmicrohttpd +@end verbatim +with the two paths set accordingly and run it. + +Now open your favorite Internet browser and go to the address @code{http://localhost:8888/}, provided that 8888 +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. This is typically not what you want as it +disables HTTP pipelining. The correct approach is to simply not queue a message on the first +callback unless there is an error. The @code{void**} argument to the callback provides a location +for storing information about the history of the connection; for the first call, the pointer +will point to NULL. A simplistic way to differenciate the first call from others is to check +if the pointer is NULL and set it to a non-NULL value during the first call. + +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{MHD} 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 @code{telnet} or @code{netcat} to connect to it. Try to form a +valid HTTP 1.1 request yourself like +@verbatim +GET /dontcare HTTP/1.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{answer_to_connection}. Remember to free the memory of the string +every time after satisfying the request. + +@end itemize |