lwIP 2.2.1 Lightweight IP stack

Macros
Options
Applications » HTTP server

## Macros
#define | LWIP_HTTPD_CGI 0
#define | LWIP_HTTPD_CGI_SSI 0
#define | LWIP_HTTPD_SSI 0
#define | LWIP_HTTPD_SSI_RAW 0
#define | LWIP_HTTPD_SSI_BY_FILE_EXTENSION 1
#define | LWIP_HTTPD_SSI_EXTENSIONS ".shtml", ".shtm", ".ssi", ".xml", ".json"
#define | LWIP_HTTPD_SUPPORT_POST 0
#define | LWIP_HTTPD_SSI_MULTIPART 0
#define | HTTPD_SERVER_AGENT "lwIP/" LWIP_VERSION_STRING " (http://savannah.nongnu.org/projects/lwip)"
#define | LWIP_HTTPD_DYNAMIC_HEADERS 0
#define | HTTPD_USE_MEM_POOL 0
#define | HTTPD_SERVER_PORT LWIP_IANA_PORT_HTTP
#define | HTTPD_SERVER_PORT_HTTPS LWIP_IANA_PORT_HTTPS
#define | HTTPD_ENABLE_HTTPS 0
#define | HTTPD_MAX_RETRIES 4
#define | HTTPD_POLL_INTERVAL 4
#define | HTTPD_TCP_PRIO TCP_PRIO_MIN
#define | LWIP_HTTPD_TIMING 0
#define | HTTPD_DEBUG_TIMING LWIP_DBG_OFF
#define | LWIP_HTTPD_SUPPORT_EXTSTATUS 0
#define | LWIP_HTTPD_SUPPORT_V09 1
#define | LWIP_HTTPD_SUPPORT_11_KEEPALIVE 0
#define | LWIP_HTTPD_SUPPORT_REQUESTLIST 1
#define | LWIP_HTTPD_REQ_QUEUELEN 5
#define | LWIP_HTTPD_REQ_BUFSIZE LWIP_HTTPD_MAX_REQ_LENGTH
#define | LWIP_HTTPD_MAX_REQ_LENGTH LWIP_MIN(1023, (LWIP_HTTPD_REQ_QUEUELEN * PBUF_POOL_BUFSIZE))
#define | LWIP_HTTPD_MAX_REQUEST_URI_LEN 63
#define | LWIP_HTTPD_POST_MAX_RESPONSE_URI_LEN 63
#define | LWIP_HTTPD_SSI_INCLUDE_TAG 1
#define | LWIP_HTTPD_ABORT_ON_CLOSE_MEM_ERROR 0
#define | LWIP_HTTPD_KILL_OLD_ON_CONNECTIONS_EXCEEDED 0
#define | LWIP_HTTPD_OMIT_HEADER_FOR_EXTENSIONLESS_URI 0
#define | HTTP_IS_TAG_VOLATILE(ptr) TCP_WRITE_FLAG_COPY
#define | LWIP_HTTPD_CUSTOM_FILES 0
#define | LWIP_HTTPD_DYNAMIC_FILE_READ 0
#define | LWIP_HTTPD_FILE_STATE 0
#define | LWIP_HTTPD_FILE_EXTENSION 0
#define | HTTPD_PRECALCULATED_CHECKSUM 0
#define | LWIP_HTTPD_FS_ASYNC_READ 0
#define | HTTPD_FSDATA_FILE "fsdata.c"

## Detailed Description

## Macro Definition Documentation

## ◆ HTTP_IS_TAG_VOLATILE

#define HTTP_IS_TAG_VOLATILE | ( |  | ptr | ) | TCP_WRITE_FLAG_COPY

Default: Tags are sent from struct http_state and are therefore volatile

## ◆ HTTPD_DEBUG_TIMING

#define HTTPD_DEBUG_TIMING LWIP_DBG_OFF

Set this to 1 to enable timing each file sent

## ◆ HTTPD_ENABLE_HTTPS

#define HTTPD_ENABLE_HTTPS 0

Enable https support?

## ◆ HTTPD_FSDATA_FILE

#define HTTPD_FSDATA_FILE "fsdata.c"

Filename (including path) to use as FS data file

## ◆ HTTPD_MAX_RETRIES

#define HTTPD_MAX_RETRIES 4

Maximum retries before the connection is aborted/closed.

- number of times pcb->poll is called -> default is 4*500ms = 2s;
- reset when pcb->sent is called

## ◆ HTTPD_POLL_INTERVAL

#define HTTPD_POLL_INTERVAL 4

The poll delay is X*500ms

## ◆ HTTPD_PRECALCULATED_CHECKSUM

#define HTTPD_PRECALCULATED_CHECKSUM 0

HTTPD_PRECALCULATED_CHECKSUM==1: include precompiled checksums for predefined (MSS-sized) chunks of the files to prevent having to calculate the checksums at runtime.

## ◆ HTTPD_SERVER_AGENT

#define HTTPD_SERVER_AGENT "lwIP/" LWIP_VERSION_STRING " (http://savannah.nongnu.org/projects/lwip)"

This string is passed in the HTTP header as "Server: "

## ◆ HTTPD_SERVER_PORT

#define HTTPD_SERVER_PORT LWIP_IANA_PORT_HTTP

The server port for HTTPD to use

## ◆ HTTPD_SERVER_PORT_HTTPS

#define HTTPD_SERVER_PORT_HTTPS LWIP_IANA_PORT_HTTPS

The https server port for HTTPD to use

## ◆ HTTPD_TCP_PRIO

#define HTTPD_TCP_PRIO TCP_PRIO_MIN

Priority for tcp pcbs created by HTTPD (very low by default). Lower priorities get killed first when running out of memory.

## ◆ HTTPD_USE_MEM_POOL

#define HTTPD_USE_MEM_POOL 0

Set this to 1 to use a memp pool for allocating struct http_state instead of the heap. If enabled, you'll need to define MEMP_NUM_PARALLEL_HTTPD_CONNS (and MEMP_NUM_PARALLEL_HTTPD_SSI_CONNS for SSI) to set the size of the pool(s).

## ◆ LWIP_HTTPD_ABORT_ON_CLOSE_MEM_ERROR

#define LWIP_HTTPD_ABORT_ON_CLOSE_MEM_ERROR 0

Set this to 1 to call tcp_abort when tcp_close fails with memory error. This can be used to prevent consuming all memory in situations where the HTTP server has low priority compared to other communication.

## ◆ LWIP_HTTPD_CGI

#define LWIP_HTTPD_CGI 0

Set this to 1 to support CGI (old style).

This old style CGI support works by registering an array of URLs and associated CGI handler functions (http_set_cgi_handlers). This list is scanned just before fs_open is called from request handling. The handler can return a new URL that is used internally by the httpd to load the returned page (passed to fs_open).

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

#define LWIP_HTTPD_CGI_SSI 0

Set this to 1 to support CGI (new style).

This new style CGI support works by calling a global function (tCGIHandler) for all URLs that are found. fs_open is called first and the URL can not be written by the CGI handler. Instead, this handler gets passed the http file state, an object where it can store information derived from the CGI URL or parameters. This file state is later passed to SSI, so the SSI code can return data depending on CGI input.

Use this CGI handler if you want CGI information passed on to SSI.

## ◆ LWIP_HTTPD_CUSTOM_FILES

#define LWIP_HTTPD_CUSTOM_FILES 0

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

#define LWIP_HTTPD_DYNAMIC_FILE_READ 0

Set this to 1 to support fs_read() to dynamically read file data. Without this (default=off), only one-block files are supported, and the contents must be ready after fs_open().

## ◆ LWIP_HTTPD_DYNAMIC_HEADERS

#define LWIP_HTTPD_DYNAMIC_HEADERS 0

Set this to 1 if you want to include code that creates HTTP headers at runtime. Default is off: HTTP headers are then created statically by the makefsdata tool. Static headers mean smaller code size, but the (readonly) fsdata will grow a bit as every file includes the HTTP header.

## ◆ LWIP_HTTPD_FILE_EXTENSION

#define LWIP_HTTPD_FILE_EXTENSION 0

Set this to 1 to add the pextension field to the fs_file structure. This is included here to retain compatibility with legacy code that relies on the presence of the pextension field. New code should use LWIP_HTTPD_FILE_STATE instead. This option may be removed in a future version of lwip.

## ◆ LWIP_HTTPD_FILE_STATE

#define LWIP_HTTPD_FILE_STATE 0

Set this to 1 to include an application state argument per file that is opened. This allows to keep a state per connection/file.

## ◆ LWIP_HTTPD_FS_ASYNC_READ

#define LWIP_HTTPD_FS_ASYNC_READ 0

LWIP_HTTPD_FS_ASYNC_READ==1: support asynchronous read operations (fs_read_async returns FS_READ_DELAYED and calls a callback when finished).

## ◆ LWIP_HTTPD_KILL_OLD_ON_CONNECTIONS_EXCEEDED

#define LWIP_HTTPD_KILL_OLD_ON_CONNECTIONS_EXCEEDED 0

Set this to 1 to kill the oldest connection when running out of memory for 'struct http_state' or 'struct http_ssi_state'. ATTENTION: This puts all connections on a linked list, so may be kind of slow.

## ◆ LWIP_HTTPD_MAX_REQ_LENGTH

#define LWIP_HTTPD_MAX_REQ_LENGTH LWIP_MIN(1023, (LWIP_HTTPD_REQ_QUEUELEN * PBUF_POOL_BUFSIZE))

Defines the maximum length of a HTTP request line (up to the first CRLF, copied from pbuf into this a global buffer when pbuf- or packet-queues are received - otherwise the input pbuf is used directly)

## ◆ LWIP_HTTPD_MAX_REQUEST_URI_LEN

#define LWIP_HTTPD_MAX_REQUEST_URI_LEN 63

This is the size of a static buffer used when URIs end with '/'. In this buffer, the directory requested is concatenated with all the configured default file names. Set to 0 to disable checking default filenames on non-root directories.

## ◆ LWIP_HTTPD_OMIT_HEADER_FOR_EXTENSIONLESS_URI

#define LWIP_HTTPD_OMIT_HEADER_FOR_EXTENSIONLESS_URI 0

Set this to 1 to send URIs without extension without headers (who uses this at all??)

## ◆ LWIP_HTTPD_POST_MAX_RESPONSE_URI_LEN

#define LWIP_HTTPD_POST_MAX_RESPONSE_URI_LEN 63

Maximum length of the filename to send as response to a POST request, filled in by the application when a POST is finished.

## ◆ LWIP_HTTPD_REQ_BUFSIZE

#define LWIP_HTTPD_REQ_BUFSIZE LWIP_HTTPD_MAX_REQ_LENGTH

Number of (TCP payload-) bytes (in pbufs) to enqueue to parse and incoming request (up to the first double-newline)

## ◆ LWIP_HTTPD_REQ_QUEUELEN

#define LWIP_HTTPD_REQ_QUEUELEN 5

Number of rx pbufs to enqueue to parse an incoming request (up to the first newline)

## ◆ LWIP_HTTPD_SSI

#define LWIP_HTTPD_SSI 0

Set this to 1 to support SSI (Server-Side-Includes)

In contrast to other http servers, this only calls a preregistered callback function (

See also
  http_set_ssi_handler) for each tag (in the format of ) encountered in SSI-enabled pages. SSI-enabled pages must have one of the predefined SSI-enabled file extensions. All files with one of these extensions are parsed when sent.

A downside of the current SSI implementation is that persistent connections don't work, as the file length is not known in advance (and httpd currently relies on the Content-Length header for persistent connections).

To save memory, the maximum tag length is limited (

See also
  LWIP_HTTPD_MAX_TAG_NAME_LEN). To save memory, the maximum insertion string length is limited (
  LWIP_HTTPD_MAX_TAG_INSERT_LEN). If this is not enough, LWIP_HTTPD_SSI_MULTIPART can be used.

## ◆ LWIP_HTTPD_SSI_BY_FILE_EXTENSION

#define LWIP_HTTPD_SSI_BY_FILE_EXTENSION 1

Set this to 0 to prevent parsing the file extension at runtime to decide if a file should be scanned for SSI tags or not. Default is 1 (file extensions are checked using the g_pcSSIExtensions array) Set to 2 to override this runtime test function. In this case, you have to provide an external function that does the check: u8_t http_uri_is_ssi(struct fs_file *file, const char *uri)

This is enabled by default, but if you only use a newer version of makefsdata supporting the "-ssi" option, this info is already present in

## ◆ LWIP_HTTPD_SSI_EXTENSIONS

#define LWIP_HTTPD_SSI_EXTENSIONS ".shtml", ".shtm", ".ssi", ".xml", ".json"

This is a list of file extensions handled as SSI files. This define is used to initialize a 'const char *const[]'. It is only used if LWIP_HTTPD_SSI_BY_FILE_EXTENSION != 0.

## ◆ LWIP_HTTPD_SSI_INCLUDE_TAG

#define LWIP_HTTPD_SSI_INCLUDE_TAG 1

Set this to 0 to not send the SSI tag (default is on, so the tag will be sent in the HTML page

## ◆ LWIP_HTTPD_SSI_MULTIPART

#define LWIP_HTTPD_SSI_MULTIPART 0

LWIP_HTTPD_SSI_MULTIPART==1: SSI handler function is called with 2 more arguments indicating a counter for insert string that are too long to be inserted at once: the SSI handler function must then set 'next_tag_part' which will be passed back to it in the next call.

## ◆ LWIP_HTTPD_SSI_RAW

#define LWIP_HTTPD_SSI_RAW 0

Set this to 1 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) If this is 0, the SSI handler callback function is only called pre-registered tags.

## ◆ LWIP_HTTPD_SUPPORT_11_KEEPALIVE

#define LWIP_HTTPD_SUPPORT_11_KEEPALIVE 0

Set this to 1 to enable HTTP/1.1 persistent connections. ATTENTION: If the generated file system includes HTTP headers, these must include the "Connection: keep-alive" header (pass argument "-11" to makefsdata).

## ◆ LWIP_HTTPD_SUPPORT_EXTSTATUS

#define LWIP_HTTPD_SUPPORT_EXTSTATUS 0

Set this to one to show error pages when parsing a request fails instead of simply closing the connection.

## ◆ LWIP_HTTPD_SUPPORT_POST

#define LWIP_HTTPD_SUPPORT_POST 0

Set this to 1 to support HTTP POST

## ◆ LWIP_HTTPD_SUPPORT_REQUESTLIST

#define LWIP_HTTPD_SUPPORT_REQUESTLIST 1

Set this to 1 to support HTTP request coming in in multiple packets/pbufs

## ◆ LWIP_HTTPD_SUPPORT_V09

#define LWIP_HTTPD_SUPPORT_V09 1

Set this to 0 to drop support for HTTP/0.9 clients (to save some bytes)

## ◆ LWIP_HTTPD_TIMING

#define LWIP_HTTPD_TIMING 0

Set this to 1 to enable timing each file sent