Mercurial > ecos
annotate packages/net/athttpd/current/doc/athttpd.sgml @ 3292:7f8e529b4d82 default tip
Fix FREESCALE_EDMA_NBYTES_MLOFFYES_MLOFF() so it works with negative offsets.
| author | vae |
|---|---|
| date | Wed, 29 Apr 2015 23:31:48 +0000 |
| parents | 74dbf4c3f2e1 |
| children |
| rev | line source |
|---|---|
|
2449
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
1 <!-- DOCTYPE part PUBLIC "-//OASIS//DTD DocBook V3.1//EN" --> |
| 2250 | 2 <!-- =============================================================== --> |
| 3 <!-- --> | |
| 4 <!-- athttpd.sgml --> | |
| 5 <!-- --> | |
| 6 <!-- Another Tiny HTTPD Server for eCos --> | |
| 7 <!-- --> | |
| 8 <!-- =============================================================== --> | |
|
2729
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
9 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
10 <!-- =============================================================== --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
11 <!-- Copyright (C) 2003, 2004, 2007 Free Software Foundation, Inc. --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
12 <!-- This material may be distributed only subject to the terms --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
13 <!-- and conditions set forth in the Open Publication License, v1.0 --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
14 <!-- or later (the latest version is presently available at --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
15 <!-- http://www.opencontent.org/openpub/) --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
16 <!-- Distribution of the work or derivative of the work in any --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
17 <!-- standard (paper) book form is prohibited unless prior --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
18 <!-- permission obtained from the copyright holder --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
19 <!-- =============================================================== --> |
|
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
2485
diff
changeset
|
20 <!-- ####ECOSDOCCOPYRIGHTEND#### --> |
| 2250 | 21 <!-- =============================================================== --> |
| 22 <!-- #####DESCRIPTIONBEGIN#### --> | |
| 23 <!-- --> | |
| 24 <!-- ####DESCRIPTIONEND#### --> | |
| 25 <!-- =============================================================== --> | |
| 26 | |
| 27 <!-- }}} --> | |
| 28 | |
| 29 | |
| 30 <part id="athttpd"> | |
| 31 <title>Another Tiny HTTP Server for <productname>eCos</productname></title> | |
| 32 | |
| 33 <partintro> | |
| 34 <para> | |
| 35 This package provides an extensible, small footprint, full featured HTTP | |
| 36 server for <productname>eCos</productname>. Many of these features can be | |
| 37 disabled via the configuration tool, thus reducing the footprint of the server. | |
| 38 The server has been written for the FreeBSD network stack. | |
| 39 </para> | |
| 40 </partintro> | |
| 41 | |
| 42 <chapter id="net-athttpd"> | |
| 43 <title>The ATHTTP Server</title> | |
| 44 <sect1 id="athttpd-features"> | |
| 45 <title>Features</title> | |
| 46 <para>This ATHTTP implementation provides the following features:</para> | |
| 47 <itemizedlist> | |
| 48 <listitem><para>GET, POST and HEAD Methods</para></listitem> | |
| 49 <listitem><para>File system Access</para></listitem> | |
| 50 <listitem><para>Callbacks to C functions</para></listitem> | |
| 51 <listitem><para>MIME type support</para></listitem> | |
| 52 <listitem><para>CGI mechanism through the OBJLOADER package or through a | |
| 53 simple tcl interpreter</para></listitem> | |
|
2485
0e9d1d1df4a0
* src/jim-aio.c (JimAioHandlerCommand): GCC 4.3.1 pointed out a
asl
parents:
2449
diff
changeset
|
54 <listitem><para>Basic and Digest (MD5) Authentication</para></listitem> |
| 2250 | 55 <listitem><para>Directory Listing</para></listitem> |
| 56 <listitem><para>Extendable Internal Resources</para></listitem> | |
| 57 </itemizedlist> | |
| 58 | |
| 59 <para> | |
| 60 Ecos tables are used extensively throught the server to provide a high degree | |
| 61 of customization.</para> | |
| 62 </sect1> | |
| 63 | |
| 64 <sect1 id="athttpd-using"> | |
| 65 <title>Starting the server</title> | |
| 66 <para> | |
| 67 In order to start the web server, the user needs to call the function:</para> | |
| 68 | |
| 69 <programlisting width=72> | |
| 70 cyg_httpd_start(); | |
| 2265 | 71 </programlisting> |
| 2250 | 72 |
| 73 <para>in the application code. The server initialization code spawns a new | |
| 74 thread which calls <command>init_all_network_interfaces()</command> to | |
| 75 initialize the TCP/IP stack and then starts the deamon. The function is safe | |
| 76 to call multiple times. | |
| 77 </para> | |
| 78 </sect1> | |
| 79 | |
| 2265 | 80 <sect1 id="athttpd-mime-types"> |
| 81 <title>MIME types</title> | |
| 82 <para> | |
| 83 The server has an internal table with all the recognized mime types. Each time | |
| 84 a file or an internal resource is sent out by the server, its extension is | |
| 85 searched in this table and if a match is found, the associated MIME type is | |
| 86 then sent out in the header. | |
| 87 | |
| 88 The server already provides entries for the following standard file extensions: | |
| 89 | |
| 2326 | 90 'html', 'htm', 'gif', 'jpg', 'css', 'js', 'png' |
| 2265 | 91 |
| 92 and the user is responsible for adding any further entry. The syntax for | |
| 93 adding an entry is the following:</para> | |
| 94 | |
| 95 <para><programlisting width=72> | |
| 96 CYG_HTTPD_MIME_TABLE_ENTRY(entry_label, extension_string, mime_tipe_sting); | |
| 97 | |
| 98 entry table : an identifier unique to this entry | |
| 99 extension string : a string containing the extension for this entry | |
| 100 type_string : the mime string. The strings for many more mime types | |
| 101 is included in a file in the "doc" directory. | |
| 102 </programlisting></para> | |
| 103 | |
| 104 <para> | |
| 105 The following is an example of how to add the Adobe Portable Document Format | |
| 106 <command>pdf</command> MIME type to the table:</para> | |
| 107 | |
| 108 <para><programlisting width=72> | |
| 109 CYG_HTTPD_MIME_TABLE_ENTRY(hal_pdf_entry, "pdf", "application/pdf"); | |
| 110 </programlisting></para> | |
| 111 | |
| 112 <sect2 id="athttpd-mime-types-chunked"> | |
| 113 <title>MIME Types for Chunked Frames</title> | |
| 114 <para> | |
| 115 For chunked frames, which are generally used inside c language callbacks, there | |
| 116 is no file name to match an extension to, and thus the extension to be used | |
| 117 must be passed in the <command>cyg_httpd_start_chunked()</command> call. The | |
| 118 server will then scan the MIME table to find a MIME type to match the extension. | |
| 119 | |
| 120 For example, to start a chunked transfer of an <command>html</command> file, | |
| 121 the following call is used:</para> | |
| 122 | |
| 123 <para><programlisting width=72> | |
| 124 cyg_httpd_start_chunked("html"); | |
| 125 </programlisting></para> | |
| 126 | |
| 127 <para> | |
| 128 In any event, it is the responsibility of the user to make sure that a match to | |
| 129 all used extensions is found in the table search. Failing this, | |
| 130 the default MIME type specified in the CYGDAT_NET_ATHTTPD_DEFAULT_MIME_TYPE | |
| 131 string is returned.</para> | |
| 132 </sect2> | |
| 133 </sect1> | |
| 134 | |
| 2250 | 135 <sect1 id="athttpd-callback"> |
| 136 <title>C language callback functions</title> | |
| 137 <para> | |
| 138 The server allows the association of particular URLs to C language callback | |
| 2265 | 139 functions. eCos tables are used to define the association between a URL and its |
| 140 corresponding callback. The syntax of the macro to add callback entries to | |
| 141 the table is: | |
| 2250 | 142 </para> |
| 143 | |
| 144 <para><programlisting width=72> | |
| 2265 | 145 CYG_HTTPD_HANDLER_TABLE_ENTRY(entry_label, url_string, callback); |
| 146 | |
| 147 entry table : an identifier unique to this entry. | |
| 148 url_string : a string with the extension url that will be appended to the | |
| 149 default directory. | |
| 150 callback : a function with a prototype: | |
|
2446
a72554718436
* doc/athttpd.cdl: Fixed typos in doc. Return value from handler is not
jlarmour
parents:
2326
diff
changeset
|
151 cyg_int32 callback_function(CYG_HTTPD_STATE*); |
|
a72554718436
* doc/athttpd.cdl: Fixed typos in doc. Return value from handler is not
jlarmour
parents:
2326
diff
changeset
|
152 Return value is ignored - just return 0. |
| 2265 | 153 </programlisting></para> |
| 2250 | 154 |
| 155 <para> | |
|
2446
a72554718436
* doc/athttpd.cdl: Fixed typos in doc. Return value from handler is not
jlarmour
parents:
2326
diff
changeset
|
156 <command>CYG_HTTPD_STATE*</command> is a pointer to a structure that |
| 2250 | 157 contains, among others, a buffer (outbuffer) that can be used to send data |
| 2265 | 158 out. The definitions of the structure is in http.h.</para> |
| 159 | |
| 2250 | 160 <para> |
| 2265 | 161 The following is an example of how to add a callback to a function myForm() |
| 162 whenever the URL /myform.cgi is requested: | |
| 2250 | 163 </para> |
| 164 | |
| 165 <programlisting width=72> | |
| 2265 | 166 CYG_HTTPD_HANDLER_TABLE_ENTRY(hal_cb_entry, "/myform.cgi", myForm); |
| 2250 | 167 </programlisting> |
| 2265 | 168 |
| 2250 | 169 <para> |
| 170 and somewhere in the source tree there is a function:</para> | |
| 171 | |
| 172 <programlisting> | |
|
2446
a72554718436
* doc/athttpd.cdl: Fixed typos in doc. Return value from handler is not
jlarmour
parents:
2326
diff
changeset
|
173 cyg_int32 myForm(CYG_HTTPD_STATE* p) |
| 2250 | 174 { |
| 175 cyg_httpd_start_chunked("html"); | |
| 176 strcpy(p->outbuffer, "eCos Web Server"); | |
| 177 cyg_httpd_write_chunked(p->outbuffer, strlen(p->outbuffer)) | |
| 178 cyg_httpd_end_chunked(); | |
| 2265 | 179 } |
| 2250 | 180 </programlisting> |
| 181 | |
| 182 <para>This function also shows the correct method of using the chunked frames | |
| 183 API inside a c language callback and also shows the use of outbuffer to | |
| 184 collect data to send out.</para> | |
| 185 | |
| 186 <para>Chunked frames are useful when the size of the frame is not known upfront. | |
| 187 In this case it possible to send a response in chunks of various sizes, and | |
| 2265 | 188 terminate it with a null chunk (See RFC 2616 for details). To use chunked |
| 2250 | 189 frames, the <command>cyg_httpd_start_chunked()</command> function is used. |
| 190 The prototype is the following:</para> | |
| 191 | |
| 192 <programlisting> | |
| 193 ssize_t cyg_httpd_start_chunked(char *); | |
| 194 </programlisting> | |
| 195 | |
| 196 <para>The only parameter is the <command>extension</command> to use in the | |
| 197 search for the MIME type. For most files this will be "html" or "htm" and | |
| 198 it will be searched in the MIME table for an approriate MIME type that will | |
| 199 be sent along in the header. The function returns the number of bytes sent | |
| 200 out.</para> | |
| 201 | |
| 202 <para>The chunked frame must be terminated by a call to | |
| 203 <command>cyg_httpd_end_chunked()</command>:</para> | |
| 204 | |
| 205 <programlisting> | |
| 206 void cyg_httpd_end_chunked()(void); | |
| 207 </programlisting> | |
| 208 | |
| 209 <para>In between these two calls, the user can call the function | |
| 2265 | 210 <command>cyg_httpd_write_chunked()</command> to send out data any number of |
| 2250 | 211 times. It is important that <command>cyg_httpd_write_chunked()</command> be |
| 212 the only function used to send data out for chunked frames. This | |
| 213 guarantees that proper formatting of the response is respected. | |
| 214 The prototype for the function is:</para> | |
| 215 | |
| 216 <programlisting> | |
| 217 ssize_t cyg_httpd_write_chunked(char* p, int len); | |
| 218 </programlisting> | |
| 219 | |
| 220 <para>The 'char*' points to the data to send out, the 'int' is the length of the | |
| 221 data to send.</para> | |
| 222 | |
| 223 <para>In the case in which the size of the data is known upfront, the | |
| 224 callback can instead create the header with a call to | |
| 225 <command>cyg_httpd_create_std_header()</command> with the following | |
| 226 prototype:</para> | |
| 227 | |
| 228 <programlisting> | |
| 229 void cyg_httpd_create_std_header(char *ext, int len); | |
| 230 | |
| 231 extension : the extension used in the search of the MIME type | |
| 232 len : length of the data to send out | |
| 233 </programlisting> | |
| 234 | |
| 2265 | 235 <para>and use |
| 236 <command>cyg_httpd_write()</command> to send data out to the client. The | |
| 237 prototype of <command>cyg_httpd_write()</command> is the same as | |
| 238 <command>cyg_httpd_write_chunked()</command></para></sect1> | |
| 2250 | 239 |
| 240 <sect1 id="athttpd-cgi"> | |
| 241 <title>CGI</title> | |
| 242 <para> | |
| 2265 | 243 The web server allows writing of pseudo-CGI programs. This is helpful in order |
| 244 to modify the functionality of the server without having to recompile it and | |
| 2250 | 245 reflash it.</para> |
| 246 | |
| 247 <para>One way to implement CGI is, of course, the C language callback mechanism | |
| 248 described above: This assumes, of course, that all the callbacks are written | |
| 2265 | 249 by compile time and cannot be modified later on. Another way to perform the |
| 2250 | 250 same functionality is the use of a library in the form of an object file. |
| 2265 | 251 These object files reside in the file system and are loaded, executed and |
| 2250 | 252 unloaded on demand.</para> |
| 253 | |
| 254 <para>Yet a third way is the use of a scripting language. Since full fledged | |
| 255 implementation of the most popular scripting languages such as Python or Perl | |
| 256 are too large for most embedded systems, a slim down implementation of tcl | |
| 257 was chosen for this server. Most of the tcl functionality is still there, | |
| 258 and makes writing cgi a lot easier.</para> | |
| 259 | |
| 260 <para>In order to limit the footprint of the operating system support for both | |
| 2265 | 261 the objloader and the tcl script for dealing with cgi files can be |
| 262 independently selected out. Tcl support in particular increases the memory | |
| 263 requirements considerably. | |
| 2250 | 264 </para> |
| 265 | |
| 266 <sect2 id="athttpd-cgi-objloader"> | |
| 267 <title>CGI via objloader</title> | |
| 268 <para> | |
| 2265 | 269 In order to use the cgi mechanism the CYGPKG_OBJLOADER must be included |
| 2250 | 270 when building the operating system. This will enable the proper option in the |
| 2265 | 271 configuration tool and if selected, the necessary code will be compiled |
| 272 in the eCos kernel. The user will then have to compile the necessary libraries | |
| 273 and place them in the file system under a directory defined by | |
| 2250 | 274 CYGDAT_NET_ATHTTPD_SERVEROPT_CGIDIR. |
| 2265 | 275 When a request is made, the web server checks if the root directory of the |
| 276 requested URL is inside the CYGDAT_NET_ATHTTPD_SERVEROPT_CGIDIR directory. | |
| 277 If so, the server assumes that the user requested a cgi file and looks into the | |
| 2250 | 278 directory to see if a library by the same name is present, and if so load it |
| 2265 | 279 and tries to execute a function inside the library with the following prototype: |
| 2250 | 280 </para> |
| 281 | |
|
2446
a72554718436
* doc/athttpd.cdl: Fixed typos in doc. Return value from handler is not
jlarmour
parents:
2326
diff
changeset
|
282 <programlisting width=72>void exec_cgi(CYG_HTTPD_STATE *) |
| 2250 | 283 </programlisting> |
| 284 | |
| 285 <para> | |
|
2446
a72554718436
* doc/athttpd.cdl: Fixed typos in doc. Return value from handler is not
jlarmour
parents:
2326
diff
changeset
|
286 The pointer <command>CYG_HTTPD_STATE*</command> gives access to the socket |
| 2250 | 287 data: The user will use this pointer to access the 'outbuffer' and use it to |
| 288 copy data to send data out. | |
| 289 </para> | |
| 2265 | 290 |
| 2250 | 291 <para> |
| 292 When using the OBJLOADER package within the HTTP server a number of functions | |
| 293 are automatically added to the externals table of the OBJLOADER package. These | |
| 294 functions are likely to be used inside the library and the relocator need to | |
| 295 have a pointer to them. In order to add more functions, see the OBJLOADER | |
| 2265 | 296 documentation. The complete list of the functions automatically added is: |
| 2250 | 297 </para> |
| 298 | |
| 299 <itemizedlist> | |
| 300 <listitem><para>cyg_httpd_start_chunked()</para></listitem> | |
| 301 <listitem><para>cyg_httpd_write_chunked()</para></listitem> | |
| 302 <listitem><para>cyg_httpd_end_chunked()</para></listitem> | |
| 303 <listitem><para>cyg_httpd_write()</para></listitem> | |
| 304 <listitem><para>cyg_httpd_find_form_variable()</para></listitem> | |
| 305 <listitem><para>cyg_httpd_find_ires()</para></listitem> | |
| 306 <listitem><para>cyg_httpd_send_ires()</para></listitem> | |
| 307 <listitem><para>diag_printf()</para></listitem> | |
| 308 <listitem><para>cyg_httpd_format_header()</para></listitem> | |
| 309 <listitem><para>cyg_httpd_find_mime_string()</para></listitem> | |
| 310 </itemizedlist> | |
| 311 | |
| 2265 | 312 <para>Every time the web client issues a GET or POST request for a file with an |
| 313 extension of '.o'in the /cgi-bin directory (or whatever path the user chooses | |
| 2250 | 314 to hold the libraries) then the library by that name is loaded, run and |
| 2265 | 315 when the execution is over, it is dumped from memory. |
| 316 | |
| 2250 | 317 The library must be compiled separately, using the same toolchain used to |
| 318 compile the server and then added to the file system.</para> | |
| 2265 | 319 |
| 2250 | 320 <para>In order to reduce the footprint of the server, CGI through OBJLOADER |
| 321 can be compiled out by unchecking CYGOPT_NET_ATHTTPD_USE_CGIBIN_OBJLOADER | |
| 322 in the configuration tool.</para> | |
| 323 </sect2> | |
| 324 | |
| 325 <sect2 id="athttpd-cgi-tcl"> | |
| 326 <title>CGI via the simple tcl interpreter</title> | |
| 327 <para>A small tcl interpreter has been added to the web server, and it can | |
| 328 be used to write simple cgi scripts. The interpreter is admittedly very | |
| 329 minimal, and it is only useful for very simple applications, but it is an | |
| 330 excellent starting point for further development.</para> | |
| 331 | |
| 332 <para>In order for the scripting language to be useful, it has to access | |
| 333 the form variables passed on during the GET or POST request. Because of | |
| 334 this, all form variables registered with the CYG_HTTPD_FVAR_TABLE_ENTRY() | |
| 335 macro are accessible via tcl. For example, if we have registered a | |
| 336 form variable called foo, and during the GET request we are defining foo | |
| 337 as being "1":</para> | |
| 338 | |
| 2265 | 339 <programlisting width=72>GET /myForm.cgi?foo=1</programlisting> |
| 2250 | 340 |
|
2485
0e9d1d1df4a0
* src/jim-aio.c (JimAioHandlerCommand): GCC 4.3.1 pointed out a
asl
parents:
2449
diff
changeset
|
341 <para>then tcl will be able to access the variable foo as $foo. The data |
|
0e9d1d1df4a0
* src/jim-aio.c (JimAioHandlerCommand): GCC 4.3.1 pointed out a
asl
parents:
2449
diff
changeset
|
342 in the body of a POST request is also accessible through the use of the variable |
|
0e9d1d1df4a0
* src/jim-aio.c (JimAioHandlerCommand): GCC 4.3.1 pointed out a
asl
parents:
2449
diff
changeset
|
343 $post_data. This is useful if the data is not in "multipart/form-data" |
|
0e9d1d1df4a0
* src/jim-aio.c (JimAioHandlerCommand): GCC 4.3.1 pointed out a
asl
parents:
2449
diff
changeset
|
344 and tcl has to perform any type of processing on the data itself.</para> |
| 2250 | 345 |
| 346 <para>In order to send back a response to the client a few functions have been | |
| 347 added to the interpreter. These functions are:</para> | |
| 348 | |
| 349 <sect3 id="athttpd-start-chunked"> | |
| 350 <title>start_chunked</title> | |
| 351 <programlisting width=72>start_chunked "extension";</programlisting> | |
| 352 <para>"extension" is a string used to search the | |
| 353 table of the mime types. For example, to send back to the client an HTML file, | |
| 354 we can use: start_chunked "html"; | |
| 2265 | 355 </para> |
| 2250 | 356 </sect3> |
| 357 | |
| 358 <sect3 id="athttpd-write-chunked"> | |
| 359 <title>write_chunked</title> | |
| 360 <programlisting width=72>write_chunked content;</programlisting> | |
| 361 <para>content is a string to send back to the client. | |
| 2265 | 362 </para> |
| 2250 | 363 </sect3> |
| 364 | |
| 365 <sect3 id="athttpd-end-chunked"> | |
| 366 <title>end_chunked</title> | |
| 367 <programlisting width=72>end_chunked;</programlisting> | |
| 2265 | 368 <para>No parameters. Send back an end of frame to the client.</para> |
| 2250 | 369 </sect3> |
|
2449
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
370 |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
371 <sect3 id="athttpd-tcl-hello-world"> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
372 <title>tcl hello world example</title> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
373 <para> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
374 The following example demonstrates how to send a log file in the file |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
375 <filename>/ram/log</filename> to a web client. It replaces |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
376 newline characters with <literal><br></literal> so that it is formatted on the |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
377 browser correctly. |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
378 <programlisting width=72> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
379 start_chunked "html"; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
380 |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
381 set fp [aio.open "/ram/log" r]; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
382 $fp seek 0 end; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
383 set fsize [$fp tell]; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
384 $fp seek 0 start; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
385 set data "abcxxx"; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
386 set data [$fp read $fsize]; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
387 $fp close; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
388 set data [string map {\n <br>} $data]; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
389 |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
390 set datax ""; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
391 append datax "<html><body>" $data "</body></html>"; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
392 |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
393 write_chunked $datax; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
394 end_chunked; |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
395 </programlisting> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
396 </para> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
397 <para> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
398 The above file should exist on a filesystem |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
399 on the embedded target within its <filename class=directory>cgi-bin</filename> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
400 directory, for example as <filename>/cgi-bin/hello.tcl</filename>. Thereafter |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
401 it may be accessed at the URL |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
402 <literal>http://<replaceable>TARGET_NAME</replaceable>/cgi-bin/hello.tcl</literal>. |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
403 </para> |
|
4631139fc774
* doc/athttpd.sgml: added an example of a tcl script.
jlarmour
parents:
2446
diff
changeset
|
404 </sect3> |
| 2250 | 405 </sect2> |
| 406 </sect1> | |
| 407 | |
| 408 <sect1 id="athttpd-authentication"> | |
| 409 <title>Authentication</title> | |
| 410 <para> | |
| 411 The server supports both Basic (base64) and Digest (MD5) authentication, | |
| 412 although they have not been tested with all clients. In this implementation, | |
| 413 the contents of certain directories of the file system can be protected, such | |
| 414 that the user will be required to issue a username/password to access the | |
| 415 content of the directory.</para> | |
| 416 | |
| 417 <para>To protect a directory with a basic authentication, there is a | |
| 418 specific macro:</para> | |
| 419 | |
| 420 <programlisting> | |
| 421 CYG_HTTPD_AUTH_TABLE_ENTRY(entry, path, domain, un, pw, mode) | |
| 422 | |
| 423 entry : an identifier unique to this entry. | |
| 424 path : the path to the directory whose content must be | |
| 425 authenticated before it is sent out | |
| 426 domain : a domain identifier for this directory. | |
| 427 un : username for authentication | |
| 428 pw : password for authentication | |
| 2265 | 429 mode : CYG_HTTPD_AUTH_BASIC for base64 encoding or |
| 2250 | 430 CYG_HTTPD_AUTH_DIGEST for MD5 encoding |
| 431 </programlisting> | |
| 432 | |
| 433 <para>for example, to require basic authentication of the content of directory | |
| 2265 | 434 "/ecos/" with a username of "foo" and password "bar", the following is used: |
| 2250 | 435 </para> |
| 436 | |
| 437 <programlisting> | |
| 2265 | 438 CYG_HTTPD_AUTH_TABLE_ENTRY(hal_domain1_entry, \ |
| 439 "/ecos/", "ecos_domain", \ | |
| 440 "foo", "bar", \ | |
| 2250 | 441 CYG_HTTPD_AUTH_BASIC); |
| 442 </programlisting> | |
| 443 | |
| 2265 | 444 <para>Any request for a file in the directory /ecos/ will now trigger a |
| 2250 | 445 credential check. These credentials, once provided, are automatically sent by |
| 2265 | 446 the client for every request within the particular domain.</para> |
| 2250 | 447 |
| 2265 | 448 <para>It must be noticed that the path name set in the macro is relative to the |
| 2250 | 449 HTML document directory, CYGDAT_NET_HTTPD_SERVEROPT_HTMLDIR and it is the |
| 450 first part of the path provided by the client request (including the leading | |
| 451 slash).</para> | |
| 452 | |
| 453 <para>In order to reduce the footprint of the server, authentication | |
| 454 is not enabled by default, and so the option CYGOPT_NET_ATHTTPD_USE_AUTH must | |
| 455 be used to enable support for basic and digest authentication.</para> | |
| 456 | |
| 457 <para>The MD5 digest authentication support is implemented using the RSA | |
| 458 Data Security, Inc. MD5 Message-Digest Algorithm. Derivative works with | |
| 459 MD5 digest authentication included must be identified as "derived from the | |
| 460 RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material | |
| 461 mentioning or referencing the derived work. See the file md5.c within this | |
| 462 package for license details.</para> | |
| 463 </sect1> | |
| 464 | |
| 465 <sect1 id="athttpd-dirlist"> | |
| 466 <title>Directory Listing</title> | |
| 467 | |
| 468 <para>If the user issues a "GET" request with a URL terminating in a slash, the | |
| 469 server will try to locate one of the following index files in the directory, | |
| 470 choosing one in the following order:</para> | |
| 471 | |
| 472 <itemizedlist> | |
| 473 <listitem><para>index.html</para></listitem> | |
| 474 <listitem><para>index.htm</para></listitem> | |
| 475 <listitem><para>default.html</para></listitem> | |
| 476 <listitem><para>home.html</para></listitem> | |
| 477 </itemizedlist> | |
| 478 | |
| 479 <para>If any of these files is found, its contents are sent back | |
| 2265 | 480 to the client. If no such file is found the server uses the user-provided |
| 481 index file name (if any is specified with the CYGDAT_NET_ATHTTPD_ALTERNATE_HOME | |
| 482 setting. Failing all this a directory listing is sent.</para> | |
| 2250 | 483 |
| 484 <para>Trailing slash redirection for directory names is supported.</para> | |
| 485 | |
| 486 <para>In order to reduce the footprint of the server, directory listing can | |
| 487 be disabled by unchecking CYGOPT_NET_ATHTTPD_USE_DIRLIST. The savings are | |
| 488 substantial since directory listing also makes use of a few internal | |
| 489 resources (gif files) which are also compiled out.</para> | |
| 490 </sect1> | |
| 491 | |
| 492 <sect1 id="athttpd-formvars"> | |
| 493 <title>Form Variables</title> | |
| 494 | |
| 495 <para>The server will automatically try to parse form variables when a form is | |
| 2326 | 496 submitted in the following cases: |
| 497 | |
| 498 <itemizedlist> | |
| 499 <listitem><para>In a GET request, when the URL is followed by a question | |
| 500 mark sign</para></listitem> | |
| 501 <listitem><para>In a POST request, when the the 'Content-Type' header line | |
| 502 is set to 'application/x-www-form-urlencoded'</para></listitem> | |
| 503 </itemizedlist> | |
| 504 | |
| 505 The variable names to look for during the parsing are held in | |
| 2250 | 506 an eCos table. In order to take advantage of this feature, the user first |
| 2326 | 507 adds the variable names to the table, which also requires providing a buffer |
| 508 where the parsed value will eventually be stored. The values will then be | |
| 509 available in the buffers during the processing of the request, presumably in | |
| 510 the body of a c language callback or CGI script.</para> | |
| 2250 | 511 |
| 512 <para>For example, if the user wants two form variables, "foo" and "bar", to | |
| 513 be parsed automatically, those variable names must be added to the table | |
| 514 with the following macro:</para> | |
| 515 | |
| 516 <programlisting> | |
| 517 CYG_HTTPD_FVAR_TABLE_ENTRY(entry, name, buffp, bufflen) | |
| 518 | |
| 519 entry : an identifier unique to this entry. | |
| 520 name : name of the form variable | |
| 521 buffp : a pointer to a buffer of characters where to store the value | |
| 522 of the form variable. | |
| 523 bufflen : The length of the buffer. Must include a trailing string | |
| 524 terminator. | |
| 525 </programlisting> | |
| 526 | |
| 527 <para>or, in the specific instance mentioned above:</para> | |
| 528 | |
| 529 <programlisting> | |
| 2265 | 530 #define HTML_VAR_LEN 20 |
| 531 char var_foo[HTML_VAR_LEN]; | |
| 532 char var_bar[HTML_VAR_LEN]; | |
| 533 CYG_HTTPD_FVAR_TABLE_ENTRY(hal_form_entry_foo, "foo", var_foo, HTML_VAR_LEN); | |
| 534 CYG_HTTPD_FVAR_TABLE_ENTRY(hal_form_entry_bar, "bar", var_bar, HTML_VAR_LEN); | |
| 2250 | 535 </programlisting> |
| 536 | |
| 537 <para>and after the GET or POST submissions, the list will contain the value | |
| 538 for "foo" and "bar" (if they were found in the form data.) It is the | |
| 539 responsability of the user to make sure that the buffer is large enough | |
| 540 to hold all the data parsed (including the string terminator). The parser will | |
| 541 write only up to the length of the buffer minus one (the last being the | |
| 2326 | 542 terminator) and discard any additional data.</para> |
| 2250 | 543 |
| 544 <para>The values parsed are likely going to be used in c language callback, or | |
| 2326 | 545 in CGI files. In a c language callback the user can directly access the pointers |
| 546 of individual variables for further processing, keeping in mind that the parsing | |
| 547 always result in a string of characters to be produced, and any conversion | |
| 548 (e.g. from strings to integer) must be performed within the callback. In | |
| 549 a TCL script the user can just access a variable by its name. For example, | |
| 550 in the case of the variables 'foo' and 'bar' shown above, it is possible | |
| 551 to do something like 'write_chunked "You wrote $foo". The data that was sent in | |
| 552 the body of a POST request is accessible in through a variable called | |
| 553 'post_data'. In CGI functions | |
| 554 implemented using the objloader the pointers to the | |
| 2250 | 555 variables cannot be accessed directly, since the library will likely not |
| 556 know their location in memory. The proper way to access them is by using the | |
| 2326 | 557 cyg_httpd_find_form_variable() function from within the library:</para> |
| 2250 | 558 |
| 559 <programlisting> | |
| 560 char* cyg_httpd_find_form_variable(char* name) | |
| 561 | |
| 562 name : name of the form variable to look up | |
| 563 | |
| 564 returns a pointer to the buffer, or 0 if the variable was not found. | |
| 565 </programlisting> | |
| 566 | |
| 2265 | 567 <para>When using the OBJLOADER package within the web server, an entry |
| 568 for the cyg_httpd_find_form_variable() function is automatically added to the | |
| 569 externals table the OBJLOADER for relocation. See the OBLOADER paragraph of | |
| 570 the ATHTTP user's guide for the full list of the exported functions.</para> | |
| 571 | |
| 572 <para>In order to avoid stale data, all the buffers in the table are cleared | |
| 573 before running the parser and thus any variable in the list that was not | |
| 574 assigned a new value dureing the request will be an empty string.</para> | |
| 2250 | 575 </sect1> |
| 576 | |
| 577 <sect1 id="athttpd-ires"> | |
| 578 <title>Internal Resources</title> | |
| 579 | |
| 580 <para>When the server does not use a file system the user must be responsible | |
| 581 to provide a C language callback function for each URL that will be | |
| 582 requested by the client. This means locating the data and sending it out | |
| 583 using either <command>cyg_httpd_write()</command> or | |
| 584 <command>cyg_httpd_write_chunked()</command>.</para> | |
| 585 | |
| 586 <para>In order to simplify this process the server allows registering | |
| 2265 | 587 any number of URLs as internal resources, by providing the URL name, the |
| 2250 | 588 pointer to the resource data and its size. When a URL is requested the |
| 589 server will look it up among all internal resources, and if found, it | |
| 590 will send out the resource.</para> | |
| 591 | |
| 592 <para>Internal resource can also be used along with a file system. In this | |
| 593 case the file system is searched first, and if a file is found, it it | |
| 594 sent. If a file is not found, the internal resources are searched and | |
| 595 if a match if found it is sent.</para> | |
| 596 | |
| 597 <para>The drawback of this approach is, of course, that all these | |
| 598 resources are going to add to the size of the operating system image, and thus | |
| 599 it should be used only when memory is not a major constraint of the | |
| 600 design.</para> | |
| 601 | |
| 602 <para>As always, to provide this type of customization, ecos tables are used. | |
| 603 The format for adding a new resource to the internal table is the following: | |
| 604 </para> | |
| 605 | |
| 606 <programlisting> | |
| 607 CYG_HTTPD_IRES_TABLE_ENTRY(entry, name, buffp, len) | |
| 608 | |
| 609 entry : an identifier unique to this entry. | |
| 610 name : name of the URL including leading '/' | |
| 611 buffp : a pointer to a buffer of characters where to store the value | |
| 612 of the form variable. | |
| 613 len : size of the array | |
| 614 </programlisting> | |
| 615 | |
| 616 <para>As an example, if the user wants to provide his own web page by | |
| 617 hardcoding it in the application code, here is how he would do it:</para> | |
| 618 | |
| 619 <programlisting> | |
| 620 #define MY_OWN_HOME_PAGE "eCos RTOS" | |
| 621 CYG_HTTPD_IRES_TABLE_ENTRY(cyg_httpd_ires_home, \ | |
| 622 "/index.html", \ | |
| 623 MY_OWN_HOME_PAGE, \ | |
| 624 9); | |
| 625 </programlisting> | |
| 626 | |
| 627 <para>The extension of the file name determines the MIME type to be used for | |
| 628 internal resources.</para> | |
| 629 | |
| 630 <para>When using directory listing you are implicitly making use of internal | |
| 631 resources. The small icons that appear to the left of file names and | |
| 632 directories are internal resources. Unchecking CYGOPT_NET_HTTP_USE_DIRLIST | |
| 633 will prevent the addition of these files.</para> | |
| 634 | |
| 635 <para>In order to use internal resources, a generic file must first be | |
| 636 turned into a c language array, which is then compiled in the application | |
| 637 code. To create this array you can use the tcl script that comes with the | |
| 638 ecos distribution at packages/fs/rom/current/support/file2.tcl.</para> | |
| 639 </sect1> | |
| 640 </chapter> | |
| 641 </part> |