diff options
-rw-r--r-- | doc/chapters/hellobrowser.inc | 50 | ||||
-rw-r--r-- | doc/libmicrohttpd-tutorial.texi | 10 |
2 files changed, 30 insertions, 30 deletions
diff --git a/doc/chapters/hellobrowser.inc b/doc/chapters/hellobrowser.inc index 58597786..8ff81e4b 100644 --- a/doc/chapters/hellobrowser.inc +++ b/doc/chapters/hellobrowser.inc | |||
@@ -1,13 +1,13 @@ | |||
1 | The most basic task for a HTTP server is to deliver a static text message to any client connecting to it. | 1 | The most basic task for a HTTP server is to deliver a static text message to any client connecting to it. |
2 | Given that this is also easy to implement, it is an excellent problem to start with. | 2 | Given that this is also easy to implement, it is an excellent problem to start with. |
3 | 3 | ||
4 | For now, the particular URI the client asks for shall have no effect on the message that will | 4 | For now, the particular URI the client asks for shall have no effect on the message that will |
5 | be returned. In addition, the server shall end the connection after the message has been sent so that | 5 | be returned. In addition, the server shall end the connection after the message has been sent so that |
6 | the client will know there is nothing more to expect. | 6 | the client will know there is nothing more to expect. |
7 | 7 | ||
8 | The C program @code{hellobrowser.c}, which is to be found in the examples section, does just that. | 8 | The C program @code{hellobrowser.c}, which is to be found in the examples section, does just that. |
9 | If you are very eager, you can compile and start it right away but it is advisable to type the | 9 | If you are very eager, you can compile and start it right away but it is advisable to type the |
10 | lines in by yourself as they will be discussed and explained in detail. | 10 | lines in by yourself as they will be discussed and explained in detail. |
11 | 11 | ||
12 | After the necessary includes and the definition of the port which our server should listen on | 12 | After the necessary includes and the definition of the port which our server should listen on |
13 | @verbatim | 13 | @verbatim |
@@ -23,7 +23,7 @@ After the necessary includes and the definition of the port which our server sho | |||
23 | @noindent | 23 | @noindent |
24 | the desired behaviour of our server when HTTP request arrive has to be implemented. We already have | 24 | the desired behaviour of our server when HTTP request arrive has to be implemented. We already have |
25 | agreed that it should not care about the particular details of the request, such as who is requesting | 25 | agreed that it should not care about the particular details of the request, such as who is requesting |
26 | what. The server will respond merely with the same small HTML page to every request. | 26 | what. The server will respond merely with the same small HTML page to every request. |
27 | 27 | ||
28 | The function we are going to write now will be called by @emph{GNU libmicrohttpd} every time an | 28 | The function we are going to write now will be called by @emph{GNU libmicrohttpd} every time an |
29 | appropriate request comes in. While the name of this callback function is arbitrary, its parameter | 29 | appropriate request comes in. While the name of this callback function is arbitrary, its parameter |
@@ -39,10 +39,10 @@ daemon to sent the reply. | |||
39 | 39 | ||
40 | Talking about the reply, it is defined as a string right after the function header | 40 | Talking about the reply, it is defined as a string right after the function header |
41 | @verbatim | 41 | @verbatim |
42 | int answer_to_connection (void *cls, struct MHD_Connection *connection, | 42 | int answer_to_connection (void *cls, struct MHD_Connection *connection, |
43 | const char *url, | 43 | const char *url, |
44 | const char *method, const char *version, | 44 | const char *method, const char *version, |
45 | const char *upload_data, | 45 | const char *upload_data, |
46 | size_t *upload_data_size, void **con_cls) | 46 | size_t *upload_data_size, void **con_cls) |
47 | { | 47 | { |
48 | const char *page = "<html><body>Hello, browser!</body></html>"; | 48 | const char *page = "<html><body>Hello, browser!</body></html>"; |
@@ -53,7 +53,7 @@ int answer_to_connection (void *cls, struct MHD_Connection *connection, | |||
53 | HTTP is a rather strict protocol and the client would certainly consider it "inappropriate" if we | 53 | HTTP is a rather strict protocol and the client would certainly consider it "inappropriate" if we |
54 | 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 | 54 | 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 |
55 | just have to ask. Our reply string packed in the necessary layers will be called a "response". | 55 | just have to ask. Our reply string packed in the necessary layers will be called a "response". |
56 | To obtain such a response we hand our data (the reply--string) and its size over to the | 56 | To obtain such a response we hand our data (the reply--string) and its size over to the |
57 | @code{MHD_create_response_from_buffer} function. The last two parameters basically tell @emph{MHD} | 57 | @code{MHD_create_response_from_buffer} function. The last two parameters basically tell @emph{MHD} |
58 | that we do not want it to dispose the message data for us when it has been sent and there also needs | 58 | that we do not want it to dispose the message data for us when it has been sent and there also needs |
59 | no internal copy to be done because the @emph{constant} string won't change anyway. | 59 | no internal copy to be done because the @emph{constant} string won't change anyway. |
@@ -68,11 +68,11 @@ no internal copy to be done because the @emph{constant} string won't change anyw | |||
68 | @end verbatim | 68 | @end verbatim |
69 | 69 | ||
70 | @noindent | 70 | @noindent |
71 | Now that the the response has been laced up, it is ready for delivery and can be queued for sending. | 71 | Now that the the response has been laced up, it is ready for delivery and can be queued for sending. |
72 | This is done by passing it to another @emph{GNU libmicrohttpd} function. As all our work was done in | 72 | This is done by passing it to another @emph{GNU libmicrohttpd} function. As all our work was done in |
73 | the scope of one function, the recipient is without doubt the one associated with the | 73 | the scope of one function, the recipient is without doubt the one associated with the |
74 | local variable @code{connection} and consequently this variable is given to the queue function. | 74 | local variable @code{connection} and consequently this variable is given to the queue function. |
75 | Every HTTP response is accompanied by a status code, here "OK", so that the client knows | 75 | Every HTTP response is accompanied by a status code, here "OK", so that the client knows |
76 | this response is the intended result of his request and not due to some error or malfunction. | 76 | this response is the intended result of his request and not due to some error or malfunction. |
77 | 77 | ||
78 | Finally, the packet is destroyed and the return value from the queue returned, | 78 | Finally, the packet is destroyed and the return value from the queue returned, |
@@ -88,14 +88,14 @@ already being set at this point to either MHD_YES or MHD_NO in case of success o | |||
88 | @end verbatim | 88 | @end verbatim |
89 | 89 | ||
90 | @noindent | 90 | @noindent |
91 | With the primary task of our server implemented, we can start the actual server daemon which will listen | 91 | With the primary task of our server implemented, we can start the actual server daemon which will listen |
92 | on @code{PORT} for connections. This is done in the main function. | 92 | on @code{PORT} for connections. This is done in the main function. |
93 | @verbatim | 93 | @verbatim |
94 | int main () | 94 | int main () |
95 | { | 95 | { |
96 | struct MHD_Daemon *daemon; | 96 | struct MHD_Daemon *daemon; |
97 | 97 | ||
98 | daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL, | 98 | daemon = MHD_start_daemon (MHD_USE_SELECT_INTERNALLY, PORT, NULL, NULL, |
99 | &answer_to_connection, NULL, MHD_OPTION_END); | 99 | &answer_to_connection, NULL, MHD_OPTION_END); |
100 | if (NULL == daemon) return 1; | 100 | if (NULL == daemon) return 1; |
101 | 101 | ||
@@ -121,7 +121,7 @@ main thread or else the program will terminate prematurely. We let it pause in a | |||
121 | friendly manner by waiting for the enter key to be pressed. In the end, we stop the daemon so it can | 121 | friendly manner by waiting for the enter key to be pressed. In the end, we stop the daemon so it can |
122 | do its cleanup tasks. | 122 | do its cleanup tasks. |
123 | @verbatim | 123 | @verbatim |
124 | getchar (); | 124 | getchar (); |
125 | 125 | ||
126 | MHD_stop_daemon (daemon); | 126 | MHD_stop_daemon (daemon); |
127 | return 0; | 127 | return 0; |
@@ -132,9 +132,9 @@ do its cleanup tasks. | |||
132 | @noindent | 132 | @noindent |
133 | The first example is now complete. | 133 | The first example is now complete. |
134 | 134 | ||
135 | Compile it with | 135 | Compile it with |
136 | @verbatim | 136 | @verbatim |
137 | cc hellobrowser.c -o hellobrowser -I$PATH_TO_LIBMHD_INCLUDES | 137 | cc hellobrowser.c -o hellobrowser -I$PATH_TO_LIBMHD_INCLUDES |
138 | -L$PATH_TO_LIBMHD_LIBS -lmicrohttpd | 138 | -L$PATH_TO_LIBMHD_LIBS -lmicrohttpd |
139 | @end verbatim | 139 | @end verbatim |
140 | with the two paths set accordingly and run it. | 140 | with the two paths set accordingly and run it. |
@@ -145,7 +145,7 @@ static HTML page it got from our minimal server. | |||
145 | 145 | ||
146 | @heading Remarks | 146 | @heading Remarks |
147 | To keep this first example as small as possible, some drastic shortcuts were taken and are to be | 147 | To keep this first example as small as possible, some drastic shortcuts were taken and are to be |
148 | discussed now. | 148 | discussed now. |
149 | 149 | ||
150 | Firstly, there is no distinction made between the kinds of requests a client could send. We implied | 150 | Firstly, there is no distinction made between the kinds of requests a client could send. We implied |
151 | that the client sends a GET request, that means, that he actually asked for some data. Even when | 151 | that the client sends a GET request, that means, that he actually asked for some data. Even when |
@@ -168,16 +168,16 @@ Both of these issues you will find addressed in the official @code{minimal_examp | |||
168 | the @code{src/examples} directory of the @emph{MHD} package. The source code of this | 168 | the @code{src/examples} directory of the @emph{MHD} package. The source code of this |
169 | program should look very familiar to you by now and easy to understand. | 169 | program should look very familiar to you by now and easy to understand. |
170 | 170 | ||
171 | For our example, the @code{must_copy} and @code{must_free} parameter at the response construction | 171 | For our example, we create the response from a static (persistent) buffer in memory and thus pass @code{MHD_RESPMEM_PERSISTENT} to the response construction |
172 | function could be set to @code{MHD_NO}. In the usual case, responses cannot be sent immediately | 172 | function. In the usual case, responses are not transmitted immediately |
173 | after being queued. For example, there might be other data on the system that needs to be sent with | 173 | after being queued. For example, there might be other data on the system that needs to be sent with |
174 | a higher priority. Nevertheless, the queue function will return successfully---raising the problem | 174 | a higher priority. Nevertheless, the queue function will return successfully---raising the problem |
175 | that the data we have pointed to may be invalid by the time it is about being sent. This is not an | 175 | that the data we have pointed to may be invalid by the time it is about being sent. This is not an |
176 | issue here because we can expect the @code{page} string, which is a constant @emph{string literal} | 176 | issue here because we can expect the @code{page} string, which is a constant @emph{string literal} |
177 | here, to be static. That means it will be present and unchanged for as long as the program runs. | 177 | here, to be static. That means it will be present and unchanged for as long as the program runs. |
178 | For dynamic data, one could choose to either have @emph{MHD} free the memory @code{page} points | 178 | For dynamic data, one could choose to either have @emph{MHD} free the memory @code{page} points |
179 | to itself when it is not longer needed or, alternatively, have the library to make and manage | 179 | to itself when it is not longer needed (by passing @code{MHD_RESPMEM_MUST_FREE}) or, alternatively, have the library to make and manage |
180 | its own copy of it. | 180 | its own copy of it (by passing @code{MHD_RESPMEM_MUST_COPY}). Naturally, this last option is the most expensive. |
181 | 181 | ||
182 | @heading Exercises | 182 | @heading Exercises |
183 | @itemize @bullet | 183 | @itemize @bullet |
@@ -191,7 +191,7 @@ Host: itsme | |||
191 | @end verbatim | 191 | @end verbatim |
192 | @noindent | 192 | @noindent |
193 | and see what the server returns to you. | 193 | and see what the server returns to you. |
194 | 194 | ||
195 | 195 | ||
196 | @item | 196 | @item |
197 | Also, try other requests, like POST, and see how our server does not mind and why. | 197 | Also, try other requests, like POST, and see how our server does not mind and why. |
@@ -214,7 +214,7 @@ former static string. | |||
214 | 214 | ||
215 | 215 | ||
216 | @item | 216 | @item |
217 | @emph{Demanding:} Write a separate function returning a string containing some useful information, | 217 | @emph{Demanding:} Write a separate function returning a string containing some useful information, |
218 | for example, the time. Pass the function's address as the sixth parameter and evaluate this function | 218 | for example, the time. Pass the function's address as the sixth parameter and evaluate this function |
219 | on every request anew in @code{answer_to_connection}. Remember to free the memory of the string | 219 | on every request anew in @code{answer_to_connection}. Remember to free the memory of the string |
220 | every time after satisfying the request. | 220 | every time after satisfying the request. |
diff --git a/doc/libmicrohttpd-tutorial.texi b/doc/libmicrohttpd-tutorial.texi index 104f00c3..8fd7b566 100644 --- a/doc/libmicrohttpd-tutorial.texi +++ b/doc/libmicrohttpd-tutorial.texi | |||
@@ -1,10 +1,10 @@ | |||
1 | \input texinfo @c -*-texinfo-*- | 1 | \input texinfo @c -*-texinfo-*- |
2 | @finalout | 2 | @finalout |
3 | @setfilename libmicrohttpd-tutorial.info | 3 | @setfilename libmicrohttpd-tutorial.info |
4 | @set UPDATED 17 November 2013 | 4 | @set UPDATED 2 April 2016 |
5 | @set UPDATED-MONTH November 2013 | 5 | @set UPDATED-MONTH April 2016 |
6 | @set EDITION 0.9.23 | 6 | @set EDITION 0.9.48 |
7 | @set VERSION 0.9.23 | 7 | @set VERSION 0.9.48 |
8 | @settitle A tutorial for GNU libmicrohttpd | 8 | @settitle A tutorial for GNU libmicrohttpd |
9 | @c Unify all the indices into concept index. | 9 | @c Unify all the indices into concept index. |
10 | @syncodeindex fn cp | 10 | @syncodeindex fn cp |
@@ -24,7 +24,7 @@ updated @value{UPDATED}. | |||
24 | 24 | ||
25 | Copyright (c) 2008 Sebastian Gerhardt. | 25 | Copyright (c) 2008 Sebastian Gerhardt. |
26 | 26 | ||
27 | Copyright (c) 2010, 2011, 2012, 2013 Christian Grothoff. | 27 | Copyright (c) 2010, 2011, 2012, 2013, 2016 Christian Grothoff. |
28 | @quotation | 28 | @quotation |
29 | Permission is granted to copy, distribute and/or modify this document | 29 | Permission is granted to copy, distribute and/or modify this document |
30 | under the terms of the GNU Free Documentation License, Version 1.3 | 30 | under the terms of the GNU Free Documentation License, Version 1.3 |