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