Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
httpd_opts.h
Go to the documentation of this file.
1 /**
2  * @file
3  * HTTP server options list
4  */
5 
6 /*
7  * Copyright (c) 2001-2003 Swedish Institute of Computer Science.
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without modification,
11  * are permitted provided that the following conditions are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright notice,
14  * this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  * 3. The name of the author may not be used to endorse or promote products
19  * derived from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
22  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
23  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
24  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
26  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30  * OF SUCH DAMAGE.
31  *
32  * This file is part of the lwIP TCP/IP stack.
33  *
34  * Author: Adam Dunkels <adam@sics.se>
35  *
36  * This version of the file has been modified by Texas Instruments to offer
37  * simple server-side-include (SSI) and Common Gateway Interface (CGI)
38  * capability.
39  */
40 
41 #ifndef LWIP_HDR_APPS_HTTPD_OPTS_H
42 #define LWIP_HDR_APPS_HTTPD_OPTS_H
43 
44 #include "lwip/opt.h"
45 #include "lwip/prot/iana.h"
46 
47 /**
48  * @defgroup httpd_opts Options
49  * @ingroup httpd
50  * @{
51  */
52 
53 /** Set this to 1 to support CGI (old style).
54  *
55  * This old style CGI support works by registering an array of URLs and
56  * associated CGI handler functions (@ref http_set_cgi_handlers).
57  * This list is scanned just before fs_open is called from request handling.
58  * The handler can return a new URL that is used internally by the httpd to
59  * load the returned page (passed to fs_open).
60  *
61  * Use this CGI type e.g. to execute specific actions and return a page that
62  * does not depend on the CGI parameters.
63  */
64 #if !defined LWIP_HTTPD_CGI || defined __DOXYGEN__
65 #define LWIP_HTTPD_CGI 0
66 #endif
67 
68 /** Set this to 1 to support CGI (new style).
69  *
70  * This new style CGI support works by calling a global function
71  * (@ref tCGIHandler) for all URLs that are found. fs_open is called first
72  * and the URL can not be written by the CGI handler. Instead, this handler gets
73  * passed the http file state, an object where it can store information derived
74  * from the CGI URL or parameters. This file state is later passed to SSI, so
75  * the SSI code can return data depending on CGI input.
76  *
77  * Use this CGI handler if you want CGI information passed on to SSI.
78  */
79 #if !defined LWIP_HTTPD_CGI_SSI || defined __DOXYGEN__
80 #define LWIP_HTTPD_CGI_SSI 0
81 #endif
82 
83 /** Set this to 1 to support SSI (Server-Side-Includes)
84  *
85  * In contrast to other http servers, this only calls a preregistered callback
86  * function (@see http_set_ssi_handler) for each tag (in the format of
87  * <!--#tag-->) encountered in SSI-enabled pages.
88  * SSI-enabled pages must have one of the predefined SSI-enabled file extensions.
89  * All files with one of these extensions are parsed when sent.
90  *
91  * A downside of the current SSI implementation is that persistent connections
92  * don't work, as the file length is not known in advance (and httpd currently
93  * relies on the Content-Length header for persistent connections).
94  *
95  * To save memory, the maximum tag length is limited (@see LWIP_HTTPD_MAX_TAG_NAME_LEN).
96  * To save memory, the maximum insertion string length is limited (@see
97  * LWIP_HTTPD_MAX_TAG_INSERT_LEN). If this is not enought, @ref LWIP_HTTPD_SSI_MULTIPART
98  * can be used.
99  */
100 #if !defined LWIP_HTTPD_SSI || defined __DOXYGEN__
101 #define LWIP_HTTPD_SSI 0
102 #endif
103 
104 /** Set this to 1 to implement an SSI tag handler callback that gets a const char*
105  * to the tag (instead of an index into a pre-registered array of known tags)
106  * If this is 0, the SSI handler callback function is only called pre-registered tags.
107  */
108 #if !defined LWIP_HTTPD_SSI_RAW || defined __DOXYGEN__
109 #define LWIP_HTTPD_SSI_RAW 0
110 #endif
111 
112 /** Set this to 0 to prevent parsing the file extension at runtime to decide
113  * if a file should be scanned for SSI tags or not.
114  * Default is 1 (file extensions are checked using the g_pcSSIExtensions array)
115  * Set to 2 to override this runtime test function.
116  *
117  * This is enabled by default, but if you only use a newer version of makefsdata
118  * supporting the "-ssi" option, this info is already present in
119  */
120 #if !defined LWIP_HTTPD_SSI_BY_FILE_EXTENSION || defined __DOXYGEN__
121 #define LWIP_HTTPD_SSI_BY_FILE_EXTENSION 1
122 #endif
123 
124 /** Set this to 1 to support HTTP POST */
125 #if !defined LWIP_HTTPD_SUPPORT_POST || defined __DOXYGEN__
126 #define LWIP_HTTPD_SUPPORT_POST 0
127 #endif
128 
129 /* The maximum number of parameters that the CGI handler can be sent. */
130 #if !defined LWIP_HTTPD_MAX_CGI_PARAMETERS || defined __DOXYGEN__
131 #define LWIP_HTTPD_MAX_CGI_PARAMETERS 16
132 #endif
133 
134 /** LWIP_HTTPD_SSI_MULTIPART==1: SSI handler function is called with 2 more
135  * arguments indicating a counter for insert string that are too long to be
136  * inserted at once: the SSI handler function must then set 'next_tag_part'
137  * which will be passed back to it in the next call. */
138 #if !defined LWIP_HTTPD_SSI_MULTIPART || defined __DOXYGEN__
139 #define LWIP_HTTPD_SSI_MULTIPART 0
140 #endif
141 
142 /* The maximum length of the string comprising the SSI tag name
143  * ATTENTION: tags longer than this are ignored, not truncated!
144  */
145 #if !defined LWIP_HTTPD_MAX_TAG_NAME_LEN || defined __DOXYGEN__
146 #define LWIP_HTTPD_MAX_TAG_NAME_LEN 8
147 #endif
148 
149 /* The maximum length of string that can be returned to replace any given tag
150  * If this buffer is not long enough, use LWIP_HTTPD_SSI_MULTIPART.
151  */
152 #if !defined LWIP_HTTPD_MAX_TAG_INSERT_LEN || defined __DOXYGEN__
153 #define LWIP_HTTPD_MAX_TAG_INSERT_LEN 192
154 #endif
155 
156 #if !defined LWIP_HTTPD_POST_MANUAL_WND || defined __DOXYGEN__
157 #define LWIP_HTTPD_POST_MANUAL_WND 0
158 #endif
159 
160 /** This string is passed in the HTTP header as "Server: " */
161 #if !defined HTTPD_SERVER_AGENT || defined __DOXYGEN__
162 #define HTTPD_SERVER_AGENT "lwIP/" LWIP_VERSION_STRING " (http://savannah.nongnu.org/projects/lwip)"
163 #endif
164 
165 /** Set this to 1 if you want to include code that creates HTTP headers
166  * at runtime. Default is off: HTTP headers are then created statically
167  * by the makefsdata tool. Static headers mean smaller code size, but
168  * the (readonly) fsdata will grow a bit as every file includes the HTTP
169  * header. */
170 #if !defined LWIP_HTTPD_DYNAMIC_HEADERS || defined __DOXYGEN__
171 #define LWIP_HTTPD_DYNAMIC_HEADERS 0
172 #endif
173 
174 #if !defined HTTPD_DEBUG || defined __DOXYGEN__
175 #define HTTPD_DEBUG LWIP_DBG_OFF
176 #endif
177 
178 /** Set this to 1 to use a memp pool for allocating
179  * struct http_state instead of the heap.
180  * If enabled, you'll need to define MEMP_NUM_PARALLEL_HTTPD_CONNS
181  * (and MEMP_NUM_PARALLEL_HTTPD_SSI_CONNS for SSI) to set the size of
182  * the pool(s).
183  */
184 #if !defined HTTPD_USE_MEM_POOL || defined __DOXYGEN__
185 #define HTTPD_USE_MEM_POOL 0
186 #endif
187 
188 /** The server port for HTTPD to use */
189 #if !defined HTTPD_SERVER_PORT || defined __DOXYGEN__
190 #define HTTPD_SERVER_PORT LWIP_IANA_PORT_HTTP
191 #endif
192 
193 /** The https server port for HTTPD to use */
194 #if !defined HTTPD_SERVER_PORT_HTTPS || defined __DOXYGEN__
195 #define HTTPD_SERVER_PORT_HTTPS LWIP_IANA_PORT_HTTPS
196 #endif
197 
198 /** Enable https support? */
199 #if !defined HTTPD_ENABLE_HTTPS || defined __DOXYGEN__
200 #define HTTPD_ENABLE_HTTPS 0
201 #endif
202 
203 /** Maximum retries before the connection is aborted/closed.
204  * - number of times pcb->poll is called -> default is 4*500ms = 2s;
205  * - reset when pcb->sent is called
206  */
207 #if !defined HTTPD_MAX_RETRIES || defined __DOXYGEN__
208 #define HTTPD_MAX_RETRIES 4
209 #endif
210 
211 /** The poll delay is X*500ms */
212 #if !defined HTTPD_POLL_INTERVAL || defined __DOXYGEN__
213 #define HTTPD_POLL_INTERVAL 4
214 #endif
215 
216 /** Priority for tcp pcbs created by HTTPD (very low by default).
217  * Lower priorities get killed first when running out of memory.
218  */
219 #if !defined HTTPD_TCP_PRIO || defined __DOXYGEN__
220 #define HTTPD_TCP_PRIO TCP_PRIO_MIN
221 #endif
222 
223 /** Set this to 1 to enable timing each file sent */
224 #if !defined LWIP_HTTPD_TIMING || defined __DOXYGEN__
225 #define LWIP_HTTPD_TIMING 0
226 #endif
227 /** Set this to 1 to enable timing each file sent */
228 #if !defined HTTPD_DEBUG_TIMING || defined __DOXYGEN__
229 #define HTTPD_DEBUG_TIMING LWIP_DBG_OFF
230 #endif
231 
232 /** Set this to one to show error pages when parsing a request fails instead
233  of simply closing the connection. */
234 #if !defined LWIP_HTTPD_SUPPORT_EXTSTATUS || defined __DOXYGEN__
235 #define LWIP_HTTPD_SUPPORT_EXTSTATUS 0
236 #endif
237 
238 /** Set this to 0 to drop support for HTTP/0.9 clients (to save some bytes) */
239 #if !defined LWIP_HTTPD_SUPPORT_V09 || defined __DOXYGEN__
240 #define LWIP_HTTPD_SUPPORT_V09 1
241 #endif
242 
243 /** Set this to 1 to enable HTTP/1.1 persistent connections.
244  * ATTENTION: If the generated file system includes HTTP headers, these must
245  * include the "Connection: keep-alive" header (pass argument "-11" to makefsdata).
246  */
247 #if !defined LWIP_HTTPD_SUPPORT_11_KEEPALIVE || defined __DOXYGEN__
248 #define LWIP_HTTPD_SUPPORT_11_KEEPALIVE 0
249 #endif
250 
251 /** Set this to 1 to support HTTP request coming in in multiple packets/pbufs */
252 #if !defined LWIP_HTTPD_SUPPORT_REQUESTLIST || defined __DOXYGEN__
253 #define LWIP_HTTPD_SUPPORT_REQUESTLIST 1
254 #endif
255 
256 #if LWIP_HTTPD_SUPPORT_REQUESTLIST
257 /** Number of rx pbufs to enqueue to parse an incoming request (up to the first
258  newline) */
259 #if !defined LWIP_HTTPD_REQ_QUEUELEN || defined __DOXYGEN__
260 #define LWIP_HTTPD_REQ_QUEUELEN 5
261 #endif
262 
263 /** Number of (TCP payload-) bytes (in pbufs) to enqueue to parse and incoming
264  request (up to the first double-newline) */
265 #if !defined LWIP_HTTPD_REQ_BUFSIZE || defined __DOXYGEN__
266 #define LWIP_HTTPD_REQ_BUFSIZE LWIP_HTTPD_MAX_REQ_LENGTH
267 #endif
268 
269 /** Defines the maximum length of a HTTP request line (up to the first CRLF,
270  copied from pbuf into this a global buffer when pbuf- or packet-queues
271  are received - otherwise the input pbuf is used directly) */
272 #if !defined LWIP_HTTPD_MAX_REQ_LENGTH || defined __DOXYGEN__
273 #define LWIP_HTTPD_MAX_REQ_LENGTH LWIP_MIN(1023, (LWIP_HTTPD_REQ_QUEUELEN * PBUF_POOL_BUFSIZE))
274 #endif
275 #endif /* LWIP_HTTPD_SUPPORT_REQUESTLIST */
276 
277 /** This is the size of a static buffer used when URIs end with '/'.
278  * In this buffer, the directory requested is concatenated with all the
279  * configured default file names.
280  * Set to 0 to disable checking default filenames on non-root directories.
281  */
282 #if !defined LWIP_HTTPD_MAX_REQUEST_URI_LEN || defined __DOXYGEN__
283 #define LWIP_HTTPD_MAX_REQUEST_URI_LEN 63
284 #endif
285 
286 /** Maximum length of the filename to send as response to a POST request,
287  * filled in by the application when a POST is finished.
288  */
289 #if !defined LWIP_HTTPD_POST_MAX_RESPONSE_URI_LEN || defined __DOXYGEN__
290 #define LWIP_HTTPD_POST_MAX_RESPONSE_URI_LEN 63
291 #endif
292 
293 /** Set this to 0 to not send the SSI tag (default is on, so the tag will
294  * be sent in the HTML page */
295 #if !defined LWIP_HTTPD_SSI_INCLUDE_TAG || defined __DOXYGEN__
296 #define LWIP_HTTPD_SSI_INCLUDE_TAG 1
297 #endif
298 
299 /** Set this to 1 to call tcp_abort when tcp_close fails with memory error.
300  * This can be used to prevent consuming all memory in situations where the
301  * HTTP server has low priority compared to other communication. */
302 #if !defined LWIP_HTTPD_ABORT_ON_CLOSE_MEM_ERROR || defined __DOXYGEN__
303 #define LWIP_HTTPD_ABORT_ON_CLOSE_MEM_ERROR 0
304 #endif
305 
306 /** Set this to 1 to kill the oldest connection when running out of
307  * memory for 'struct http_state' or 'struct http_ssi_state'.
308  * ATTENTION: This puts all connections on a linked list, so may be kind of slow.
309  */
310 #if !defined LWIP_HTTPD_KILL_OLD_ON_CONNECTIONS_EXCEEDED || defined __DOXYGEN__
311 #define LWIP_HTTPD_KILL_OLD_ON_CONNECTIONS_EXCEEDED 0
312 #endif
313 
314 /** Set this to 1 to send URIs without extension without headers
315  * (who uses this at all??) */
316 #if !defined LWIP_HTTPD_OMIT_HEADER_FOR_EXTENSIONLESS_URI || defined __DOXYGEN__
317 #define LWIP_HTTPD_OMIT_HEADER_FOR_EXTENSIONLESS_URI 0
318 #endif
319 
320 /** Default: Tags are sent from struct http_state and are therefore volatile */
321 #if !defined HTTP_IS_TAG_VOLATILE || defined __DOXYGEN__
322 #define HTTP_IS_TAG_VOLATILE(ptr) TCP_WRITE_FLAG_COPY
323 #endif
324 
325 /* By default, the httpd is limited to send 2*pcb->mss to keep resource usage low
326  when http is not an important protocol in the device. */
327 #if !defined HTTPD_LIMIT_SENDING_TO_2MSS || defined __DOXYGEN__
328 #define HTTPD_LIMIT_SENDING_TO_2MSS 1
329 #endif
330 
331 /* Define this to a function that returns the maximum amount of data to enqueue.
332  The function have this signature: u16_t fn(struct altcp_pcb* pcb);
333  The best place to define this is the hooks file (@see LWIP_HOOK_FILENAME) */
334 #if !defined HTTPD_MAX_WRITE_LEN || defined __DOXYGEN__
335 #if HTTPD_LIMIT_SENDING_TO_2MSS
336 #define HTTPD_MAX_WRITE_LEN(pcb) ((u16_t)(2 * altcp_mss(pcb)))
337 #endif
338 #endif
339 
340 /*------------------- FS OPTIONS -------------------*/
341 
342 /** Set this to 1 and provide the functions:
343  * - "int fs_open_custom(struct fs_file *file, const char *name)"
344  * Called first for every opened file to allow opening files
345  * that are not included in fsdata(_custom).c
346  * - "void fs_close_custom(struct fs_file *file)"
347  * Called to free resources allocated by fs_open_custom().
348  */
349 #if !defined LWIP_HTTPD_CUSTOM_FILES || defined __DOXYGEN__
350 #define LWIP_HTTPD_CUSTOM_FILES 0
351 #endif
352 
353 /** Set this to 1 to support fs_read() to dynamically read file data.
354  * Without this (default=off), only one-block files are supported,
355  * and the contents must be ready after fs_open().
356  */
357 #if !defined LWIP_HTTPD_DYNAMIC_FILE_READ || defined __DOXYGEN__
358 #define LWIP_HTTPD_DYNAMIC_FILE_READ 0
359 #endif
360 
361 /** Set this to 1 to include an application state argument per file
362  * that is opened. This allows to keep a state per connection/file.
363  */
364 #if !defined LWIP_HTTPD_FILE_STATE || defined __DOXYGEN__
365 #define LWIP_HTTPD_FILE_STATE 0
366 #endif
367 
368 /** HTTPD_PRECALCULATED_CHECKSUM==1: include precompiled checksums for
369  * predefined (MSS-sized) chunks of the files to prevent having to calculate
370  * the checksums at runtime. */
371 #if !defined HTTPD_PRECALCULATED_CHECKSUM || defined __DOXYGEN__
372 #define HTTPD_PRECALCULATED_CHECKSUM 0
373 #endif
374 
375 /** LWIP_HTTPD_FS_ASYNC_READ==1: support asynchronous read operations
376  * (fs_read_async returns FS_READ_DELAYED and calls a callback when finished).
377  */
378 #if !defined LWIP_HTTPD_FS_ASYNC_READ || defined __DOXYGEN__
379 #define LWIP_HTTPD_FS_ASYNC_READ 0
380 #endif
381 
382 /** Filename (including path) to use as FS data file */
383 #if !defined HTTPD_FSDATA_FILE || defined __DOXYGEN__
384 /* HTTPD_USE_CUSTOM_FSDATA: Compatibility with deprecated lwIP option */
385 #if defined(HTTPD_USE_CUSTOM_FSDATA) && (HTTPD_USE_CUSTOM_FSDATA != 0)
386 #define HTTPD_FSDATA_FILE "fsdata_custom.c"
387 #else
388 #define HTTPD_FSDATA_FILE "fsdata.c"
389 #endif
390 #endif
391 
392 /**
393  * @}
394  */
395 
396 #endif /* LWIP_HDR_APPS_HTTPD_OPTS_H */
opt.h
lwIP Options Configuration
iana.h
IANA assigned numbers (RFC 1700 and successors)
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.