Mercurial > ecos
annotate packages/net/httpd/current/doc/httpd.sgml @ 2967:a98ace8abb52
* bsd_tcpip/current/doc/freebsd.sgml, tcpip/current/doc/openbsd.sgml:
No longer "recent".
* httpd/current/doc/httpd.sgml: Fix GoAhead URL.
| author | jld |
|---|---|
| date | Sat, 18 Sep 2010 16:10:32 +0000 |
| parents | 74dbf4c3f2e1 |
| children |
| rev | line source |
|---|---|
| 468 | 1 |
| 2 <!-- =============================================================== --> | |
| 3 <!-- --> | |
| 4 <!-- httpd.sgml --> | |
| 5 <!-- --> | |
| 6 <!-- eCos HTTP Server --> | |
| 7 <!-- --> | |
| 8 <!-- =============================================================== --> | |
|
2729
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
1535
diff
changeset
|
9 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> |
| 468 | 10 <!-- =============================================================== --> |
|
2967
a98ace8abb52
* bsd_tcpip/current/doc/freebsd.sgml, tcpip/current/doc/openbsd.sgml:
jld
parents:
2729
diff
changeset
|
11 <!-- Copyright (C) 2002, 2010 Free Software Foundation, Inc. --> |
| 468 | 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 <!-- Distribution of the work or derivative of the work in any --> | |
| 17 <!-- standard (paper) book form is prohibited unless prior --> | |
| 18 <!-- permission obtained from the copyright holder --> | |
| 19 <!-- =============================================================== --> | |
|
2729
74dbf4c3f2e1
Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents:
1535
diff
changeset
|
20 <!-- ####ECOSDOCCOPYRIGHTEND#### --> |
| 468 | 21 <!-- =============================================================== --> |
| 22 <!-- #####DESCRIPTIONBEGIN#### --> | |
| 23 <!-- --> | |
| 24 <!-- ####DESCRIPTIONEND#### --> | |
| 25 <!-- =============================================================== --> | |
| 26 | |
| 27 <part id="net-httpd"> | |
| 28 <title>Embedded HTTP Server</title> | |
| 29 <chapter id="net-httpd-chapter"> | |
| 30 <title>Embedded HTTP Server</title> | |
| 31 | |
| 32 <sect1 id="net-httpd-intro"> | |
| 33 <title>Intrduction</title> | |
| 34 <para> | |
| 35 The <emphasis>eCos</emphasis> HTTPD package provides a simple HTTP | |
| 36 server for use with applications in eCos. This server is specifically | |
| 37 aimed at the remote control and monitoring requirements of embedded | |
| 38 applications. For this reason the emphasis is on dynamically generated | |
| 39 content, simple forms handling and a basic CGI interface. It is | |
| 40 <emphasis>not</emphasis> intended to be a general purpose server for | |
| 41 delivering arbitrary web content. For these purposes a port of the | |
| 42 GoAhead web server is available from <ulink | |
|
2967
a98ace8abb52
* bsd_tcpip/current/doc/freebsd.sgml, tcpip/current/doc/openbsd.sgml:
jld
parents:
2729
diff
changeset
|
43 url="http://www.goahead.com">www.goahead.com</ulink>. |
| 468 | 44 </para> |
|
1008
4ca8a5f30c03
* src/monitor.c (cyg_monitor_network): Added IPv6 information to
asl
parents:
468
diff
changeset
|
45 <para>This server is also capable of serving content using IPv6 when |
|
4ca8a5f30c03
* src/monitor.c (cyg_monitor_network): Added IPv6 information to
asl
parents:
468
diff
changeset
|
46 the eCos configuration contains IPv6. |
|
4ca8a5f30c03
* src/monitor.c (cyg_monitor_network): Added IPv6 information to
asl
parents:
468
diff
changeset
|
47 </para> |
| 468 | 48 </sect1> |
| 49 | |
| 50 <sect1 id="net-httpd-organization"> | |
| 51 <title>Server Organization</title> | |
| 52 <para> | |
| 53 The server consists of one or more threads running in parallel to any | |
| 54 application threads and which serve web pages to clients. Apart from | |
| 55 defining content, the application does not need to do anything to | |
| 56 start the HTTP server. | |
| 57 </para> | |
| 58 <para> | |
|
1535
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
59 The HTTP server is, by default, started by a static constructor. This |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
60 simply creates an initial thread and sets it running. Since this is |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
61 called before the scheduler is started, nothing will happen until the |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
62 application calls <function>cyg_scheduler_start()</function>. The |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
63 server thread can also be started explicitly by the application, see |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
64 the <literal>CYGNUM_HTTPD_SERVER_AUTO_START</literal> option for |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
65 details. |
| 468 | 66 </para> |
| 67 <para> | |
| 68 When the thread gets to run it first optionally delays for some period | |
| 69 of time. This is to allow the application to perform any | |
| 70 initialization free of any interference from the HTTP server. When the | |
| 71 thread does finally run it creates a socket, binds it to the HTTP | |
| 72 server port, and puts it into listen mode. It will then create any | |
| 73 additional HTTPD server threads that have been configured before | |
| 74 becoming a server thread itself. | |
| 75 </para> | |
| 76 <para> | |
| 77 Each HTTPD server thread simply waits for a connection to be made to | |
| 78 the server port. When the connection is made it reads the HTTP request | |
| 79 and extracts the filename being accessed. If the request also contains | |
| 80 form data, this is also preserved. The filename is then looked up in a | |
| 81 table. | |
| 82 </para> | |
| 83 <para> | |
| 84 Each table entry contains a filename pattern string, a | |
| 85 pointer to a handler function, and a user defined argument for the | |
| 86 function. Table entries are defined using the same link-time table | |
| 87 building mechanism used to generate device tables. This is all handled | |
| 88 by the <literal>CYG_HTTPD_TABLE_ENTRY()</literal> macro which has the | |
| 89 following format: | |
| 90 </para> | |
| 91 <programlisting width=72> | |
| 92 | |
| 93 #include <cyg/httpd/httpd.h> | |
| 94 | |
| 95 CYG_HTTPD_TABLE_ENTRY( __name, __pattern, __handler, __arg ) | |
| 96 | |
| 97 </programlisting> | |
| 98 <para> | |
| 99 The <parameter>__name</parameter> argument is a variable name for the | |
| 100 table entry since C does not allow us to define anonymous data | |
| 101 structures. This name should be chosen so that it is unique and does | |
| 102 not pollute the name space. The <parameter>__pattern</parameter> | |
| 103 argument is the match pattern. The <parameter>__handler</parameter> | |
| 104 argument is a pointer to the handler function and | |
| 105 <parameter>__arg</parameter> the user defined value. | |
| 106 </para> | |
| 107 <para> | |
| 108 The link-time table building means that several different pieces of | |
| 109 code can define server table entries, and so long as the patterns do | |
| 110 not clash they can be totally oblivious of each other. However, note | |
| 111 also that this mechanism does not guarantee the order in which entries | |
| 112 appear, this depends on the order of object files in the link, which | |
| 113 could vary from one build to the next. So any tricky pattern matching | |
| 114 that relies on this may not always work. | |
| 115 </para> | |
| 116 <para> | |
| 117 A request filename matches an entry in the table if either it exactly | |
| 118 matches the pattern string, or if the pattern ends in an asterisk, and | |
| 119 it matches everything up to that point. So for example the pattern | |
| 120 "/monitor/threads.html" will only match that exact filename, | |
| 121 but the pattern "/monitor/thread-*" will match | |
| 122 "/monitor/thread-0040.html", | |
| 123 "/monitor/thread-0100.html" and any other filename starting | |
| 124 with "/monitor/thread-". | |
| 125 </para> | |
| 126 <para> | |
| 127 When a pattern is matched, the hander function is called. It has the | |
| 128 following prototype: | |
| 129 </para> | |
| 130 <programlisting width=72> | |
| 131 cyg_bool cyg_httpd_handler(FILE *client, | |
| 132 char *filename, | |
| 133 char *formdata, | |
| 134 void *arg); | |
| 135 </programlisting> | |
| 136 <para> | |
| 137 The <parameter>client</parameter> argument is the TCP connection to | |
| 138 the client: anything output through this stream will be returned to | |
| 139 the browser. The <parameter>filename</parameter> argument is the | |
| 140 filename from the HTTP request and the <parameter>formdata</parameter> | |
| 141 argument is any form response data, or NULL if none was sent. The | |
| 142 <parameter>arg</parameter> argument is the user defined value from the | |
| 143 table entry. | |
| 144 </para> | |
| 145 <para> | |
| 146 The handler is entirely responsible for generating the response to the | |
| 147 client, both HTTP header and content. If the handler decides that it | |
| 148 does not want to generate a response it can return | |
| 149 <literal>false</literal>, in which case the table scan is resumed for | |
| 150 another match. If no match is found, or no handler returns true, then | |
| 151 a default response page is generated indicating that the requested | |
| 152 page cannot be found. | |
| 153 </para> | |
| 154 <para> | |
| 155 Finally, the server thread closes the connection to the client and | |
| 156 loops back to accept a new connection. | |
| 157 </para> | |
| 158 </sect1> | |
| 159 | |
| 160 <!-- =============================================================== --> | |
| 161 | |
| 162 <sect1 id="net-httpd-configuration"> | |
| 163 <title>Server Configuration</title> | |
| 164 <para> | |
| 165 The HTTP server has a number of configuration options: | |
| 166 </para> | |
| 167 | |
| 168 <sect2> | |
| 169 <title><literal>CYGNUM_HTTPD_SERVER_PORT</literal></title> | |
| 170 <para> | |
| 171 This option defines the TCP port that the server will listen on. It | |
| 172 defaults to the standard HTTP port number 80. It may be changed to a | |
| 173 different number if, for example, another HTTP server is using the | |
| 174 main HTTP port. | |
| 175 </para> | |
| 176 </sect2> | |
| 177 | |
| 178 <sect2> | |
| 179 <title><literal>CYGDAT_HTTPD_SERVER_ID</literal></title> | |
| 180 <para> | |
| 181 This is the string that is reported to the client in the | |
| 182 "Server:" field of the HTTP header. | |
| 183 </para> | |
| 184 </sect2> | |
| 185 | |
| 186 <sect2> | |
| 187 <title><literal>CYGNUM_HTTPD_THREAD_COUNT</literal></title> | |
| 188 <para> | |
| 189 The HTTP server can be configured to use more than one thread to | |
| 190 service HTTP requests. If you expect to serve complex pages with many | |
| 191 images or other components that are fetched separately, or if any | |
| 192 pages may take a long time to send, then it may be useful to increase | |
| 193 the number of server threads. For most uses, however, the connection | |
| 194 queuing in the TCP/IP stack and the speed with which each page is | |
| 195 generated, means that a single thread is usually adequate. | |
| 196 </para> | |
| 197 </sect2> | |
| 198 | |
| 199 <sect2> | |
| 200 <title><literal>CYGNUM_HTTPD_THREAD_PRIORITY</literal></title> | |
| 201 <para> | |
| 202 The HTTP server threads can be run at any priority. The exact priority | |
| 203 depends on the importance of the server relative to the rest of the | |
| 204 system. The default is to put them in the middle of the priority range | |
| 205 to provide reasonable response without impacting genuine high priority | |
| 206 threads. | |
| 207 </para> | |
| 208 </sect2> | |
| 209 | |
| 210 <sect2> | |
| 211 <title><literal>CYGNUM_HTTPD_THREAD_STACK_SIZE</literal></title> | |
| 212 <para> | |
| 213 This is the amount of stack to be allocated for each of the HTTPD | |
| 214 threads. The actual stack size allocated will be this value plus the | |
| 215 values of <literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal> and | |
| 216 <literal>CYGNUM_HTTPD_SERVER_BUFFER_SIZE</literal>. | |
| 217 </para> | |
| 218 </sect2> | |
| 219 | |
| 220 <sect2> | |
| 221 <title><literal>CYGNUM_HTTPD_SERVER_BUFFER_SIZE</literal></title> | |
| 222 <para> | |
| 223 This defines the size of the buffer used to receive the first line of | |
| 224 each HTTP request. If you expect to use particularly long URLs or have | |
| 225 very complex forms, this should be increased. | |
| 226 </para> | |
| 227 </sect2> | |
| 228 | |
| 229 <sect2> | |
|
1535
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
230 <title><literal>CYGNUM_HTTPD_SERVER_AUTO_START</literal></title> |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
231 <para> |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
232 This option causes the HTTP Daemon to be started automatically during |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
233 system initialization. If this option is not set then the application |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
234 must start the daemon explicitly by calling |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
235 <function>cyg_httpd_startup()</function>. This option is set by |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
236 default. |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
237 </para> |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
238 </sect2> |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
239 |
|
00ed8504e595
Forgot to update the documentation in last checkin. Now done.
nickg
parents:
1240
diff
changeset
|
240 <sect2> |
| 468 | 241 <title><literal>CYGNUM_HTTPD_SERVER_DELAY</literal></title> |
| 242 <para> | |
| 243 This defines the number of system clock ticks that the HTTP server | |
| 244 will wait before initializing itself and spawning any extra server | |
| 245 threads. This is to give the application a chance to initialize | |
| 246 properly without any interference from the HTTPD. | |
| 247 </para> | |
| 248 </sect2> | |
| 249 | |
| 250 </sect1> | |
| 251 | |
| 252 <!-- =============================================================== --> | |
| 253 | |
| 254 <sect1 id="net-httpd-html"> | |
| 255 <title>Support Functions and Macros</title> | |
| 256 <para> | |
| 257 The emphasis of this server is on dynamically generated content, | |
| 258 rather than fetching it from a filesystem. To do this the handler | |
| 259 functions make calls to <function>fprintf()</function> and | |
| 260 <function>fputs()</function>. Such handler functions would end up a | |
| 261 mass of print calls, with the actual structure of the HTML page hidden | |
| 262 in the format strings and arguments, making maintenance and debugging | |
| 263 very difficult. Such an approach would also result in the definition | |
| 264 of many, often only slightly different, format strings, leading to | |
| 265 unnecessary bloat. | |
| 266 </para> | |
| 267 <para> | |
| 268 In an effort to expose the structure of the HTML in the structure of | |
| 269 the C code, and to maximize the sharing of string constants, the | |
| 270 <filename>cyg/httpd/httpd.h</filename> header file defines a set of | |
| 271 helper functions and macros. Most of these are wrappers for predefined | |
| 272 print calls on the <parameter>client</parameter> stream passed to the | |
| 273 hander function. For examples of their use, see the System Monitor | |
| 274 example. | |
| 275 </para> | |
| 276 <note> | |
| 277 <para> | |
| 278 All arguments to macros are pointers to strings, unless otherwise | |
| 279 stated. In general, wherever a function or macro has an | |
| 280 <parameter>attr</parameter> or <parameter>__attr</parameter> | |
| 281 parameter, then the contents of this string will be inserted into the | |
| 282 tag being defined as HTML attributes. If it is a NULL or empty string | |
| 283 it will be ignored. | |
| 284 </para> | |
| 285 </note> | |
| 286 | |
| 287 <sect2> | |
| 288 <title>HTTP Support</title> | |
| 289 <programlisting width=72> | |
| 290 void cyg_http_start( FILE *client, char *content_type, int content_length ); | |
| 291 void cyg_http_finish( FILE *client ); | |
| 292 #define html_begin(__client) | |
| 293 #define html_end( __client ) | |
| 294 </programlisting> | |
| 295 <para> | |
| 296 The function <function>cyg_http_start()</function> generates a simple | |
| 297 HTTP response header containing the value of | |
| 298 <literal>CYGDAT_HTTPD_SERVER_ID</literal> in the "Server" field, and the | |
| 299 values of <parameter>content_type</parameter> and | |
| 300 <parameter>content_length</parameter> in the "Content-type" | |
| 301 and "Content-length" field respectively. The function | |
| 302 <function>cyg_http_finish()</function> just adds an extra newline to | |
| 303 the end of the output and then flushes it to force the data out to the | |
| 304 client. | |
| 305 </para> | |
| 306 <para> | |
| 307 The macro <literal>html_begin()</literal> generates an HTTP header | |
| 308 with a "text/html" content type followed by an opening | |
| 309 "<html>" tag. <literal>html_end()</literal> generates | |
| 310 a closing "</html>" tag and calls | |
| 311 <function>cyg_http_finish()</function>. | |
| 312 </para> | |
| 313 </sect2> | |
| 314 | |
| 315 <sect2> | |
| 316 <title>General HTML Support</title> | |
| 317 <programlisting width=72> | |
| 318 void cyg_html_tag_begin( FILE *client, char *tag, char *attr ); | |
| 319 void cyg_html_tag_end( FILE *client, char *tag ); | |
| 320 #define html_tag_begin( __client, __tag, __attr ) | |
| 321 #define html_tag_end( __client, __tag ) | |
| 322 #define html_head( __client, __title, __meta ) | |
| 323 #define html_body_begin( __client, __attr ) | |
| 324 #define html_body_end( __client ) | |
| 325 #define html_heading( __client, __level, __heading ) | |
| 326 #define html_para_begin( __client, __attr ) | |
| 327 #define html_url( __client, __text, __link ) | |
| 328 #define html_image( __client, __source, __alt, __attr ) | |
| 329 </programlisting> | |
| 330 <para> | |
| 331 The function <function>cyg_html_tag_begin()</function> generates an | |
| 332 opening tag with the given name. The function | |
| 333 <function>cyg_html_tag_end()</function> generates a closing tag with | |
| 334 the given name. The macros <literal>html_tag_begin()</literal> and | |
| 335 <literal>html_tag_end</literal> are just wrappers for these functions. | |
| 336 </para> | |
| 337 <para> | |
| 338 The macro <literal>html_head()</literal> generates an HTML header | |
| 339 section with <parameter>__title</parameter> as the title. The | |
| 340 <parameter>__meta</parameter> argument defines any meta tags that will | |
| 341 be inserted into the header. <literal>html_body_begin()</literal> and | |
| 342 <literal>html_body_end</literal> generate HTML body begin and end | |
| 343 tags. | |
| 344 </para> | |
| 345 <para> | |
| 346 <literal>html_heading()</literal> generates a complete HTML header | |
| 347 where <parameter>__level</parameter> is a numerical level, between 1 | |
| 348 and 6, and <parameter>__heading</parameter> is the heading | |
| 349 text. <literal>html_para_begin()</literal> generates a paragraph | |
| 350 break. | |
| 351 </para> | |
| 352 <para> | |
| 353 <literal>html_url()</literal> inserts a URL where | |
| 354 <parameter>__text</parameter> is the displayed text and | |
| 355 <parameter>__link</parameter> is the URL of the linked | |
| 356 page. <literal>html_image()</literal> inserts an image tag where | |
| 357 <parameter>__source</parameter> is the URL of the image to be | |
| 358 included and <parameter>__alt</parameter> is the alternative text for | |
| 359 when the image is not displayed. | |
| 360 </para> | |
| 361 </sect2> | |
| 362 | |
| 363 <sect2> | |
| 364 <title>Table Support</title> | |
| 365 <programlisting width=72> | |
| 366 #define html_table_begin( __client, __attr ) | |
| 367 #define html_table_end( __client ) | |
| 368 #define html_table_header( __client, __content, __attr ) | |
| 369 #define html_table_row_begin( __client, __attr ) | |
| 370 #define html_table_row_end( __client ) | |
| 371 #define html_table_data_begin( __client, __attr ) | |
| 372 #define html_table_data_end( __client ) | |
| 373 </programlisting> | |
| 374 <para> | |
| 375 <literal>html_table_begin()</literal> starts a table and | |
| 376 <literal>html_table_end()</literal> end | |
| 377 it. <literal>html_table_header()</literal> generates a simple table | |
| 378 column header containg the string <parameter>__content</parameter>. | |
| 379 </para> | |
| 380 <para> | |
| 381 <literal>html_table_row_begin()</literal> and | |
| 382 <literal>html_table_row_end()</literal> begin and end a table row, | |
| 383 and similarly <literal>html_table_data_begin()</literal> and | |
| 384 <literal>html_table_data_end()</literal> begin and end a table | |
| 385 entry. | |
| 386 </para> | |
| 387 </sect2> | |
| 388 | |
| 389 <sect2> | |
| 390 <title>Forms Support</title> | |
| 391 <programlisting width=72> | |
| 392 #define html_form_begin( __client, __url, __attr ) | |
| 393 #define html_form_end( __client ) | |
| 394 #define html_form_input( __client, __type, __name, __value, __attr ) | |
| 395 #define html_form_input_radio( __client, __name, __value, __checked ) | |
| 396 #define html_form_input_checkbox( __client, __name, __value, __checked ) | |
| 397 #define html_form_input_hidden( __client, __name, __value ) | |
| 398 #define html_form_select_begin( __client, __name, __attr ) | |
| 399 #define html_form_option( __client, __value, __label, __selected ) | |
| 400 #define html_form_select_end( __client ) | |
| 401 void cyg_formdata_parse( char *data, char *list[], int size ); | |
| 402 char *cyg_formlist_find( char *list[], char *name ); | |
| 403 </programlisting> | |
| 404 <para> | |
| 405 <literal>html_form_begin()</literal> begins a form, the | |
| 406 <parameter>__url</parameter> argument is the value for the | |
| 407 <literal>action</literal> | |
| 408 attribute. <literal>html_form_end()</literal> ends the form. | |
| 409 </para> | |
| 410 <para> | |
| 411 <literal>html_form_input()</literal> defines a general form input | |
| 412 element with the given type, name and | |
| 413 value. <literal>html_form_input_radio</literal> creates a radio button | |
| 414 with the given name and value; the <parameter>__checked</parameter> | |
| 415 argument is a boolean expression that is used to determine whether the | |
| 416 <literal>checked</literal> attribute is added to the tag. Similarly | |
| 417 <literal>html_form_input_checkbox()</literal> defines a checkbox | |
| 418 element. <literal>html_form_input_hidden()</literal> defines a hidden | |
| 419 form element with the given name and value. | |
| 420 </para> | |
| 421 <para> | |
| 422 <literal>html_form_select_begin()</literal> begins a multiple choice | |
| 423 menu with the given name. <literal>html_form_select_end()</literal> | |
| 424 end it. <literal>html_form_option()</literal> defines a menu entry | |
| 425 with the given value and label; the <parameter>__selected</parameter> | |
| 426 argument is a boolean expression controlling whether the | |
| 427 <literal>selected</literal> attribute is added to the tag. | |
| 428 </para> | |
| 429 <para> | |
| 430 <function>cyg_formdata_parse()</function> converts a form response | |
| 431 string into an <literal>NULL</literal>-terminated array of | |
| 432 "name=value" entries. The <parameter>data</parameter> | |
| 433 argument is the string as passed to the handler function; note that | |
| 434 this string is not copied and will be updated in place to form the | |
| 435 list entries. <parameter>list</parameter> is a pointer to an array of | |
| 436 character pointers, and is <parameter>size</parameter> elements long. | |
| 437 <function>cyg_formlist_find()</function> searches a list generated by | |
| 438 <function>cyg_formdata_parse()</function> and returns a pointer to the | |
| 439 value part of the string whose name part matches | |
| 440 <parameter>name</parameter>; if there is no match it will return | |
| 441 <literal>NULL</literal>. | |
| 442 </para> | |
| 443 </sect2> | |
| 444 | |
| 445 <sect2> | |
| 446 <title>Predefined Handlers</title> | |
| 447 <programlisting width=72> | |
| 448 | |
|
1240
eeb14eae974b
* src/httpd.c (cyg_httpd_server): Removed unused variable.
asl
parents:
1008
diff
changeset
|
449 cyg_bool cyg_httpd_send_html( FILE *client, char *filename, char *request, void *arg ); |
| 468 | 450 |
| 451 typedef struct | |
| 452 { | |
| 453 char *content_type; | |
| 454 cyg_uint32 content_length; | |
| 455 cyg_uint8 *data; | |
| 456 } cyg_httpd_data; | |
| 457 #define CYG_HTTPD_DATA( __name, __type, __length, __data ) | |
| 458 | |
|
1240
eeb14eae974b
* src/httpd.c (cyg_httpd_server): Removed unused variable.
asl
parents:
1008
diff
changeset
|
459 cyg_bool cyg_httpd_send_data( FILE *client, char *filename, char *request, void *arg ); |
| 468 | 460 |
| 461 </programlisting> | |
| 462 <para> | |
| 463 The HTTP server defines a couple of predefined handers to make it | |
| 464 easier to deliver simple, static content. | |
| 465 </para> | |
| 466 <para> | |
| 467 <function>cyg_httpd_send_html()</function> takes a | |
| 468 <literal>NULL</literal>-terminated string as the argument and sends it | |
| 469 to the client with an HTTP header indicating that it is HTML. The | |
| 470 following is an example of its use: | |
| 471 </para> | |
| 472 <programlisting width=72> | |
| 473 | |
| 474 char cyg_html_message[] = "<head><title>Welcome</title></head>\n" | |
| 475 "<body><h2>Welcome to my Web Page</h2></body>\n" | |
| 476 | |
| 477 CYG_HTTPD_TABLE_ENTRY( cyg_html_message_entry, | |
| 478 "/message.html", | |
| 479 cyg_httpd_send_html, | |
| 480 cyg_html_message ); | |
| 481 | |
| 482 </programlisting> | |
| 483 <para> | |
| 484 <function>cyg_httpd_send_data()</function> Sends arbitrary data to the | |
| 485 client. The argument is a pointer to a <type>cyg_httpd_data</type> | |
| 486 structure that defines the content type and length of the data, and a | |
| 487 pointer to the data itself. The <literal>CYG_HTTPD_DATA()</literal> | |
| 488 macro automates the definition of the structure. Here is a typical | |
| 489 example of its use: | |
| 490 </para> | |
| 491 <programlisting width=72> | |
| 492 | |
| 493 static cyg_uint8 ecos_logo_gif[] = { | |
| 494 ... | |
| 495 }; | |
| 496 | |
| 497 CYG_HTTPD_DATA( cyg_monitor_ecos_logo_data, | |
| 498 "image/gif", | |
| 499 sizeof(ecos_logo_gif), | |
| 500 ecos_logo_gif ); | |
| 501 | |
| 502 CYG_HTTPD_TABLE_ENTRY( cyg_monitor_ecos_logo, | |
| 503 "/monitor/ecos.gif", | |
| 504 cyg_httpd_send_data, | |
| 505 &cyg_monitor_ecos_logo_data ); | |
| 506 | |
| 507 </programlisting> | |
| 508 </sect2> | |
| 509 | |
| 510 </sect1> | |
| 511 | |
| 512 <!-- =============================================================== --> | |
| 513 | |
| 514 <sect1 id="net-httpd-monitor"> | |
| 515 <title>System Monitor</title> | |
| 516 <para> | |
| 517 Included in the HTTPD package is a simple System Monitor that is | |
| 518 intended to act as a test and an example of how to produce servers. | |
| 519 It is also hoped that it might be of some use in and of itself. | |
| 520 </para> | |
| 521 <para> | |
| 522 The System Monitor is intended to work in the background of any | |
| 523 application. Adding the network stack and the HTTPD package to any | |
| 524 configuration will enable the monitor by default. It may be disabled | |
| 525 by disabling the <literal>CYGPKG_HTTPD_MONITOR</literal> option. | |
| 526 </para> | |
| 527 <para> | |
| 528 The monitor is intended to be simple and self-explanatory in use. It | |
| 529 consists of four main pages. The thread monitor page presents a table | |
| 530 of all current threads showing such things as id, state, priority, | |
| 531 name and stack dimensions. Clicking on the thread ID will link to a | |
| 532 thread edit page where the thread's state and priority may be | |
| 533 manipulated. The interrupt monitor just shows a table of the current | |
| 534 interrupts and indicates which are active. The memory monitor shows a | |
| 535 256 byte page of memory, with controls to change the base address and | |
|
1008
4ca8a5f30c03
* src/monitor.c (cyg_monitor_network): Added IPv6 information to
asl
parents:
468
diff
changeset
|
536 display element size. Note: Accessing invalid memory locations can cause |
|
4ca8a5f30c03
* src/monitor.c (cyg_monitor_network): Added IPv6 information to
asl
parents:
468
diff
changeset
|
537 memory exceptions and the program to crash. The network monitor page shows |
| 468 | 538 information extracted from the active network interfaces and |
| 539 protocols. Finally, if kernel instrumentation is enabled, the | |
| 540 instrumentation page provides some controls over the instrumentation | |
| 541 mechanism, and displays the instrumentation buffer. | |
| 542 </para> | |
| 543 </sect1> | |
| 544 | |
| 545 <!-- =============================================================== --> | |
| 546 | |
| 547 </chapter> | |
| 548 </part> |