C language callback functions

The server allows the association of particular URLs to C language callback functions. eCos tables are used to define the association between a URL and its corresponding callback. The syntax of the macro to add callback entries to the table is:

CYG_HTTPD_HANDLER_TABLE_ENTRY(entry_label, url_string, callback);

entry table      : an identifier unique to this entry.
url_string       : a string with the extension url that will be appended to the
                   default directory.
callback         : a function with a prototype:
                   cyg_int32 callback_function(CYG_HTTPD_STATE*); 
                   Return value is ignored - just return 0.

CYG_HTTPD_STATE* is a pointer to a structure that contains, among others, a buffer (outbuffer) that can be used to send data out. The definitions of the structure is in http.h.

The following is an example of how to add a callback to a function myForm() whenever the URL /myform.cgi is requested:

CYG_HTTPD_HANDLER_TABLE_ENTRY(hal_cb_entry, "/myform.cgi", myForm);

and somewhere in the source tree there is a function:

cyg_int32 myForm(CYG_HTTPD_STATE* p)
{
   cyg_httpd_start_chunked("html");
   strcpy(p->outbuffer, "eCos Web Server");
   cyg_httpd_write_chunked(p->outbuffer, strlen(p->outbuffer))
   cyg_httpd_end_chunked();
}  

This function also shows the correct method of using the chunked frames API inside a c language callback and also shows the use of outbuffer to collect data to send out.

Chunked frames are useful when the size of the frame is not known upfront. In this case it possible to send a response in chunks of various sizes, and terminate it with a null chunk (See RFC 2616 for details). To use chunked frames, the cyg_httpd_start_chunked() function is used. The prototype is the following:

ssize_t cyg_httpd_start_chunked(char *);

The only parameter is the extension to use in the search for the MIME type. For most files this will be "html" or "htm" and it will be searched in the MIME table for an approriate MIME type that will be sent along in the header. The function returns the number of bytes sent out.

The chunked frame must be terminated by a call to cyg_httpd_end_chunked():

void cyg_httpd_end_chunked()(void);

In between these two calls, the user can call the function cyg_httpd_write_chunked() to send out data any number of times. It is important that cyg_httpd_write_chunked() be the only function used to send data out for chunked frames. This guarantees that proper formatting of the response is respected. The prototype for the function is:

ssize_t cyg_httpd_write_chunked(char* p, int len);

The 'char*' points to the data to send out, the 'int' is the length of the data to send.

In the case in which the size of the data is known upfront, the callback can instead create the header with a call to cyg_httpd_create_std_header() with the following prototype:

void cyg_httpd_create_std_header(char *ext, int len);

extension   : the extension used in the search of the MIME type
len         : length of the data to send out

and use cyg_httpd_write() to send data out to the client. The prototype of cyg_httpd_write() is the same as cyg_httpd_write_chunked()