eCos Reference Manual
Prev | Chapter 53. Embedded HTTP Server | Next

# Support Functions and Macros

The emphasis of this server is on dynamically generated content, rather than fetching it from a filesystem. To do this the handler functions make calls to `fprintf()` and `fputs()`. Such handler functions would end up a mass of print calls, with the actual structure of the HTML page hidden in the format strings and arguments, making maintenance and debugging very difficult. Such an approach would also result in the definition of many, often only slightly different, format strings, leading to unnecessary bloat.

In an effort to expose the structure of the HTML in the structure of the C code, and to maximize the sharing of string constants, the `cyg/httpd/httpd.h` header file defines a set of helper functions and macros. Most of these are wrappers for predefined print calls on the client stream passed to the hander function. For examples of their use, see the System Monitor example.

> Note: All arguments to macros are pointers to strings, unless otherwise stated. In general, wherever a function or macro has an attr or __attr parameter, then the contents of this string will be inserted into the tag being defined as HTML attributes. If it is a NULL or empty string it will be ignored.

## HTTP Support

    void cyg_http_start( FILE *client, char *content_type, int content_length );
    void cyg_http_finish( FILE *client );
    #define html_begin(__client)
    #define html_end( __client )

The function `cyg_http_start()` generates a simple HTTP response header containing the value of CYGDAT_HTTPD_SERVER_ID in the "Server" field, and the values of content_type and content_length in the "Content-type" and "Content-length" field respectively. The function `cyg_http_finish()` just adds an extra newline to the end of the output and then flushes it to force the data out to the client.

The macro html_begin() generates an HTTP header with a "text/html" content type followed by an opening "<html>" tag. html_end() generates a closing "</html>" tag and calls `cyg_http_finish()`.

## General HTML Support

    void cyg_html_tag_begin( FILE *client, char *tag, char *attr );
    void cyg_html_tag_end( FILE *client, char *tag );
    #define html_tag_begin( __client, __tag, __attr )
    #define html_tag_end( __client, __tag )
    #define html_head( __client, __title, __meta )
    #define html_body_begin( __client, __attr )
    #define html_body_end( __client )
    #define html_heading( __client, __level, __heading )
    #define html_para_begin( __client, __attr )
    #define html_url( __client, __text, __link )
    #define html_image( __client, __source, __alt, __attr )

The function `cyg_html_tag_begin()` generates an opening tag with the given name. The function `cyg_html_tag_end()` generates a closing tag with the given name. The macros html_tag_begin() and html_tag_end are just wrappers for these functions.

The macro html_head() generates an HTML header section with __title as the title. The __meta argument defines any meta tags that will be inserted into the header. html_body_begin() and html_body_end generate HTML body begin and end tags.

html_heading() generates a complete HTML header where __level is a numerical level, between 1 and 6, and __heading is the heading text. html_para_begin() generates a paragraph break.

html_url() inserts a URL where __text is the displayed text and __link is the URL of the linked page. html_image() inserts an image tag where __source is the URL of the image to be included and __alt is the alternative text for when the image is not displayed.

## Table Support

    #define html_table_begin( __client, __attr )
    #define html_table_end( __client )
    #define html_table_header( __client, __content, __attr )
    #define html_table_row_begin( __client, __attr )
    #define html_table_row_end( __client )
    #define html_table_data_begin( __client, __attr )
    #define html_table_data_end( __client )

html_table_begin() starts a table and html_table_end() end it. html_table_header() generates a simple table column header containg the string __content.

html_table_row_begin() and html_table_row_end() begin and end a table row, and similarly html_table_data_begin() and html_table_data_end() begin and end a table entry.

## Forms Support

    #define html_form_begin( __client, __url, __attr )
    #define html_form_end( __client )
    #define html_form_input( __client, __type, __name, __value, __attr )
    #define html_form_input_radio( __client, __name, __value, __checked )
    #define html_form_input_checkbox( __client, __name, __value, __checked )
    #define html_form_input_hidden( __client, __name, __value )
    #define html_form_select_begin( __client, __name, __attr )
    #define html_form_option( __client, __value, __label, __selected )
    #define html_form_select_end( __client )
    void cyg_formdata_parse( char *data, char *list[], int size );
    char *cyg_formlist_find( char *list[], char *name );

html_form_begin() begins a form, the __url argument is the value for the action attribute. html_form_end() ends the form.

html_form_input() defines a general form input element with the given type, name and value. html_form_input_radio creates a radio button with the given name and value; the __checked argument is a boolean expression that is used to determine whether the checked attribute is added to the tag. Similarly html_form_input_checkbox() defines a checkbox element. html_form_input_hidden() defines a hidden form element with the given name and value.

html_form_select_begin() begins a multiple choice menu with the given name. html_form_select_end() end it. html_form_option() defines a menu entry with the given value and label; the __selected argument is a boolean expression controlling whether the selected attribute is added to the tag.

`cyg_formdata_parse()` converts a form response string into an NULL-terminated array of "name=value" entries. The data argument is the string as passed to the handler function; note that this string is not copied and will be updated in place to form the list entries. list is a pointer to an array of character pointers, and is size elements long. `cyg_formlist_find()` searches a list generated by `cyg_formdata_parse()` and returns a pointer to the value part of the string whose name part matches name; if there is no match it will return NULL.

## Predefined Handlers

    cyg_bool cyg_httpd_send_html( FILE *client, char *filename, char *request, void *arg );

    typedef struct
    {
        char        *content_type;
        cyg_uint32  content_length;
        cyg_uint8   *data;
    } cyg_httpd_data;
    #define CYG_HTTPD_DATA( __name, __type, __length, __data )

    cyg_bool cyg_httpd_send_data( FILE *client, char *filename, char *request, void *arg );

The HTTP server defines a couple of predefined handers to make it easier to deliver simple, static content.

`cyg_httpd_send_html()` takes a NULL-terminated string as the argument and sends it to the client with an HTTP header indicating that it is HTML. The following is an example of its use:

    char cyg_html_message[] = "<head><title>Welcome</title></head>\n"
                              "<body><h2>Welcome to my Web Page</h2></body>\n"

    CYG_HTTPD_TABLE_ENTRY( cyg_html_message_entry,
                           "/message.html",
                           cyg_httpd_send_html,
                           cyg_html_message );

`cyg_httpd_send_data()` Sends arbitrary data to the client. The argument is a pointer to a cyg_httpd_data structure that defines the content type and length of the data, and a pointer to the data itself. The CYG_HTTPD_DATA() macro automates the definition of the structure. Here is a typical example of its use:

    static cyg_uint8 ecos_logo_gif[] = {
        ...
    };

    CYG_HTTPD_DATA( cyg_monitor_ecos_logo_data,
                    "image/gif",
                    sizeof(ecos_logo_gif),
                    ecos_logo_gif );

    CYG_HTTPD_TABLE_ENTRY( cyg_monitor_ecos_logo,
                           "/monitor/ecos.gif",
                           cyg_httpd_send_data,
                           &cyg_monitor_ecos_logo_data );

Prev | Home | Next
Server Configuration | Up | System Monitor