lwIP HTTP Server

This module provides the lwIP HTTP Server integration documentation.

Overview

The LwIP HTTP Server library can be used to respond HTTP request. The documentation for the library can be found at the following link: lwIPServer.

Features

The LwIP HTTP Server:

• Can respond from HTTP GET and POST requests.
• Supports Server-Side Includes (SSI) and Common Gateway Interface (CGI).

Configuration

Build Time Configurations for Source

The following build time configurations are defined in lwip/lwip/apps/httpd_opts.h:

Configuration	Options	Default	Description
LwIP HTTPD CGI (old style)	Enabled Disabled	Disabled	Enable CGI support (old style). Use this CGI type e.g. to execute specific actions and return a page that does not depend on the CGI parameters.
LwIP HTTPD CGI SSI (new style)	Enabled Disabled	Disabled	Enable CGI support with SSI feature (new style). Use this CGI handler if you want CGI information passed on to SSI.
LwIP HTTPD SSI	Enabled Disabled	Disabled	Enable SSI support (Server-Side-Includes).
LwIP HTTPD SSI Raw	Enabled Disabled	Disabled	Enable to implement an SSI tag handler callback that gets a const char* to the tag (instead of an index into a pre-registered array of known tags).
LwIP HTTPD SSI By File Extension	Overriden Enabled Disabled	Enabled	enable/disable or override the file SSI tag scan function. You need to provide an external function to perform the check: u8_t http_uri_is_ssi(struct fs_file *file, const char *uri)
LwIP HTTPD SSI Extension	Manual Entry	".shtml", ".shtm", ".ssi", ".xml", ".json"	List of file extensions handled as SSI files. Only used if LWIP_HTTPD_SSI_BY_FILE_EXTENSION != 0.
LwIP HTTPD Support POST	Enabled Disabled	Disabled	Set this to 1 to support HTTP POST.
LwIP HTTPD Maximum CGI Parameters	Must be a non zero positive interger.	16	The maximum number of parameters that the CGI handler can be sent.
LwIP HTTPD SSI Multipart	Enabled Disabled	Disabled	SSI handler function is called with 2 more arguments to handle string too long to be inserted at once
LwIP HTTPD Maximum Tag Name Length	Must be a non zero positive interger.	8	The maximum length of the string comprising the SSI tag name. The longer tags are ignored.
LwIP HTTPD Maximum Tag Insert Length	Must be a non zero positive interger.	192	The maximum length of string that can be returned to replace any given tag.
LwIP HTTPD POST Manual WND	Enabled Disabled	Disabled	Enable configurating POST window response for HTTP server
HTTPD Server Agent	Manual Entry	lwIP/" LWIP_VERSION_STRING " (http://savannah.nongnu.org/projects/lwip)	This string is passed in the HTTP header as 'Server: HTTPD_SERVER_AGENT'.
LwIP HTTPD Dynamic Headers	Enabled Disabled	Disabled	Set this to 1 if you want to include code that creates HTTP headers at runtime. Else use static header created by the makefsdata tool.
HTTPD Debug	Disabled Enabled	Disabled	Configure debug for HTTPD file send timing
HTTPD Use Mem Pool	Enabled Disabled	Disabled	Set this to 1 to allocate http_state instead of using heap.If enabled, define MEMP_NUM_PARALLEL_HTTPD_CONNS (and MEMP_NUM_PARALLEL_HTTPD_SSI_CONNS for SSI) to set the size of the pool(s).
HTTPD Server Port	Must be an interger in range 0-65535.	80	The http server port for HTTPD to use
HTTPD Server Port HTTPS	Must be an interger in range 0-65535.	443	The https server port for HTTPD to use
HTTPD Enable HTTPS	Enabled Disabled	Disabled	Enable https support.
HTTPD Maximum Retries	Must be a positive integer.	4	Maximum retries before the connection is aborted/closed.
HTTPD Poll Interval	Must be a non zero positive interger.	4	How long the Server will keep the connection. The poll delay is X*500ms.
HTTPD TCP Priority	Must be an interger in range 1-127.	1	Priority for tcp pcbs created by HTTPD 1 by default range from 1-127.
LwIP HTTPD Timing	Enabled Disabled	Disabled	Set this to 1 to enable timing each file sent.
HTTPD Debug Timing	Disabled Enabled	Disabled	Set this to 1 to enable timing each file sent.
LwIP HTTPD Support Extstatus	Enabled Disabled	Disabled	Set this to one to show error pages when parsing request fail. Else simply close the connection
LwIP HTTPD Support V09	Enabled Disabled	Enabled	Set this to 0 to drop support for HTTP/0.9 clients (to save some bytes).
LwIP HTTPD Support 11 Keepalive	Enabled Disabled	Disabled	Set this to 1 to enable HTTP/1.1 persistent connections.
LwIP HTTPD Support Requestlist	Enabled Disabled	Enabled	Set this to 1 to support HTTP request coming in in multiple packets/pbufs.
LwIP HTTPD Request Queuelen	Must be a non zero positive interger.	5	Number of rx pbufs to enqueue to parse an incoming request.
LwIP HTTPD Request Bufsize	Must be a non zero positive interger.	LWIP_HTTPD_MAX_REQ_LENGTH	Number of (TCP payload-) bytes (in pbufs) to enqueue to parse and incoming request.
LwIP HTTPD Maximum Request Length	Must be a non zero positive interger.	LWIP_MIN(1023, (LWIP_HTTPD_REQ_QUEUELEN * PBUF_POOL_BUFSIZE))	Defines the maximum length of a HTTP request line.
LwIP HTTPD Maximum Request URI Length	Must be a positive interger.	63	This is the size of a static buffer used when URIs end with '/'.
LwIP HTTPD POST Maximum Response URI Length	Must be a non zero positive interger.	63	Maximum length of the filename to send as response to a POST request.
LwIP HTTPD SSI Include Tag	Enabled Disabled	Enabled	Set this to 0 to not send the SSI tag.
LwIP HTTPD Abort On Close Memory Error	Enabled Disabled	Disabled	Set this to 1 to call tcp_abort when tcp_close fails with memory error.
LwIP HTTPD Kill Old On Connections Exceeded	Enabled Disabled	Disabled	Set this to 1 to kill the oldest connection.
LwIP HTTPD Omit Header For Extensionless URI	Enabled Disabled	Disabled	Set this to 1 to send URIs without extension without headers.
HTTPD Limit Sending To 2mss	Enabled Disabled	Enabled	By default, the httpd is limited to send 2*pcb->mss.
HTTPD Maximum Write Length	The name function must be a valid C symbol	altcp_mss	Define this to a function that returns the maximum amount of data to enqueue. The function have this signature: u16_t fn(struct altcp_pcb* pcb);.
LwIP HTTPD Custom Files	Enabled Disabled	Disabled	Set this to 1 and provide the functions: - int fs_open_custom(struct fs_file *file, const char *name) Called first for every opened file to allow opening files that are not included in fsdata(_custom).c - void fs_close_custom(struct fs_file *file) Called to free resources allocated by fs_open_custom().
LwIP HTTPD Dynamic File Read	Enabled Disabled	Disabled	Set this to 1 to support fs_read(). Else only one-block files are supported, and the contents must be ready after fs_open().
LwIP HTTPD File State	Enabled Disabled	Disabled	Set this to 1 to include an application stateargument per file that is opened.
LwIP HTTPD File Extension	Enabled Disabled	Disabled	Set this to 1 to add the pextension field to the fs_file structure.New code should use LWIP_HTTPD_FILE_STATE instead.
HTTPD Precalculated Checksum	Enabled Disabled	Disabled	Support asynchronous read operations.
LwIP HTTPD FS Async Read	Enabled Disabled	Disabled	Set this to 1 to add the pextension field.
HTTPD Fsdata File	Manual Entry	fsdata_sample.c	Provide source name file of FS custom data. This data file will be included by fs.c file
HTTP Is Data Volatile	Allow Copy and More Allow Copy Undefined	Allow Copy	Determines if HTTP data should be copied into the TCP buffer before transmission. Allow Copy: data will be copied into memory belonging to the stack. Allow Copy and More: Notify to TCP that data will be copied into memory belonging to the stack and additional data will follow in subsequent TCP transmissions.
LwIP HTTPD Use Default Template	Enabled FSdata Generator Disabled FSdata Generator	Enabled FSdata Generator	Set this to 1 to when intent to use the default template from the generator

Usage Notes

Limitations

• In normal mode, the user must select the "HTTP Is Data Volatile" option as Allow Copy mode (TCP_WRITE_FLAG_COPY) in the FSP Configurator properties to ensure tcp_write() functions correctly.
• When using the Server-Side Includes (SSI) mode or the Common Gateway Interface (CGI) mode, make sure that the "HTTP Is Data Volatile" option is set to Allow Copy and More mode (TCP_WRITE_FLAG_COPY | TCP_WRITE_FLAG_MORE) in the FSP Configurator properties to work properly.
• TLS connection handling (HTTPS) is not currently supported.

How to use fsdata file

There are two ways to use fsdata file as follows:

1. Use the available fsdata_sample.c file

When the stack "LwIP HTTP Server" is added, by default it includes the stack "LwIP HTTP Server FS" which is the sample file provided in the LwIP HTTP Server library repository, and the fsdata_sample.c file is generated at the src/fsdata/ path.

2. Generate new fsdata.c file using makefsdata script

In case, creating a new fsdata.c file by makefsdata script, follow these detailed steps:

Note

Reffer to this link readme.txt for an introduction by the author about the makefsdata scripts.

• Setup Environment
  1. Make sure Perl is installed on your development environment to ensure the required script runs.
• Convert Server Contents to C Source Code
  1. Create a new folder. (the created folder can be placed outside the project workspace).
  2. Copy the "makefsdata" folder from the LwIP HTTP Server library repository into the created folder.
  3. Inside the created folder, create a new subfolder named "fs" (the name "fs" is mandatory).
  4. Place the files to be converted into the "fs" folder.
  5. Open a terminal on Linux or Git Bash/Windows Command Prompt on Windows. (if Cygwin is installed) and navigate to the created folder.
  6. Type the command "perl makefsdata".
  7. The new "fsdata.c" file will be generated in the created folder.
• Configure the Generated File
  1. Remove the the stack "LwIP HTTP Server FS".
  2. Add an "include guard" to prevent multiple inclusions in the new file "fsdata.c".
  3. Include the headers "lwip/apps/fs.h" and "lwip/def.h" in the new file "fsdata.c".
  4. Copy only the new file "fsdata.c" into the project workspace.
  5. In the FSP Configurator properties, set the "HTTPD Fsdata File" option to the new file "fsdata.c".

Examples

Basic Example

This is a basic example of minimal use of the LwIP HTTP Server APIs in an application.

#include "lwip/timeouts.h"
#include "lwip/init.h"
#include "lwip/ip4.h"
#include "lwip/apps/httpd.h"

/* LwIP HTTPD example */
void lwip_httpd_example () {
    struct netif netif;

    ip_addr_t ipaddr;
    ip_addr_t netmask;
    ip_addr_t gw;

    /* Initializing lwIP core. */
    lwip_init();

    /* Set ip address of the board. */
    IP4_ADDR(&ipaddr, 192, 168, 10, 4);
    IP4_ADDR(&netmask, 255, 255, 255, 0);
    IP4_ADDR(&gw, 192, 168, 10, 1);

    /* Initialize netif. Please pass rm_lwip_ether_init() function and the instance of rm_lwip_ether to netif_add(). */
    netif_add(&netif, &ipaddr, &netmask, &gw, &g_lwip_ether0_instance, rm_lwip_ether_init, netif_input);

    /* Set netif as default and enable */
    netif_set_default(&netif);
    netif_set_up(&netif);
    netif_set_link_up(&netif);

    /* Initialize the httpd */
    httpd_init();

    /* WAIT_LOOP */
    while (true)
    {
        R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_MILLISECONDS);
        sys_check_timeouts();
    }
}