doc/html/ref/net-httpd-html.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Support Functions and Macros</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="Embedded HTTP Server"
  23 HREF="net-httpd-chapter.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Server Configuration"
  26 HREF="net-httpd-configuration.html"><LINK
  27 REL="NEXT"
  28 TITLE="System Monitor"
  29 HREF="net-httpd-monitor.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-httpd-configuration.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 48. Embedded HTTP Server</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-httpd-monitor.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-HTTPD-HTML">Support Functions and Macros</H1
  86 ><P
  87 >The emphasis of this server is on dynamically generated content,
  88 rather than fetching it from a filesystem. To do this the handler
  89 functions make calls to <TT
  90 CLASS="FUNCTION"
  91 >fprintf()</TT
  92 > and
  93 <TT
  94 CLASS="FUNCTION"
  95 >fputs()</TT
  96 >. Such handler functions would end up a
  97 mass of print calls, with the actual structure of the HTML page hidden
  98 in the format strings and arguments, making maintenance and debugging
  99 very difficult. Such an approach would also result in the definition
 100 of many, often only slightly different, format strings, leading to
 101 unnecessary bloat.</P
 102 ><P
 103 >In an effort to expose the structure of the HTML in the structure of
 104 the C code, and to maximize the sharing of string constants, the
 105 <TT
 106 CLASS="FILENAME"
 107 >cyg/httpd/httpd.h</TT
 108 > header file defines a set of
 109 helper functions and macros. Most of these are wrappers for predefined
 110 print calls on the <TT
 111 CLASS="PARAMETER"
 112 ><I
 113 >client</I
 114 ></TT
 115 > stream passed to the
 116 hander function. For examples of their use, see the System Monitor
 117 example.</P
 118 ><DIV
 119 CLASS="NOTE"
 120 ><BLOCKQUOTE
 121 CLASS="NOTE"
 122 ><P
 123 ><B
 124 >Note: </B
 125 >All arguments to macros are pointers to strings, unless otherwise
 126 stated. In general, wherever a function or macro has an
 127 <TT
 128 CLASS="PARAMETER"
 129 ><I
 130 >attr</I
 131 ></TT
 132 > or <TT
 133 CLASS="PARAMETER"
 134 ><I
 135 >__attr</I
 136 ></TT
 137 >
 138 parameter, then the contents of this string will be inserted into the
 139 tag being defined as HTML attributes. If it is a NULL or empty string
 140 it will be ignored.</P
 141 ></BLOCKQUOTE
 142 ></DIV
 143 ><DIV
 144 CLASS="SECT2"
 145 ><H2
 146 CLASS="SECT2"
 147 ><A
 148 NAME="AEN15305">HTTP Support</H2
 149 ><TABLE
 150 BORDER="5"
 151 BGCOLOR="#E0E0F0"
 152 WIDTH="70%"
 153 ><TR
 154 ><TD
 155 ><PRE
 156 CLASS="PROGRAMLISTING"
 157 >void cyg_http_start( FILE *client, char *content_type, int content_length );
 158 void cyg_http_finish( FILE *client );
 159 #define html_begin(__client)
 160 #define html_end( __client )</PRE
 161 ></TD
 162 ></TR
 163 ></TABLE
 164 ><P
 165 >The function <TT
 166 CLASS="FUNCTION"
 167 >cyg_http_start()</TT
 168 > generates a simple
 169 HTTP response header containing the value of
 170 <TT
 171 CLASS="LITERAL"
 172 >CYGDAT_HTTPD_SERVER_ID</TT
 173 > in the &quot;Server&quot; field, and the
 174 values of <TT
 175 CLASS="PARAMETER"
 176 ><I
 177 >content_type</I
 178 ></TT
 179 > and
 180 <TT
 181 CLASS="PARAMETER"
 182 ><I
 183 >content_length</I
 184 ></TT
 185 > in the &quot;Content-type&quot;
 186 and &quot;Content-length&quot; field respectively. The function
 187 <TT
 188 CLASS="FUNCTION"
 189 >cyg_http_finish()</TT
 190 > just adds an extra newline to
 191 the end of the output and then flushes it to force the data out to the
 192 client.</P
 193 ><P
 194 >The macro <TT
 195 CLASS="LITERAL"
 196 >html_begin()</TT
 197 > generates an HTTP header
 198 with a &quot;text/html&quot; content type followed by an opening
 199 &quot;&lt;html&gt;&quot; tag. <TT
 200 CLASS="LITERAL"
 201 >html_end()</TT
 202 > generates
 203 a closing &quot;&lt;/html&gt;&quot; tag and calls
 204 <TT
 205 CLASS="FUNCTION"
 206 >cyg_http_finish()</TT
 207 >.</P
 208 ></DIV
 209 ><DIV
 210 CLASS="SECT2"
 211 ><H2
 212 CLASS="SECT2"
 213 ><A
 214 NAME="AEN15318">General HTML Support</H2
 215 ><TABLE
 216 BORDER="5"
 217 BGCOLOR="#E0E0F0"
 218 WIDTH="70%"
 219 ><TR
 220 ><TD
 221 ><PRE
 222 CLASS="PROGRAMLISTING"
 223 >void cyg_html_tag_begin( FILE *client, char *tag, char *attr );
 224 void cyg_html_tag_end( FILE *client, char *tag );
 225 #define html_tag_begin( __client, __tag, __attr )
 226 #define html_tag_end( __client, __tag )
 227 #define html_head( __client, __title, __meta )
 228 #define html_body_begin( __client, __attr )
 229 #define html_body_end( __client )
 230 #define html_heading( __client, __level, __heading )
 231 #define html_para_begin( __client, __attr )
 232 #define html_url( __client, __text, __link )
 233 #define html_image( __client, __source, __alt, __attr )</PRE
 234 ></TD
 235 ></TR
 236 ></TABLE
 237 ><P
 238 >The function <TT
 239 CLASS="FUNCTION"
 240 >cyg_html_tag_begin()</TT
 241 > generates an
 242 opening tag with the given name. The function
 243 <TT
 244 CLASS="FUNCTION"
 245 >cyg_html_tag_end()</TT
 246 > generates a closing tag with
 247 the given name. The macros <TT
 248 CLASS="LITERAL"
 249 >html_tag_begin()</TT
 250 > and
 251 <TT
 252 CLASS="LITERAL"
 253 >html_tag_end</TT
 254 > are just wrappers for these functions.</P
 255 ><P
 256 >The macro <TT
 257 CLASS="LITERAL"
 258 >html_head()</TT
 259 > generates an HTML header
 260 section with <TT
 261 CLASS="PARAMETER"
 262 ><I
 263 >__title</I
 264 ></TT
 265 > as the title. The
 266 <TT
 267 CLASS="PARAMETER"
 268 ><I
 269 >__meta</I
 270 ></TT
 271 > argument defines any meta tags that will
 272 be inserted into the header. <TT
 273 CLASS="LITERAL"
 274 >html_body_begin()</TT
 275 > and
 276 <TT
 277 CLASS="LITERAL"
 278 >html_body_end</TT
 279 > generate HTML body begin and end
 280 tags.</P
 281 ><P
 282 ><TT
 283 CLASS="LITERAL"
 284 >html_heading()</TT
 285 > generates a complete HTML header
 286 where <TT
 287 CLASS="PARAMETER"
 288 ><I
 289 >__level</I
 290 ></TT
 291 > is a numerical level, between 1
 292 and 6, and <TT
 293 CLASS="PARAMETER"
 294 ><I
 295 >__heading</I
 296 ></TT
 297 > is the heading
 298 text. <TT
 299 CLASS="LITERAL"
 300 >html_para_begin()</TT
 301 > generates a paragraph
 302 break.</P
 303 ><P
 304 ><TT
 305 CLASS="LITERAL"
 306 >html_url()</TT
 307 > inserts a URL where
 308 <TT
 309 CLASS="PARAMETER"
 310 ><I
 311 >__text</I
 312 ></TT
 313 > is the displayed text and
 314 <TT
 315 CLASS="PARAMETER"
 316 ><I
 317 >__link</I
 318 ></TT
 319 > is the URL of the linked
 320 page. <TT
 321 CLASS="LITERAL"
 322 >html_image()</TT
 323 > inserts an image tag where
 324 <TT
 325 CLASS="PARAMETER"
 326 ><I
 327 >__source</I
 328 ></TT
 329 > is the URL of the image to be
 330 included and <TT
 331 CLASS="PARAMETER"
 332 ><I
 333 >__alt</I
 334 ></TT
 335 > is the alternative text for
 336 when the image is not displayed.</P
 337 ></DIV
 338 ><DIV
 339 CLASS="SECT2"
 340 ><H2
 341 CLASS="SECT2"
 342 ><A
 343 NAME="AEN15344">Table Support</H2
 344 ><TABLE
 345 BORDER="5"
 346 BGCOLOR="#E0E0F0"
 347 WIDTH="70%"
 348 ><TR
 349 ><TD
 350 ><PRE
 351 CLASS="PROGRAMLISTING"
 352 >#define html_table_begin( __client, __attr )
 353 #define html_table_end( __client )
 354 #define html_table_header( __client, __content, __attr )
 355 #define html_table_row_begin( __client, __attr )
 356 #define html_table_row_end( __client )
 357 #define html_table_data_begin( __client, __attr )
 358 #define html_table_data_end( __client )               </PRE
 359 ></TD
 360 ></TR
 361 ></TABLE
 362 ><P
 363 ><TT
 364 CLASS="LITERAL"
 365 >html_table_begin()</TT
 366 > starts a table and
 367 <TT
 368 CLASS="LITERAL"
 369 >html_table_end()</TT
 370 > end
 371 it. <TT
 372 CLASS="LITERAL"
 373 >html_table_header()</TT
 374 > generates a simple table
 375 column header containg the string <TT
 376 CLASS="PARAMETER"
 377 ><I
 378 >__content</I
 379 ></TT
 380 >. </P
 381 ><P
 382 ><TT
 383 CLASS="LITERAL"
 384 >html_table_row_begin()</TT
 385 > and
 386 <TT
 387 CLASS="LITERAL"
 388 >html_table_row_end()</TT
 389 > begin and end a table row,
 390 and similarly <TT
 391 CLASS="LITERAL"
 392 >html_table_data_begin()</TT
 393 > and
 394 <TT
 395 CLASS="LITERAL"
 396 >html_table_data_end()</TT
 397 > begin and end a table
 398 entry. </P
 399 ></DIV
 400 ><DIV
 401 CLASS="SECT2"
 402 ><H2
 403 CLASS="SECT2"
 404 ><A
 405 NAME="AEN15357">Forms Support</H2
 406 ><TABLE
 407 BORDER="5"
 408 BGCOLOR="#E0E0F0"
 409 WIDTH="70%"
 410 ><TR
 411 ><TD
 412 ><PRE
 413 CLASS="PROGRAMLISTING"
 414 >#define html_form_begin( __client, __url, __attr )
 415 #define html_form_end( __client )
 416 #define html_form_input( __client, __type, __name, __value, __attr )
 417 #define html_form_input_radio( __client, __name, __value, __checked )
 418 #define html_form_input_checkbox( __client, __name, __value, __checked )
 419 #define html_form_input_hidden( __client, __name, __value )
 420 #define html_form_select_begin( __client, __name, __attr )
 421 #define html_form_option( __client, __value, __label, __selected )
 422 #define html_form_select_end( __client )
 423 void cyg_formdata_parse( char *data, char *list[], int size );
 424 char *cyg_formlist_find( char *list[], char *name );</PRE
 425 ></TD
 426 ></TR
 427 ></TABLE
 428 ><P
 429 ><TT
 430 CLASS="LITERAL"
 431 >html_form_begin()</TT
 432 > begins a form, the
 433 <TT
 434 CLASS="PARAMETER"
 435 ><I
 436 >__url</I
 437 ></TT
 438 > argument is the value for the
 439 <TT
 440 CLASS="LITERAL"
 441 >action</TT
 442 >
 443 attribute. <TT
 444 CLASS="LITERAL"
 445 >html_form_end()</TT
 446 > ends the form.</P
 447 ><P
 448 ><TT
 449 CLASS="LITERAL"
 450 >html_form_input()</TT
 451 > defines a general form input
 452 element with the given type, name and
 453 value. <TT
 454 CLASS="LITERAL"
 455 >html_form_input_radio</TT
 456 > creates a radio button
 457 with the given name and value; the <TT
 458 CLASS="PARAMETER"
 459 ><I
 460 >__checked</I
 461 ></TT
 462 >
 463 argument is a boolean expression that is used to determine whether the
 464 <TT
 465 CLASS="LITERAL"
 466 >checked</TT
 467 > attribute is added to the tag. Similarly
 468 <TT
 469 CLASS="LITERAL"
 470 >html_form_input_checkbox()</TT
 471 > defines a checkbox
 472 element. <TT
 473 CLASS="LITERAL"
 474 >html_form_input_hidden()</TT
 475 > defines a hidden
 476 form element with the given name and value.</P
 477 ><P
 478 ><TT
 479 CLASS="LITERAL"
 480 >html_form_select_begin()</TT
 481 > begins a multiple choice
 482 menu with the given name. <TT
 483 CLASS="LITERAL"
 484 >html_form_select_end()</TT
 485 >
 486 end it. <TT
 487 CLASS="LITERAL"
 488 >html_form_option()</TT
 489 > defines a menu entry
 490 with the given value and label; the <TT
 491 CLASS="PARAMETER"
 492 ><I
 493 >__selected</I
 494 ></TT
 495 >
 496 argument is a boolean expression controlling whether the
 497 <TT
 498 CLASS="LITERAL"
 499 >selected</TT
 500 > attribute is added to the tag.</P
 501 ><P
 502 ><TT
 503 CLASS="FUNCTION"
 504 >cyg_formdata_parse()</TT
 505 > converts a form response
 506 string into an <TT
 507 CLASS="LITERAL"
 508 >NULL</TT
 509 >-terminated array of
 510 &quot;name=value&quot; entries. The <TT
 511 CLASS="PARAMETER"
 512 ><I
 513 >data</I
 514 ></TT
 515 >
 516 argument is the string as passed to the handler function; note that
 517 this string is not copied and will be updated in place to form the
 518 list entries.  <TT
 519 CLASS="PARAMETER"
 520 ><I
 521 >list</I
 522 ></TT
 523 > is a pointer to an array of
 524 character pointers, and is <TT
 525 CLASS="PARAMETER"
 526 ><I
 527 >size</I
 528 ></TT
 529 > elements long.
 530 <TT
 531 CLASS="FUNCTION"
 532 >cyg_formlist_find()</TT
 533 > searches a list generated by
 534 <TT
 535 CLASS="FUNCTION"
 536 >cyg_formdata_parse()</TT
 537 > and returns a pointer to the
 538 value part of the string whose name part matches
 539 <TT
 540 CLASS="PARAMETER"
 541 ><I
 542 >name</I
 543 ></TT
 544 >; if there is no match it will return
 545 <TT
 546 CLASS="LITERAL"
 547 >NULL</TT
 548 >.</P
 549 ></DIV
 550 ><DIV
 551 CLASS="SECT2"
 552 ><H2
 553 CLASS="SECT2"
 554 ><A
 555 NAME="AEN15388">Predefined Handlers</H2
 556 ><TABLE
 557 BORDER="5"
 558 BGCOLOR="#E0E0F0"
 559 WIDTH="70%"
 560 ><TR
 561 ><TD
 562 ><PRE
 563 CLASS="PROGRAMLISTING"
 564 >&#13;int cyg_httpd_send_html( FILE *client, char *filename, char *request, void *arg );
 565
 566 typedef struct
 567 {
 568     char        *content_type;
 569     cyg_uint32  content_length;
 570     cyg_uint8   *data;
 571 } cyg_httpd_data;
 572 #define CYG_HTTPD_DATA( __name, __type, __length, __data )
 573
 574 int cyg_httpd_send_data( FILE *client, char *filename, char *request, void *arg );&#13;</PRE
 575 ></TD
 576 ></TR
 577 ></TABLE
 578 ><P
 579 >The HTTP server defines a couple of predefined handers to make it
 580 easier to deliver simple, static content.</P
 581 ><P
 582 ><TT
 583 CLASS="FUNCTION"
 584 >cyg_httpd_send_html()</TT
 585 > takes a
 586 <TT
 587 CLASS="LITERAL"
 588 >NULL</TT
 589 >-terminated string as the argument and sends it
 590 to the client with an HTTP header indicating that it is HTML. The
 591 following is an example of its use:</P
 592 ><TABLE
 593 BORDER="5"
 594 BGCOLOR="#E0E0F0"
 595 WIDTH="70%"
 596 ><TR
 597 ><TD
 598 ><PRE
 599 CLASS="PROGRAMLISTING"
 600 >&#13;char cyg_html_message[] = "&lt;head&gt;&lt;title&gt;Welcome&lt;/title&gt;&lt;/head&gt;\n"
 601                           "&lt;body&gt;&lt;h2&gt;Welcome to my Web Page&lt;/h2&gt;&lt;/body&gt;\n"
 602
 603 CYG_HTTPD_TABLE_ENTRY( cyg_html_message_entry,
 604                        "/message.html",
 605                        cyg_httpd_send_html,
 606                        cyg_html_message );&#13;</PRE
 607 ></TD
 608 ></TR
 609 ></TABLE
 610 ><P
 611 ><TT
 612 CLASS="FUNCTION"
 613 >cyg_httpd_send_data()</TT
 614 > Sends arbitrary data to the
 615 client. The argument is a pointer to a <SPAN
 616 CLASS="TYPE"
 617 >cyg_httpd_data</SPAN
 618 >
 619 structure that defines the content type and length of the data, and a
 620 pointer to the data itself. The <TT
 621 CLASS="LITERAL"
 622 >CYG_HTTPD_DATA()</TT
 623 >
 624 macro automates the definition of the structure. Here is a typical
 625 example of its use:</P
 626 ><TABLE
 627 BORDER="5"
 628 BGCOLOR="#E0E0F0"
 629 WIDTH="70%"
 630 ><TR
 631 ><TD
 632 ><PRE
 633 CLASS="PROGRAMLISTING"
 634 >&#13;static cyg_uint8 ecos_logo_gif[] = {
 635     ...
 636 };
 637
 638 CYG_HTTPD_DATA( cyg_monitor_ecos_logo_data,
 639                 "image/gif",
 640                 sizeof(ecos_logo_gif),
 641                 ecos_logo_gif );
 642
 643 CYG_HTTPD_TABLE_ENTRY( cyg_monitor_ecos_logo,
 644                        "/monitor/ecos.gif",
 645                        cyg_httpd_send_data,
 646                        &amp;cyg_monitor_ecos_logo_data );&#13;</PRE
 647 ></TD
 648 ></TR
 649 ></TABLE
 650 ></DIV
 651 ></DIV
 652 ><DIV
 653 CLASS="NAVFOOTER"
 654 ><HR
 655 ALIGN="LEFT"
 656 WIDTH="100%"><TABLE
 657 SUMMARY="Footer navigation table"
 658 WIDTH="100%"
 659 BORDER="0"
 660 CELLPADDING="0"
 661 CELLSPACING="0"
 662 ><TR
 663 ><TD
 664 WIDTH="33%"
 665 ALIGN="left"
 666 VALIGN="top"
 667 ><A
 668 HREF="net-httpd-configuration.html"
 669 ACCESSKEY="P"
 670 >Prev</A
 671 ></TD
 672 ><TD
 673 WIDTH="34%"
 674 ALIGN="center"
 675 VALIGN="top"
 676 ><A
 677 HREF="ecos-ref.html"
 678 ACCESSKEY="H"
 679 >Home</A
 680 ></TD
 681 ><TD
 682 WIDTH="33%"
 683 ALIGN="right"
 684 VALIGN="top"
 685 ><A
 686 HREF="net-httpd-monitor.html"
 687 ACCESSKEY="N"
 688 >Next</A
 689 ></TD
 690 ></TR
 691 ><TR
 692 ><TD
 693 WIDTH="33%"
 694 ALIGN="left"
 695 VALIGN="top"
 696 >Server Configuration</TD
 697 ><TD
 698 WIDTH="34%"
 699 ALIGN="center"
 700 VALIGN="top"
 701 ><A
 702 HREF="net-httpd-chapter.html"
 703 ACCESSKEY="U"
 704 >Up</A
 705 ></TD
 706 ><TD
 707 WIDTH="33%"
 708 ALIGN="right"
 709 VALIGN="top"
 710 >System Monitor</TD
 711 ></TR
 712 ></TABLE
 713 ></DIV
 714 ></BODY
 715 ></HTML
 716 >