HTTP server
[Applications]

Function pointer for a CGI script handler.

This function is called each time the HTTPD server is asked for a file whose name was previously registered as a CGI function using a call to http_set_cgi_handlers. The iIndex parameter provides the index of the CGI within the cgis array passed to http_set_cgi_handlers. Parameters pcParam and pcValue provide access to the parameters provided along with the URI. iNumParams provides a count of the entries in the pcParam and pcValue arrays. Each entry in the pcParam array contains the name of a parameter with the corresponding entry in the pcValue array containing the value for that parameter. Note that pcParam may contain multiple elements with the same name if, for example, a multi-selection list control is used in the form generating the data.

The function should return a pointer to a character string which is the path and filename of the response that is to be sent to the connected browser, for example "/thanks.htm" or "/response/error.ssi".

The maximum number of parameters that will be passed to this function via iNumParams is defined by LWIP_HTTPD_MAX_CGI_PARAMETERS. Any parameters in the incoming HTTP request above this number will be discarded.

Requests intended for use by this CGI mechanism must be sent using the GET method (which encodes all parameters within the URI rather than in a block later in the request). Attempts to use the POST method will result in the request being ignored.

Definition at line 84 of file httpd.h.

Function pointer for the SSI tag handler callback.

This function will be called each time the HTTPD server detects a tag of the form in files with extensions mentioned in the g_pcSSIExtensions array (currently .shtml, .shtm, .ssi, .xml, .json) where "name" appears as one of the tags supplied to http_set_ssi_handler in the tags array. The returned insert string, which will be appended after the the string "<!--#name-->" in file sent back to the client, should be written to pointer pcInsert. iInsertLen contains the size of the buffer pointed to by pcInsert. The iIndex parameter provides the zero-based index of the tag as found in the tags array and identifies the tag that is to be processed.

The handler returns the number of characters written to pcInsert excluding any terminating NULL or HTTPD_SSI_TAG_UNKNOWN when tag is not recognized.

Note that the behavior of this SSI mechanism is somewhat different from the "normal" SSI processing as found in, for example, the Apache web server. In this case, the inserted text is appended following the SSI tag rather than replacing the tag entirely. This allows for an implementation that does not require significant additional buffering of output data yet which will still offer usable SSI functionality. One downside to this approach is when attempting to use SSI within JavaScript. The SSI tag is structured to resemble an HTML comment but this syntax does not constitute a comment within JavaScript and, hence, leaving the tag in place will result in problems in these cases. In order to avoid these problems, define LWIP_HTTPD_SSI_INCLUDE_TAG as zero in your lwip options file, or use JavaScript style block comments in the form / * # name * / (without the spaces).

Definition at line 156 of file httpd.h.

Insert a tag (found in an shtml in the form of "<!--#tagname-->" into the file.

The tag's name is stored in ssi->tag_name (NULL-terminated), the replacement should be written to hs->tag_insert (up to a length of LWIP_HTTPD_MAX_TAG_INSERT_LEN). The amount of data written is stored to ssi->tag_insert_len.

Parameters:

hs	http connection state

Generate the relevant HTTP headers for the given filename and write them into the supplied buffer.

Sub-function of http_send(): send dynamic headers

Returns:

: - HTTP_NO_DATA_TO_SEND: no new data has been enqueued

• HTTP_DATA_TO_SEND_CONTINUE: continue with sending HTTP body
• HTTP_DATA_TO_SEND_BREAK: data has been enqueued, headers pending, so don't send HTTP body yet
• HTTP_DATA_TO_SEND_FREED: http_state and pcb are already freed

Sub-function of http_send(): end-of-file (or block) is reached, either close the file or read the next block (if supported).

Returns:

: 0 if the file is finished or no data has been read 1 if the file is not finished and data has been read

Sub-function of http_send(): This is the normal send-routine for non-ssi files

Returns:

: - 1: data has been written (so call tcp_ouput)

• 0: no data has been written (no need to call tcp_output)

Sub-function of http_send(): This is the send-routine for ssi files

Returns:

: - 1: data has been written (so call tcp_ouput)

• 0: no data has been written (no need to call tcp_output)

Try to send more data on this pcb.

Parameters:

pcb	the pcb to send data
hs	connection state

Initialize a http connection with a file to send for an error message

Parameters:

hs	http connection state
error_nr	HTTP error number

Returns:

ERR_OK if file was found and hs has been initialized correctly another err_t otherwise

Get the file struct for a 404 error page. Tries some file names and returns NULL if none found.

Parameters:

uri	pointer that receives the actual file name URI

Returns:

file struct for the error page or NULL no matching file was found

Pass received POST body data to the application and correctly handle returning a response document or closing the connection. ATTENTION: The application is responsible for the pbuf now, so don't free it!

Parameters:

hs	http connection state
p	pbuf to pass to the application

Returns:

ERR_OK if passed successfully, another err_t if the response file hasn't been found (after POST finished)

Handle a post request. Called from http_parse_request when method 'POST' is found.

Parameters:

p	The input pbuf (containing the POST header and body).
hs	The http connection state.
data	HTTP request (header and part of body) from input pbuf(s).
data_len	Size of 'data'.
uri	The HTTP URI parsed from input pbuf(s).
uri_end	Pointer to the end of 'uri' (here, the rest of the HTTP header starts).

Returns:

ERR_OK: POST correctly parsed and accepted by the application. ERR_INPROGRESS: POST not completely parsed (no error yet) another err_t: Error parsing POST or denied by the application

A POST implementation can call this function to update the TCP window. This can be used to throttle data reception (e.g. when received data is programmed to flash and data is received faster than programmed).

Parameters:

connection	A connection handle passed to httpd_post_begin for which httpd_post_finished has *NOT* been called yet!
recved_len	Length of data received (for window update)

Try to send more data if file has been blocked before This is a callback function passed to fs_read_async().

When data has been received in the correct state, try to parse it as a HTTP request.

Parameters:

inp	the received pbuf
hs	the connection state
pcb	the altcp_pcb which received this packet

Returns:

ERR_OK if request was OK and hs has been initialized correctly ERR_INPROGRESS if request was OK so far but not fully received another err_t otherwise

Try to find the file specified by uri and, if found, initialize hs accordingly.

Parameters:

hs	the connection state
uri	the HTTP header URI
is_09	1 if the request is HTTP/0.9 (no HTTP headers in response)

Returns:

ERR_OK if file was found and hs has been initialized correctly another err_t otherwise

Initialize a http connection with a file to send (if found). Called by http_find_file and http_find_error_file.

Parameters:

hs	http connection state
file	file structure to send (or NULL if not found)
is_09	1 if the request is HTTP/0.9 (no HTTP headers in response)
uri	the HTTP header URI
tag_check	enable SSI tag checking
params	!= NULL if URI has parameters (separated by '?')

Returns:

ERR_OK if file was found and hs has been initialized correctly another err_t otherwise

The pcb had an error and is already deallocated. The argument might still be valid (if != NULL).

Data has been sent and acknowledged by the remote host. This means that more data can be sent.

The poll function is called every 2nd second. If there has been no data sent (which resets the retries) in 8 seconds, close. If the last portion of a file has not been sent in 2 seconds, close.

This could be increased, but we don't want to waste resources for bad connections.

Data has been received on this pcb. For HTTP 1.0, this should normally only happen once (if the request fits in one packet).

A new incoming connection has been accepted.

Initialize the httpd: set up a listening PCB and bind it to the defined port

Initialize the httpd: set up a listening PCB and bind it to the defined port. Also set up TLS connection handling (HTTPS).

Set the SSI handler function.

Parameters:

ssi_handler	the SSI handler function
tags	an array of SSI tag strings to search for in SSI-enabled files
num_tags	number of tags in the 'tags' array

Set an array of CGI filenames/handler functions

Parameters:

cgis	an array of CGI filenames/handler functions
num_handlers	number of elements in the 'cgis' array

Definition at line 759 of file lwip_httpd.c.

Called when a POST request has been received.

The application can decide whether to accept it or not.

Parameters:

connection	Unique connection identifier, valid until httpd_post_end is called.
uri	The HTTP header URI receiving the POST request.
http_request	The raw HTTP request (the first packet, normally).
http_request_len	Size of 'http_request'.
content_len	Content-Length from HTTP header.
response_uri	Filename of response file, to be filled when denying the request
response_uri_len	Size of the 'response_uri' buffer.
post_auto_wnd	Set this to 0 to let the callback code handle window updates by calling 'httpd_post_data_recved' (to throttle rx speed) default is 1 (httpd handles window updates automatically)

Returns:

ERR_OK: Accept the POST request, data may be passed in another err_t: Deny the POST request, send back 'bad request'.

Called when all data is received or when the connection is closed.

The application must return the filename/URI of a file to send in response to this POST request. If the response_uri buffer is untouched, a 404 response is returned.

Parameters:

connection	Unique connection identifier.
response_uri	Filename of response file, to be filled when denying the request
response_uri_len	Size of the 'response_uri' buffer.

Called for each pbuf of data that has been received for a POST.

ATTENTION: The application is responsible for freeing the pbufs passed in!

Parameters:

connection	Unique connection identifier.
p	Received data.

Returns:

ERR_OK: Data accepted. another err_t: Data denied, http_post_get_response_uri will be called.