Mistake on this page?
Report an issue in GitHub or email us
httpd.h
Go to the documentation of this file.
1 /**
2  * @file
3  * HTTP server
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_H
42 #define LWIP_HDR_APPS_HTTPD_H
43 
44 #include "httpd_opts.h"
45 #include "lwip/err.h"
46 #include "lwip/pbuf.h"
47 
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
51 
52 #if LWIP_HTTPD_CGI
53 
54 /**
55  * @ingroup httpd
56  * Function pointer for a CGI script handler.
57  *
58  * This function is called each time the HTTPD server is asked for a file
59  * whose name was previously registered as a CGI function using a call to
60  * http_set_cgi_handlers. The iIndex parameter provides the index of the
61  * CGI within the cgis array passed to http_set_cgi_handlers. Parameters
62  * pcParam and pcValue provide access to the parameters provided along with
63  * the URI. iNumParams provides a count of the entries in the pcParam and
64  * pcValue arrays. Each entry in the pcParam array contains the name of a
65  * parameter with the corresponding entry in the pcValue array containing the
66  * value for that parameter. Note that pcParam may contain multiple elements
67  * with the same name if, for example, a multi-selection list control is used
68  * in the form generating the data.
69  *
70  * The function should return a pointer to a character string which is the
71  * path and filename of the response that is to be sent to the connected
72  * browser, for example "/thanks.htm" or "/response/error.ssi".
73  *
74  * The maximum number of parameters that will be passed to this function via
75  * iNumParams is defined by LWIP_HTTPD_MAX_CGI_PARAMETERS. Any parameters in
76  * the incoming HTTP request above this number will be discarded.
77  *
78  * Requests intended for use by this CGI mechanism must be sent using the GET
79  * method (which encodes all parameters within the URI rather than in a block
80  * later in the request). Attempts to use the POST method will result in the
81  * request being ignored.
82  *
83  */
84 typedef const char *(*tCGIHandler)(int iIndex, int iNumParams, char *pcParam[],
85  char *pcValue[]);
86 
87 /**
88  * @ingroup httpd
89  * Structure defining the base filename (URL) of a CGI and the associated
90  * function which is to be called when that URL is requested.
91  */
92 typedef struct
93 {
94  const char *pcCGIName;
95  tCGIHandler pfnCGIHandler;
96 } tCGI;
97 
98 void http_set_cgi_handlers(const tCGI *pCGIs, int iNumHandlers);
99 
100 #endif /* LWIP_HTTPD_CGI */
101 
102 #if LWIP_HTTPD_CGI || LWIP_HTTPD_CGI_SSI
103 
104 #if LWIP_HTTPD_CGI_SSI
105 /* we have to prototype this struct here to make it available for the handler */
106 struct fs_file;
107 
108 /** Define this generic CGI handler in your application.
109  * It is called once for every URI with parameters.
110  * The parameters can be stored to the object passed as connection_state, which
111  * is allocated to file->state via fs_state_init() from fs_open() or fs_open_custom().
112  * Content creation via SSI or complete dynamic files can retrieve the CGI params from there.
113  */
114 extern void httpd_cgi_handler(struct fs_file *file, const char* uri, int iNumParams,
115  char **pcParam, char **pcValue
117  , void *connection_state
118 #endif /* LWIP_HTTPD_FILE_STATE */
119  );
120 #endif /* LWIP_HTTPD_CGI_SSI */
121 
122 #endif /* LWIP_HTTPD_CGI || LWIP_HTTPD_CGI_SSI */
123 
124 #if LWIP_HTTPD_SSI
125 
126 /**
127  * @ingroup httpd
128  * Function pointer for the SSI tag handler callback.
129  *
130  * This function will be called each time the HTTPD server detects a tag of the
131  * form <!--#name--> in files with extensions mentioned in the g_pcSSIExtensions
132  * array (currently .shtml, .shtm, .ssi, .xml, .json) where "name" appears as
133  * one of the tags supplied to http_set_ssi_handler in the tags array. The
134  * returned insert string, which will be appended after the the string
135  * "<!--#name-->" in file sent back to the client, should be written to pointer
136  * pcInsert. iInsertLen contains the size of the buffer pointed to by
137  * pcInsert. The iIndex parameter provides the zero-based index of the tag as
138  * found in the tags array and identifies the tag that is to be processed.
139  *
140  * The handler returns the number of characters written to pcInsert excluding
141  * any terminating NULL or HTTPD_SSI_TAG_UNKNOWN when tag is not recognized.
142  *
143  * Note that the behavior of this SSI mechanism is somewhat different from the
144  * "normal" SSI processing as found in, for example, the Apache web server. In
145  * this case, the inserted text is appended following the SSI tag rather than
146  * replacing the tag entirely. This allows for an implementation that does not
147  * require significant additional buffering of output data yet which will still
148  * offer usable SSI functionality. One downside to this approach is when
149  * attempting to use SSI within JavaScript. The SSI tag is structured to
150  * resemble an HTML comment but this syntax does not constitute a comment
151  * within JavaScript and, hence, leaving the tag in place will result in
152  * problems in these cases. In order to avoid these problems, define
153  * LWIP_HTTPD_SSI_INCLUDE_TAG as zero in your lwip options file, or use JavaScript
154  * style block comments in the form / * # name * / (without the spaces).
155  */
156 typedef u16_t (*tSSIHandler)(
157 #if LWIP_HTTPD_SSI_RAW
158  const char* ssi_tag_name,
159 #else /* LWIP_HTTPD_SSI_RAW */
160  int iIndex,
161 #endif /* LWIP_HTTPD_SSI_RAW */
162  char *pcInsert, int iInsertLen
163 #if LWIP_HTTPD_SSI_MULTIPART
164  , u16_t current_tag_part, u16_t *next_tag_part
165 #endif /* LWIP_HTTPD_SSI_MULTIPART */
166 #if defined(LWIP_HTTPD_FILE_STATE) && LWIP_HTTPD_FILE_STATE
167  , void *connection_state
168 #endif /* LWIP_HTTPD_FILE_STATE */
169  );
170 
171 /** Set the SSI handler function
172  * (if LWIP_HTTPD_SSI_RAW==1, only the first argument is used)
173  */
174 void http_set_ssi_handler(tSSIHandler pfnSSIHandler,
175  const char **ppcTags, int iNumTags);
176 
177 /** For LWIP_HTTPD_SSI_RAW==1, return this to indicate the tag is unknown.
178  * In this case, the webserver writes a warning into the page.
179  * You can also just return 0 to write nothing for unknown tags.
180  */
181 #define HTTPD_SSI_TAG_UNKNOWN 0xFFFF
182 
183 #endif /* LWIP_HTTPD_SSI */
184 
185 #if LWIP_HTTPD_SUPPORT_POST
186 
187 /* These functions must be implemented by the application */
188 
189 /**
190  * @ingroup httpd
191  * Called when a POST request has been received. The application can decide
192  * whether to accept it or not.
193  *
194  * @param connection Unique connection identifier, valid until httpd_post_end
195  * is called.
196  * @param uri The HTTP header URI receiving the POST request.
197  * @param http_request The raw HTTP request (the first packet, normally).
198  * @param http_request_len Size of 'http_request'.
199  * @param content_len Content-Length from HTTP header.
200  * @param response_uri Filename of response file, to be filled when denying the
201  * request
202  * @param response_uri_len Size of the 'response_uri' buffer.
203  * @param post_auto_wnd Set this to 0 to let the callback code handle window
204  * updates by calling 'httpd_post_data_recved' (to throttle rx speed)
205  * default is 1 (httpd handles window updates automatically)
206  * @return ERR_OK: Accept the POST request, data may be passed in
207  * another err_t: Deny the POST request, send back 'bad request'.
208  */
209 err_t httpd_post_begin(void *connection, const char *uri, const char *http_request,
210  u16_t http_request_len, int content_len, char *response_uri,
211  u16_t response_uri_len, u8_t *post_auto_wnd);
212 
213 /**
214  * @ingroup httpd
215  * Called for each pbuf of data that has been received for a POST.
216  * ATTENTION: The application is responsible for freeing the pbufs passed in!
217  *
218  * @param connection Unique connection identifier.
219  * @param p Received data.
220  * @return ERR_OK: Data accepted.
221  * another err_t: Data denied, http_post_get_response_uri will be called.
222  */
223 err_t httpd_post_receive_data(void *connection, struct pbuf *p);
224 
225 /**
226  * @ingroup httpd
227  * Called when all data is received or when the connection is closed.
228  * The application must return the filename/URI of a file to send in response
229  * to this POST request. If the response_uri buffer is untouched, a 404
230  * response is returned.
231  *
232  * @param connection Unique connection identifier.
233  * @param response_uri Filename of response file, to be filled when denying the request
234  * @param response_uri_len Size of the 'response_uri' buffer.
235  */
236 void httpd_post_finished(void *connection, char *response_uri, u16_t response_uri_len);
237 
238 #if LWIP_HTTPD_POST_MANUAL_WND
239 void httpd_post_data_recved(void *connection, u16_t recved_len);
240 #endif /* LWIP_HTTPD_POST_MANUAL_WND */
241 
242 #endif /* LWIP_HTTPD_SUPPORT_POST */
243 
244 void httpd_init(void);
245 
246 #if HTTPD_ENABLE_HTTPS
247 struct altcp_tls_config;
248 void httpd_inits(struct altcp_tls_config *conf);
249 #endif
250 
251 #ifdef __cplusplus
252 }
253 #endif
254 
255 #endif /* LWIP_HDR_APPS_HTTPD_H */
#define LWIP_HTTPD_FILE_STATE
Set this to 1 to include an application state argument per file that is opened.
Definition: httpd_opts.h:365
Definition: fs.h:65
Main packet buffer struct.
HTTP server options list.
lwIP Error codes
pbuf API
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.