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