Form Variables

The server will automatically try to parse form variables when a form is submitted in the following cases:

• In a GET request, when the URL is followed by a question mark sign

• In a POST request, when the the 'Content-Type' header line is set to 'application/x-www-form-urlencoded'

For example, if the user wants two form variables, "foo" and "bar", to be parsed automatically, those variable names must be added to the table with the following macro:

CYG_HTTPD_FVAR_TABLE_ENTRY(entry, name, buffp, bufflen)

entry            : an identifier unique to this entry.
name             : name of the form variable
buffp            : a pointer to a buffer of characters where to store the value
                   of the form variable.
bufflen          : The length of the buffer. Must include a trailing string
                   terminator.

or, in the specific instance mentioned above:

#define HTML_VAR_LEN   20
char var_foo[HTML_VAR_LEN];
char var_bar[HTML_VAR_LEN];
CYG_HTTPD_FVAR_TABLE_ENTRY(hal_form_entry_foo, "foo", var_foo, HTML_VAR_LEN);
CYG_HTTPD_FVAR_TABLE_ENTRY(hal_form_entry_bar, "bar", var_bar, HTML_VAR_LEN);

and after the GET or POST submissions, the list will contain the value for "foo" and "bar" (if they were found in the form data.) It is the responsability of the user to make sure that the buffer is large enough to hold all the data parsed (including the string terminator). The parser will write only up to the length of the buffer minus one (the last being the terminator) and discard any additional data.

The values parsed are likely going to be used in c language callback, or in CGI files. In a c language callback the user can directly access the pointers of individual variables for further processing, keeping in mind that the parsing always result in a string of characters to be produced, and any conversion (e.g. from strings to integer) must be performed within the callback. In a TCL script the user can just access a variable by its name. For example, in the case of the variables 'foo' and 'bar' shown above, it is possible to do something like 'write_chunked "You wrote $foo". The data that was sent in the body of a POST request is accessible in through a variable called 'post_data'. In CGI functions implemented using the objloader the pointers to the variables cannot be accessed directly, since the library will likely not know their location in memory. The proper way to access them is by using the cyg_httpd_find_form_variable() function from within the library:

char* cyg_httpd_find_form_variable(char* name)

name             : name of the form variable to look up

returns a pointer to the buffer, or 0 if the variable was not found.

When using the OBJLOADER package within the web server, an entry for the cyg_httpd_find_form_variable() function is automatically added to the externals table the OBJLOADER for relocation. See the OBLOADER paragraph of the ATHTTP user's guide for the full list of the exported functions.

In order to avoid stale data, all the buffers in the table are cleared before running the parser and thus any variable in the list that was not assigned a new value dureing the request will be an empty string.