|
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(); |
|
|
69 </programlisting> |
|
|
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 |
|
|
78 <sect1 id="athttpd-callback"> |
|
|
79 <title>C language callback functions</title> |
|
|
80 <para> |
|
|
81 The server allows the association of particular URLs to C language callback |
|
|
82 functions. Tables are again used for the association. The syntax of the macro |
|
|
83 to add callback entries to the table is: |
|
|
84 </para> |
|
|
85 |
|
|
86 <para><programlisting width=72> |
|
|
87 CYG_HTTPD_HANDLER_TABLE_ENTRY(entry_label, url_string, callback); |
|
|
88 |
|
|
89 entry table : an identifier unique to this entry. |
|
|
90 url_string : a string with the extension url that will be appended to the |
|
|
91 default directory. |
|
|
92 callback : a function with a prototype: |
|
|
93 cyg_int32 callback_function(CYG_HTTPS_STATE*); |
|
|
94 </programlisting></para> |
|
|
95 |
|
|
96 <para> |
|
|
97 <command>CYG_HTTPS_STATE*</command> is a pointer to a structure that |
|
|
98 contains, among others, a buffer (outbuffer) that can be used to send data |
|
|
99 out. The definitions of the structure is in http.h.</para> |
|
|
100 |
|
|
101 <para> |
|
|
102 If the callback function returns the value of 0, the server will try to find |
|
|
103 the file with the same URL in the file system and send it. Any other value |
|
|
104 returned causes the sever to stop further processing of this request. It is |
|
|
105 assumed that in this case the user has send the response back to the client |
|
|
106 inside the body of the callback function. |
|
|
107 |
|
|
108 The following is an example of how to add a callback to a function myForm() |
|
|
109 whenever the /myform.gci is called. |
|
|
110 </para> |
|
|
111 |
|
|
112 <programlisting width=72> |
|
|
113 CYG_HTTPD_HANDLER_TABLE_ENTRY( hal_cb_entry, "/myform.cgi", myForm ); |
|
|
114 </programlisting> |
|
|
115 |
|
|
116 <para> |
|
|
117 and somewhere in the source tree there is a function:</para> |
|
|
118 |
|
|
119 <programlisting> |
|
|
120 cyg_int32 myForm(CYG_HTTPS_STATE* p) |
|
|
121 { |
|
|
122 cyg_httpd_start_chunked("html"); |
|
|
123 strcpy(p->outbuffer, "eCos Web Server"); |
|
|
124 cyg_httpd_write_chunked(p->outbuffer, strlen(p->outbuffer)) |
|
|
125 cyg_httpd_end_chunked(); |
|
|
126 return -1; // Do not further search the file system. |
|
|
127 } |
|
|
128 </programlisting> |
|
|
129 |
|
|
130 <para>This function also shows the correct method of using the chunked frames |
|
|
131 API inside a c language callback and also shows the use of outbuffer to |
|
|
132 collect data to send out.</para> |
|
|
133 |
|
|
134 <para>Chunked frames are useful when the size of the frame is not known upfront. |
|
|
135 In this case it possible to send a response in chunks of various sizes, and |
|
|
136 terminate it with a null chunk. See RFC 2616 for details. To use chunked |
|
|
137 frames, the <command>cyg_httpd_start_chunked()</command> function is used. |
|
|
138 The prototype is the following:</para> |
|
|
139 |
|
|
140 <programlisting> |
|
|
141 ssize_t cyg_httpd_start_chunked(char *); |
|
|
142 </programlisting> |
|
|
143 |
|
|
144 <para>The only parameter is the <command>extension</command> to use in the |
|
|
145 search for the MIME type. For most files this will be "html" or "htm" and |
|
|
146 it will be searched in the MIME table for an approriate MIME type that will |
|
|
147 be sent along in the header. The function returns the number of bytes sent |
|
|
148 out.</para> |
|
|
149 |
|
|
150 <para>The chunked frame must be terminated by a call to |
|
|
151 <command>cyg_httpd_end_chunked()</command>:</para> |
|
|
152 |
|
|
153 <programlisting> |
|
|
154 void cyg_httpd_end_chunked()(void); |
|
|
155 </programlisting> |
|
|
156 |
|
|
157 <para>In between these two calls, the user can call the function |
|
|
158 <command>cyg_httpd_write_chunked()</command> to send out data, any number of |
|
|
159 times. It is important that <command>cyg_httpd_write_chunked()</command> be |
|
|
160 the only function used to send data out for chunked frames. This |
|
|
161 guarantees that proper formatting of the response is respected. |
|
|
162 The prototype for the function is:</para> |
|
|
163 |
|
|
164 <programlisting> |
|
|
165 ssize_t cyg_httpd_write_chunked(char* p, int len); |
|
|
166 </programlisting> |
|
|
167 |
|
|
168 <para>The 'char*' points to the data to send out, the 'int' is the length of the |
|
|
169 data to send.</para> |
|
|
170 |
|
|
171 <para>In the case in which the size of the data is known upfront, the |
|
|
172 callback can instead create the header with a call to |
|
|
173 <command>cyg_httpd_create_std_header()</command> with the following |
|
|
174 prototype:</para> |
|
|
175 |
|
|
176 <programlisting> |
|
|
177 void cyg_httpd_create_std_header(char *ext, int len); |
|
|
178 |
|
|
179 extension : the extension used in the search of the MIME type |
|
|
180 len : length of the data to send out |
|
|
181 </programlisting> |
|
|
182 |
|
|
183 <para>and |
|
|
184 <command>cyg_httpd_write</command>, the prototype of which is the same |
|
|
185 as <command>cyg_httpd_write_chunked()</command></para> |
|
|
186 </sect1> |
|
|
187 |
|
|
188 <sect1 id="athttpd-mime_types"> |
|
|
189 <title>MIME types</title> |
|
|
190 <para> |
|
|
191 The server has an internal table with all the recognized mime types. Each time |
|
|
192 a file or an internal resource is sent out by the server, its extension is |
|
|
193 searched in this table and if a match is found, the associated MIME type is |
|
|
194 then sent out in the header. |
|
|
195 |
|
|
196 The server already provides entries for the following standard file extensions: |
|
|
197 |
|
|
198 'html', 'htm', 'gif', 'jpg', 'css', 'js' |
|
|
199 |
|
|
200 and the user can add further enties entries to the table. The syntax for |
|
|
201 adding an entry is the following:</para> |
|
|
202 |
|
|
203 <para><programlisting width=72> |
|
|
204 CYG_HTTPD_MIME_TABLE_ENTRY(entry_label, extension_string, mime_tipe_sting); |
|
|
205 |
|
|
206 entry table : an identifier unique to this entry |
|
|
207 extension string : a string containing the extension for this entry |
|
|
208 type_string : the mime string. The strings for many more mime types |
|
|
209 is included in a file in the "doc" directory. |
|
|
210 </programlisting></para> |
|
|
211 |
|
|
212 <para> |
|
|
213 The following is an example of how to add the Adobe Portable Document Format |
|
|
214 <command>pdf</command> MIME type to the table:</para> |
|
|
215 |
|
|
216 <para><programlisting width=72> |
|
|
217 CYG_HTTPD_MIME_TABLE_ENTRY(hal_pdf_entry, "pdf", "application/pdf"); |
|
|
218 </programlisting></para> |
|
|
219 |
|
|
220 <sect2 id="athttpd-mime_types-chunked"> |
|
|
221 <title>MIME Types for Chunked Frames</title> |
|
|
222 <para> |
|
|
223 For chunked frames, which are generally used inside c language callbacks, there |
|
|
224 is no file name to match an extension to, and thus the extension to be used |
|
|
225 must be passed in the <command>cyg_httpd_start_chunked()</command> call. The |
|
|
226 server will then scan the MIME table to find a MIME type to match the extension. |
|
|
227 |
|
|
228 For example, to start a chunked transfer of an <command>html</command> file, |
|
|
229 the following call is used:</para> |
|
|
230 |
|
|
231 <para><programlisting width=72> |
|
|
232 cyg_httpd_start_chunked("html"); |
|
|
233 </programlisting></para> |
|
|
234 |
|
|
235 <para> |
|
|
236 In any event, it is the responsibility of the user to make sure that a match to |
|
|
237 all used extensions is found in the table search. Failing this, |
|
|
238 the default MIME type specified in the CYGDAT_NET_ATHTTPD_DEFAULT_MIME_TYPE |
|
|
239 string is returned.</para> |
|
|
240 </sect2> |
|
|
241 </sect1> |
|
|
242 |
|
|
243 <sect1 id="athttpd-cgi"> |
|
|
244 <title>CGI</title> |
|
|
245 <para> |
|
|
246 The web server allows writing of pseudo-CGI programs. This is helpful in order |
|
|
247 to modify the functionality of the server without having to recompile it and |
|
|
248 reflash it.</para> |
|
|
249 |
|
|
250 <para>One way to implement CGI is, of course, the C language callback mechanism |
|
|
251 described above: This assumes, of course, that all the callbacks are written |
|
|
252 at compile time and cannot be modified later on. Another way to perform the |
|
|
253 same functionality is the use of a library in the form of an object file. |
|
|
254 These object files reside in the file system, and are loaded, executed and |
|
|
255 unloaded on demand.</para> |
|
|
256 |
|
|
257 <para>Yet a third way is the use of a scripting language. Since full fledged |
|
|
258 implementation of the most popular scripting languages such as Python or Perl |
|
|
259 are too large for most embedded systems, a slim down implementation of tcl |
|
|
260 was chosen for this server. Most of the tcl functionality is still there, |
|
|
261 and makes writing cgi a lot easier.</para> |
|
|
262 |
|
|
263 <para>In order to limit the footprint of the operating system support for both |
|
|
264 the objloader and the tcl script for dealing with cgi files can be selected |
|
|
265 out. Tcl support in particular increases the memory requirements considerably. |
|
|
266 </para> |
|
|
267 |
|
|
268 <sect2 id="athttpd-cgi-objloader"> |
|
|
269 <title>CGI via objloader</title> |
|
|
270 <para> |
|
|
271 In order to use the cgi mechanism the CYGPKG_OBJLOADER must be included |
|
|
272 when building the operating system. This will enable the proper option in the |
|
|
273 configuration tool, and if selected, the necessary code will be compiled |
|
|
274 in the OS kernel. The user will then have to compile a library and place it |
|
|
275 in the file system under a directory defined by |
|
|
276 CYGDAT_NET_ATHTTPD_SERVEROPT_CGIDIR. |
|
|
277 When a request is made to the server, the web server looks into the |
|
|
278 directory to see if a library by the same name is present, and if so load it |
|
|
279 and tries to execute a library function with the following prototype: |
|
|
280 </para> |
|
|
281 |
|
|
282 <programlisting width=72>void exec_cgi(CYG_HTTPS_STATE *) |
|
|
283 </programlisting> |
|
|
284 |
|
|
285 <para> |
|
|
286 The pointer <command>CYG_HTTPS_STATE*</command> gives access to the socket |
|
|
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> |
|
|
290 |
|
|
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 |
|
|
296 documentation. The complete list of the functions automatically added is: |
|
|
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 |
|
|
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 |
|
|
314 to hold the libraries) then the library by that name is loaded, run and |
|
|
315 when the execution is over, it is dumped from memory. |
|
|
316 |
|
|
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> |
|
|
319 |
|
|
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 |
|
|
339 <programlisting width=72>GET /myForm.gci?foo=1</programlisting> |
|
|
340 |
|
|
341 <para>then tcl will be able to access the variable foo as $foo.</para> |
|
|
342 |
|
|
343 <para>In order to send back a response to the client a few functions have been |
|
|
344 added to the interpreter. These functions are:</para> |
|
|
345 |
|
|
346 <sect3 id="athttpd-start-chunked"> |
|
|
347 <title>start_chunked</title> |
|
|
348 <programlisting width=72>start_chunked "extension";</programlisting> |
|
|
349 <para>"extension" is a string used to search the |
|
|
350 table of the mime types. For example, to send back to the client an HTML file, |
|
|
351 we can use: start_chunked "html"; |
|
|
352 </para> |
|
|
353 </sect3> |
|
|
354 |
|
|
355 <sect3 id="athttpd-write-chunked"> |
|
|
356 <title>write_chunked</title> |
|
|
357 <programlisting width=72>write_chunked content;</programlisting> |
|
|
358 <para>content is a string to send back to the client. |
|
|
359 </para> |
|
|
360 </sect3> |
|
|
361 |
|
|
362 <sect3 id="athttpd-end-chunked"> |
|
|
363 <title>end_chunked</title> |
|
|
364 <programlisting width=72>end_chunked;</programlisting> |
|
|
365 <para>No parameters. Send back an end of frame to the client.</para> |
|
|
366 </sect3> |
|
|
367 </sect2> |
|
|
368 </sect1> |
|
|
369 |
|
|
370 <sect1 id="athttpd-authentication"> |
|
|
371 <title>Authentication</title> |
|
|
372 <para> |
|
|
373 The server supports both Basic (base64) and Digest (MD5) authentication, |
|
|
374 although they have not been tested with all clients. In this implementation, |
|
|
375 the contents of certain directories of the file system can be protected, such |
|
|
376 that the user will be required to issue a username/password to access the |
|
|
377 content of the directory.</para> |
|
|
378 |
|
|
379 <para>To protect a directory with a basic authentication, there is a |
|
|
380 specific macro:</para> |
|
|
381 |
|
|
382 <programlisting> |
|
|
383 CYG_HTTPD_AUTH_TABLE_ENTRY(entry, path, domain, un, pw, mode) |
|
|
384 |
|
|
385 entry : an identifier unique to this entry. |
|
|
386 path : the path to the directory whose content must be |
|
|
387 authenticated before it is sent out |
|
|
388 domain : a domain identifier for this directory. |
|
|
389 un : username for authentication |
|
|
390 pw : password for authentication |
|
|
391 mode : CYG_HTTPD_AUTH_BASIC fpr base64 encoding or |
|
|
392 CYG_HTTPD_AUTH_DIGEST for MD5 encoding |
|
|
393 </programlisting> |
|
|
394 |
|
|
395 <para>for example, to require basic authentication of the content of directory |
|
|
396 "/foo/" with a username of 'ecos' and password "bar", the following is used: |
|
|
397 </para> |
|
|
398 |
|
|
399 <programlisting> |
|
|
400 CYG_HTTPD_AUTH_TABLE_ENTRY(hal_domain1_entry, \ |
|
|
401 "/foo/", "foo_domain", \ |
|
|
402 "ecos", "bar", \ |
|
|
403 CYG_HTTPD_AUTH_BASIC); |
|
|
404 </programlisting> |
|
|
405 |
|
|
406 <para>Any request for a file in the directory /foo/ will now trigger a |
|
|
407 credential check. These credentials, once provided, are automatically sent by |
|
|
408 the client for every request wihtin the particular domain.</para> |
|
|
409 |
|
|
410 <para>It must be notice that the path name set in the macro is relative to the |
|
|
411 HTML document directory, CYGDAT_NET_HTTPD_SERVEROPT_HTMLDIR and it is the |
|
|
412 first part of the path provided by the client request (including the leading |
|
|
413 slash).</para> |
|
|
414 |
|
|
415 <para>In order to reduce the footprint of the server, authentication |
|
|
416 is not enabled by default, and so the option CYGOPT_NET_ATHTTPD_USE_AUTH must |
|
|
417 be used to enable support for basic and digest authentication.</para> |
|
|
418 |
|
|
419 <para>The MD5 digest authentication support is implemented using the RSA |
|
|
420 Data Security, Inc. MD5 Message-Digest Algorithm. Derivative works with |
|
|
421 MD5 digest authentication included must be identified as "derived from the |
|
|
422 RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material |
|
|
423 mentioning or referencing the derived work. See the file md5.c within this |
|
|
424 package for license details.</para> |
|
|
425 </sect1> |
|
|
426 |
|
|
427 <sect1 id="athttpd-dirlist"> |
|
|
428 <title>Directory Listing</title> |
|
|
429 |
|
|
430 <para>If the user issues a "GET" request with a URL terminating in a slash, the |
|
|
431 server will try to locate one of the following index files in the directory, |
|
|
432 choosing one in the following order:</para> |
|
|
433 |
|
|
434 <itemizedlist> |
|
|
435 <listitem><para>index.html</para></listitem> |
|
|
436 <listitem><para>index.htm</para></listitem> |
|
|
437 <listitem><para>default.html</para></listitem> |
|
|
438 <listitem><para>home.html</para></listitem> |
|
|
439 </itemizedlist> |
|
|
440 |
|
|
441 <para>If any of these files is found, its contents are sent back |
|
|
442 to the client. If no such file is found a directory listing is sent.</para> |
|
|
443 |
|
|
444 <para>Trailing slash redirection for directory names is supported.</para> |
|
|
445 |
|
|
446 <para>In order to reduce the footprint of the server, directory listing can |
|
|
447 be disabled by unchecking CYGOPT_NET_ATHTTPD_USE_DIRLIST. The savings are |
|
|
448 substantial since directory listing also makes use of a few internal |
|
|
449 resources (gif files) which are also compiled out.</para> |
|
|
450 </sect1> |
|
|
451 |
|
|
452 <sect1 id="athttpd-formvars"> |
|
|
453 <title>Form Variables</title> |
|
|
454 |
|
|
455 <para>The server will automatically try to parse form variables when a form is |
|
|
456 submitted.The variable names to look for during the parsing are held in |
|
|
457 an eCos table. In order to take advantage of this feature, the user first |
|
|
458 adds the variable names to the table, also providing a buffer where the parsed |
|
|
459 value will eventually be stored. The values will then be available in |
|
|
460 the buffers during the processing of the request, presumably in the body |
|
|
461 of a c language callback.</para> |
|
|
462 |
|
|
463 <para>For example, if the user wants two form variables, "foo" and "bar", to |
|
|
464 be parsed automatically, those variable names must be added to the table |
|
|
465 with the following macro:</para> |
|
|
466 |
|
|
467 <programlisting> |
|
|
468 CYG_HTTPD_FVAR_TABLE_ENTRY(entry, name, buffp, bufflen) |
|
|
469 |
|
|
470 entry : an identifier unique to this entry. |
|
|
471 name : name of the form variable |
|
|
472 buffp : a pointer to a buffer of characters where to store the value |
|
|
473 of the form variable. |
|
|
474 bufflen : The length of the buffer. Must include a trailing string |
|
|
475 terminator. |
|
|
476 </programlisting> |
|
|
477 |
|
|
478 <para>or, in the specific instance mentioned above:</para> |
|
|
479 |
|
|
480 <programlisting> |
|
|
481 char var_foo[20]; |
|
|
482 char var_bar[20]; |
|
|
483 CYG_HTTPD_FVAR_TABLE_ENTRY(hal_form_entry_foo, "foo", var_foo, 20); |
|
|
484 CYG_HTTPD_FVAR_TABLE_ENTRY(hal_form_entry_bar, "bar", var_bar, 20); |
|
|
485 </programlisting> |
|
|
486 |
|
|
487 <para>and after the GET or POST submissions, the list will contain the value |
|
|
488 for "foo" and "bar" (if they were found in the form data.) It is the |
|
|
489 responsability of the user to make sure that the buffer is large enough |
|
|
490 to hold all the data parsed (including the string terminator). The parser will |
|
|
491 write only up to the length of the buffer minus one (the last being the |
|
|
492 terminator).</para> |
|
|
493 |
|
|
494 <para>The values parsed are likely going to be used in c language callback, or |
|
|
495 in CGI files. The user can access the pointers of individual variable |
|
|
496 for further processing, keeping in mind that the parsing always result |
|
|
497 in a string of characters to be produced, and any conversion from strings to |
|
|
498 integer (i.e. atoi()) must be performed in the callback.</para> |
|
|
499 |
|
|
500 <para>In order to avoid stale data, all the buffers in the table are cleared |
|
|
501 before running the parser and thus any variable in the list that was not |
|
|
502 assigned a new value will be an empty string.</para> |
|
|
503 |
|
|
504 <para>In CGI functions implemented using the objloader the pointers to the |
|
|
505 variables cannot be accessed directly, since the library will likely not |
|
|
506 know their location in memory. The proper way to access them is by using the |
|
|
507 cyg_httpd_find_form_variable() function:</para> |
|
|
508 |
|
|
509 <programlisting> |
|
|
510 char* cyg_httpd_find_form_variable(char* name) |
|
|
511 |
|
|
512 name : name of the form variable to look up |
|
|
513 |
|
|
514 returns a pointer to the buffer, or 0 if the variable was not found. |
|
|
515 </programlisting> |
|
|
516 |
|
|
517 <para>When using the OBJLOADER package within the web server, a |
|
|
518 pointer to this function is automatically added to the externals table the |
|
|
519 OBJLOADER for relocation. See the OBLOADER paragraph of the ATHTTP user's |
|
|
520 guide for the full list of the exported functions.</para> |
|
|
521 </sect1> |
|
|
522 |
|
|
523 <sect1 id="athttpd-ires"> |
|
|
524 <title>Internal Resources</title> |
|
|
525 |
|
|
526 <para>When the server does not use a file system the user must be responsible |
|
|
527 to provide a C language callback function for each URL that will be |
|
|
528 requested by the client. This means locating the data and sending it out |
|
|
529 using either <command>cyg_httpd_write()</command> or |
|
|
530 <command>cyg_httpd_write_chunked()</command>.</para> |
|
|
531 |
|
|
532 <para>In order to simplify this process the server allows registering |
|
|
533 any number of URLs inside internal resources, by providing the URL name, the |
|
|
534 pointer to the resource data and its size. When a URL is requested the |
|
|
535 server will look it up among all internal resources, and if found, it |
|
|
536 will send out the resource.</para> |
|
|
537 |
|
|
538 <para>Internal resource can also be used along with a file system. In this |
|
|
539 case the file system is searched first, and if a file is found, it it |
|
|
540 sent. If a file is not found, the internal resources are searched and |
|
|
541 if a match if found it is sent.</para> |
|
|
542 |
|
|
543 <para>The drawback of this approach is, of course, that all these |
|
|
544 resources are going to add to the size of the operating system image, and thus |
|
|
545 it should be used only when memory is not a major constraint of the |
|
|
546 design.</para> |
|
|
547 |
|
|
548 <para>As always, to provide this type of customization, ecos tables are used. |
|
|
549 The format for adding a new resource to the internal table is the following: |
|
|
550 </para> |
|
|
551 |
|
|
552 <programlisting> |
|
|
553 CYG_HTTPD_IRES_TABLE_ENTRY(entry, name, buffp, len) |
|
|
554 |
|
|
555 entry : an identifier unique to this entry. |
|
|
556 name : name of the URL including leading '/' |
|
|
557 buffp : a pointer to a buffer of characters where to store the value |
|
|
558 of the form variable. |
|
|
559 len : size of the array |
|
|
560 </programlisting> |
|
|
561 |
|
|
562 <para>As an example, if the user wants to provide his own web page by |
|
|
563 hardcoding it in the application code, here is how he would do it:</para> |
|
|
564 |
|
|
565 <programlisting> |
|
|
566 #define MY_OWN_HOME_PAGE "eCos RTOS" |
|
|
567 CYG_HTTPD_IRES_TABLE_ENTRY(cyg_httpd_ires_home, \ |
|
|
568 "/index.html", \ |
|
|
569 MY_OWN_HOME_PAGE, \ |
|
|
570 9); |
|
|
571 </programlisting> |
|
|
572 |
|
|
573 <para>The extension of the file name determines the MIME type to be used for |
|
|
574 internal resources.</para> |
|
|
575 |
|
|
576 <para>When using directory listing you are implicitly making use of internal |
|
|
577 resources. The small icons that appear to the left of file names and |
|
|
578 directories are internal resources. Unchecking CYGOPT_NET_HTTP_USE_DIRLIST |
|
|
579 will prevent the addition of these files.</para> |
|
|
580 |
|
|
581 <para>In order to use internal resources, a generic file must first be |
|
|
582 turned into a c language array, which is then compiled in the application |
|
|
583 code. To create this array you can use the tcl script that comes with the |
|
|
584 ecos distribution at packages/fs/rom/current/support/file2.tcl.</para> |
|
|
585 </sect1> |
|
|
586 </chapter> |
|
|
587 </part> |
